OS/2 Shareware BBS: 10 Tools/10-Tools.zip/cset21v1.zip/IBMCPP/HELP/DDE4CLIB.INF

OS/2 Help File | 1993-10-13 | 754KB | 27,501 lines

ΓòÉΓòÉΓòÉ 1. How to Use the Online C Library Reference ΓòÉΓòÉΓòÉ

The C/C++ Tools Online C Library Reference is a library reference guide for C
and C++ programmers.  It provides information about the C/C++ Tools
implementation of the C language library, including code examples, to enable
you to write C and C++ programs.

This document is a reference rather than a tutorial.  It assumes you are
already familiar with C programming concepts.

Information applies to the C language, but many of the functions and macros can
be called from C++ language applications

Before you begin to use this information, it would be helpful to understand how
you can:

o Expand the Contents to see all available topics
o Obtain additional information for a highlighted word or phrase
o Use action bar choices

How to Use the Contents

When the Contents window first appears, some topics have a plus (+) sign beside
them. The plus sign indicates that additional topics are available.

To expand the Contents if you are using a mouse, click on the plus sign.  If
you are using the keyboard, use the Up or Down Arrow key to highlight the
topic, and press the plus (+) key.  For example, Preprocessor Directives has a
plus sign beside it.  To see additional topics for that heading, click on the
plus sign or highlight that topic and press the plus (+) key.

To view a topic, double-click on the topic (or press the Up or Down Arrow key
to highlight the topic, and then press the Enter key).

How to Obtain Additional Information

After you select a topic, the information for that topic appears in a window.
Highlighted words or phrases indicate that additional information is available.
You will notice that certain words and phrases are highlighted in green
letters, or in white letters on a black background. These are called hypertext
terms.  If you are using a mouse, double-click on the highlighted word.  If you
are using a keyboard, press the Tab key to move to the highlighted word, and
then press the Enter key.  Additional information then appears in a window.

How to Use Action Bar Choices

Several choices are available for managing information presented in the
C/C++Tools Online Language Reference. There are three pull-down menus on the
action bar:  the Services menu, the Options menu, and the Help menu.

The actions that are selectable from the Services menu operate on the active
window currently displayed on the screen. These actions include the following:

Bookmark
  Allows you to set a placeholder so you can retrieve information of interest
  to you.

  When you place a bookmark on a topic, it is added to a list of bookmarks you
  have previously set.  You can view the list, and you can remove one or all
  bookmarks from the list.  If you have not set any bookmarks, the list is
  empty.

  To set a bookmark, do the following:

    1. Select a topic from the Contents.
    2. When that topic appears, choose the Bookmark option from the Services
       pull-down.
    3. If you want to change the name used for the bookmark, type the new name
       in the field.
    4. Click on the Place radio button (or press the Up or Down Arrow key to
       select it).
    5. Click on OK (or select it and press Enter). The bookmark is then added
       to the bookmark list.
Search
  Allows you to find occurrences of a word or phrase in the current topic,
  selected topics, or all topics.

  You can specify a word or phrase to be searched.  You can also limit the
  search to a set of topics by first marking the topics in the Contents list.

  To search for a word or phrase in all topics, do the following:

    1. Choose the Search option from the Services pull-down.
    2. Type the word or words to be searched for.
    3. Click on All sections (or press the

               Up or Down Arrow keys to select it).

    4. Click on Search (or select it and press Enter) to begin the search.
    5. The list of topics where the word or phrase appears is displayed.
Print
  Allows you to print one or more topics. You can also print a set of topics by
  first marking the topics in the Contents list.

  To print the document Contents list, do the following:

    1. Choose Print from the Services pull-down.
    2. Click on Contents (or press the Up or Down Arrow key to select it).
    3. Click on Print (or select it and press Enter).
    4. The Contents list is printed on your printer.
Copy
  Allows you to copy a topic that you are viewing to the System Clipboard or to
  a file that you can edit. This is particularly useful for copying syntax
  definitions and program samples into the application that you are developing.

  You can copy a topic that you are viewing in two ways:

   o Copy copies the topic that you are viewing into the System Clipboard.  If
     you are using a Presentation Manager* (PM) editor (for example, the
     Enhanced Editor) that copies or cuts (or both) to the System Clipboard,
     and pastes to the System Clipboard, you can easily add the copied
     information to your program source module.

   o Copy to file copies the topic that you are viewing into a temporary file
     named TEXT.TMP.  You can later edit that file by using any editor.
     TEXT.TMP is placed in the directory where your viewable document resides.

  To copy a topic, do the following:

    1. Expand the Contents list and select a topic.
    2. When the topic appears, choose Copy to file from the Services pull-down.
    3. The system puts the text pertaining to that topic into the temporary
       file TEXT.TMP.

  For information on any of the choices in the Services pull-down, highlight
  the choice and press the F1 key.

  The actions that are selectable from the Options menu allow you to change the
  way your Contents list is displayed. To expand the Contents and show all
  levels for all topics, choose Expand all from the Options pull-down. You can
  also press the Ctrl and * keys together.

  For information on any of the choices in the Options pull-down, highlight the
  choice and press the F1 key.

  The actions that are selectable from the Help menu allow you to select
  different types of help information. You can also press the F1 key for help
  information about the Information Presentation Facility (IPF).


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Copyright
o Edition Notice
o Notices
o Trademarks and Service Marks


ΓòÉΓòÉΓòÉ 1.1. Copyright ΓòÉΓòÉΓòÉ

Copyright International Business Machines Corporation, 1993. All rights
reserved.

Note to U.S. Government Users - Documentation related to restricted rights -
Use, duplication, or disclosure is subject to restrictions set forth in GSA ADP
Schedule Contract with IBM* Corp.


ΓòÉΓòÉΓòÉ 1.2. Edition Notice ΓòÉΓòÉΓòÉ

Second Edition, November 1993.

This edition applies to Version 2.01 of IBM C/C++ Tools (82G3733, 82G3735,
82G3736) and to all subsequent releases and modifications until otherwise
indicated in new editions.  This publication could include technical
inaccuracies or typographical errors.  Changes are periodically made to the
information herein; any such changes will be reported in subsequent revisions.

Requests for publications and for technical information about IBM* products
should be made to your IBM Authorized Dealer or your IBM Marketing
Representative.

When you send information to IBM, you grant IBM a nonexclusive right to use or
distribute the information in any ways it believes appropriate without
incurring any obligation to you.


ΓòÉΓòÉΓòÉ 1.3. Notices ΓòÉΓòÉΓòÉ

References in this publication to IBM* products, programs, or services do not
imply that IBM intends to make these available in all countries in which IBM
operates. Any reference to an IBM product, program, or service is not intended
to state or imply that only IBM's product, program, or service may be used. Any
functionally equivalent product, program, or service that does not infringe any
of IBM's intellectual property rights may be used instead of the IBM product,
program, or service. Evaluation and verification of operation in conjunction
with other products, programs, or services, except those expressly designated
by IBM, are the user's responsibility.

IBM may have patents or pending patent applications covering subject matter in
this document.  The furnishing of this document does not give you any license
to these patents.  You can send license inquiries, in writing, to the IBM
Director of Commercial Relations, IBM Corporation, Purchase, NY 10577.


ΓòÉΓòÉΓòÉ 1.4. Trademarks and Service Marks ΓòÉΓòÉΓòÉ

The following terms, denoted by an asterisk (*) in this publication, are
trademarks or service marks of IBM* Corporation in the United States or other
countries:

C/2
C Set/2
C Set ++
Common User Access
CUA
IBM
Operating System/2
OS/2
Personal System/2
Presentation Manager
PS/2
SAA
Systems Application Architecture
WorkFrame/2

The following terms, denoted by a double asterisk (**) in this publication, are
trademarks of another county as follows:

AT&T      AT&T Corporation


ΓòÉΓòÉΓòÉ <hidden> IBM Trademark ΓòÉΓòÉΓòÉ

Trademark of the IBM Corporation.


ΓòÉΓòÉΓòÉ <hidden> Non-IBM Trademarks ΓòÉΓòÉΓòÉ

AT&T is a trademark of AT&T Corporation.


ΓòÉΓòÉΓòÉ 2. The C Library ΓòÉΓòÉΓòÉ

This section summarizes the available C library functions. Each library
function is listed according to the type of function it performs.

o Error Handling
o Process Control
o File and Directory Management
o Searching and Sorting
o Mathematical
o Floating-Point Unit Control
o Time Manipulation
o Type Conversion
o Stream Input/Output
o Low-Level Input/Output
o Handling Argument Lists
o Pseudorandom Numbers
o Dynamic Memory Management
o Memory Objects
o Environment Interaction
o String Operations
o Character Testing
o Character Case Mapping
o Multibyte Character Manipulation
o C/C++ Tools Extensions
o Intrinsic Functions


ΓòÉΓòÉΓòÉ 2.1. Error Handling ΓòÉΓòÉΓòÉ

o assert  - Verify Condition
o atexit  - Record Program Termination Function
o _matherr - Process Math Library Errors
o perror  - Print Error Message
o raise  - Send Signal
o _set_crt_msg_handle - Change Runtime Message Output Handle
o signal Install Interrupt Handlers
o strerror  - Set Pointer to Runtime Error Message
o _strerror - Set Pointer to System Error String


ΓòÉΓòÉΓòÉ 2.2. Process Control ΓòÉΓòÉΓòÉ

o _beginthread - Create New Thread
o _cwait - Wait for Child Process
o _disable - Disable Interrupts
o _enable - Enable Interrupts
o _endthread - Terminate Current Thread
o _execl - _execvp - Load and Run Child Process
o _exit - End Process
o _freemod - Free User DLL
o _getpid - Get Process Identifier
o _getTIBvalue - Get TIB Value
o _interrupt - Call Interrupt  Procedure
o _loadmod - Load User DLL
o _onexit - Record Termination Function
o _putenv - Modify Environment Variables
o _searchenv - Search for File
o _spawnl -_spawnvpe -Start and Run Child Processes
o _threadstore - Access Thread-Specific Storage


ΓòÉΓòÉΓòÉ 2.3. File and Directory Management ΓòÉΓòÉΓòÉ

o _chdir - Change Current Working Directory
o _chdrive - Change Current Working Drive
o _fstat - Information about Open File
o _fullpath - Get Full Path Name of Partial Path
o _getcwd - Get Path Name of Current Directory
o _getdcwd - Get Full Path Name of Current Directory
o _getdrive - Get Current Working Drive
o _makepath - Create Path
o _mkdir - Create New Directory
o _rmdir - Remove Directory
o _splitpath - Decompose Path Name
o _stat - Get Information about File or Directory


ΓòÉΓòÉΓòÉ 2.4. Searching and Sorting ΓòÉΓòÉΓòÉ

o bsearch  - Search Arrays
o _lfind - _lsearch - Find Key in Array
o _lfind - _lsearch - Find Key in Array
o qsort  - Sort Array


ΓòÉΓòÉΓòÉ 2.5. Mathematical ΓòÉΓòÉΓòÉ

o abs  - Calculate Integer Absolute Value
o acos  - Calculate Arccosine
o asin  - Calculate Arcsine
o atan - atan2  - Calculate Arctangent
o _cabs - Calculate Absolute Value of Complex Number
o ceil - Integer >= Argument
o cos  - Calculate Cosine
o cosh  - Calculate Hyperbolic Cosine
o div  - Calculate Quotient and Remainder
o erf  - Calculate Error Functions
o exp  - Exponential Function
o fabs  - Calculate Floating-Point Absolute Value
o _facos - Calculate Arccosine
o _fasin - Calculate Arcsine
o _fcos - Calculate Cosine
o _fcossin - Calculate Cosine and Sine
o floor - Integer <= Argument
o fmod  - Floating-Point Remainder
o _fpatan - Calculate Arctangent
o _fptan - Calculate Tangent
o frexp  - Separate Floating-Point Value
o _fsin - Calculate Sine
o _fsincos - Calculate Sine and Cosine
o _fsqrt -  Calculate Square Root
o _fyl2x - Calculate y * log2(x)
o _fyl2xp1 -  Calculate y * log2(x + 1)
o _f2xm1 -  Calculate (2**x) - 1
o gamma  - Gamma Function
o hypot  - Calculate Hypotenuse
o labs  - Calculate long Absolute Value
o ldexp  - Multiply by a Power of Two
o ldiv  - Long Division
o log  - Calculate Natural Logarithm
o log10  - Calculate Base 10 Logarithm
o _lrotl - _lrotr - Rotate Bits
o _lrotl - _lrotr - Rotate Bits
o max - Return Larger of Two Values
o min - Return Lesser of Two Values
o modf  - Separate Floating-Point Value
o pow  - Compute Power
o _rotl - _rotr - Bit Rotation
o _rotl - _rotr - Bit Rotation
o sin  - Calculate Sine
o sinh  - Calculate Hyperbolic Sine
o sqrt  - Calculate Square Root
o tan  - Calculate Tangent
o tanh  - Calculate Hyperbolic Tangent
o Bessel Functions


ΓòÉΓòÉΓòÉ 2.6. Floating-Point Unit Control ΓòÉΓòÉΓòÉ

o _clear87 - Clear Floating-Point Status Word
o _control87 - Set Floating-Point Status Word
o _fpreset - Reset Floating-Point Unit
o _status87 - Get Floating-Point Status Word


ΓòÉΓòÉΓòÉ 2.7. Time Manipulation ΓòÉΓòÉΓòÉ

o asctime  - Convert Time
o clock  - Determine Processor Time
o ctime  - Convert Time
o difftime  - Compute Time Difference
o _ftime - Store Current Time
o gmtime  - Convert Time
o localtime  - Convert Time
o mktime  - Convert Local Time
o _strdate - Copy Current Date
o strftime  - Convert to Formatted Time
o _strtime - Copy Time
o time  - Determine Current Time
o _tzset - Assign Values to Locale Information
o _utime - Set Modification Time


ΓòÉΓòÉΓòÉ 2.8. Type Conversion ΓòÉΓòÉΓòÉ

o atof  - Convert Character Strings
o atoi  - Convert Character Strings
o atol  - Convert Character Strings
o _atold - Convert ASCII String to Long Double
o _ecvt - Convert Floating-Point to Character
o _fcvt - Convert Floating-Point to String
o _gcvt - Convert Floating-Point to String
o _itoa - Convert Integer to String
o _ltoa - Convert Long Integer to String
o strtod  - Convert Character String to Numeric
o strtol  - Convert Character String to Numeric
o strtold - Convert String to Long Double
o strtoul  - Convert String Segment to Unsigned Integer
o _ultoa - Convert Unsigned Long Integer to String


ΓòÉΓòÉΓòÉ 2.9. Stream Input/Output ΓòÉΓòÉΓòÉ

Formatted Input/Output

o fprintf  - Write Formatted Data
o fscanf  - Read Formatted Data
o printf  - Formatted Print
o scanf  - Read Data
o sprintf  - Formatted Print to Buffer
o sscanf  - Read Data
o vfprintf  - Print Argument Data
o vprintf  - Print Argument Data
o vsprintf  - Print Argument Data

Character and String Input/Output

o fgetc  - Read a Character
o _fgetchar - Read Single Character from stdin
o fgets  - Read a String
o fputc  - Write a Character
o _fputchar - Write Character
o fputs  - Print Strings
o getc  - Read a Character
o gets  - Read a Line
o putc - putchar  - Write a Character
o putc - putchar  - Write a Character
o puts  - Write a String
o ungetc  - Push Character onto Input Stream

Direct Input/Output

o clearerr  - Reset Error Indicators
o feof  - Test End-of-File Indicator
o ferror  - Test for Read/Write Errors
o fread  - Read Items
o fwrite  - Write Items

File Positioning

o fgetpos  - Get File Position
o fseek  - Reposition File Position
o fsetpos  - Set File Position
o ftell  - Get Current Position
o _lseek - Move File Pointer
o rewind  - Adjust Current File Position

File Access

o fclose  - Close Stream
o _fcloseall - Close All Open Streams
o _fdopen - Associates Input Or Output With File
o fflush  - Write Buffer to File
o _flushall - Write Buffers to Files
o fopen  - Open Files
o freopen  - Redirect Open Files
o setbuf  - Control Buffering
o _setmode - Set File Translation Mode
o setvbuf  - Control Buffering

File Operations

o _fileno - Determine File Handle
o remove  - Delete File
o rename  - Rename File
o _rmtmp - Remove Temporary Files
o _tempnam - Produce Temporary File Name
o tmpfile  - Create Temporary File
o tmpnam  - Produce Temporary File Name
o _unlink - Delete File


ΓòÉΓòÉΓòÉ 2.10. Low-Level Input/Output ΓòÉΓòÉΓòÉ

o _inp - Read Byte from Input Port
o _inpd - Read Double Word from Input Port
o _inpw - Read Unsigned Short from Input Port
o _outp - Write Byte to Output Port
o _outpd - Write Double Word to Output Port
o _outpw - Write Word to Output Port
o _umask - Sets File Mask of Current Process

Character and String Input/Output

o _cgets - Read String of Characters from Keyboard
o _cprintf - Print Characters to Screen
o _cputs - Write String to Screen
o _cscanf - Read Data from Keyboard
o _getch - _getche - Read Character from Keyboard
o _kbhit - Test for Keystroke
o _putch - Write Character to Screen
o _ungetch - Push Character Back to Keyboard

File Positioning

o __eof - Determine End of File
o _tell - Get Pointer Position

File Access

o _access - Determine Access Mode
o _chmod - Change File Permission Setting
o _close - Closes File Associated with Handle
o _creat - Create New File
o _dup -Associate Second Handle with Open File
o _dup2 -Associate Second Handle with Open File
o _isatty - Test Handle for Character Device
o _open - Open File
o _read - Read Into Buffer
o _sopen - Open Shared File
o _read - Read Into Buffer

File Operations

o _chsize - Alter Length of File
o _filelength - Determine File Length


ΓòÉΓòÉΓòÉ 2.11. Handling Argument Lists ΓòÉΓòÉΓòÉ

o va_arg - va_end - va_start - Access Function Arguments


ΓòÉΓòÉΓòÉ 2.12. Pseudorandom Numbers ΓòÉΓòÉΓòÉ

o rand  - Generate Random Number
o srand  - Set Seed for rand Function


ΓòÉΓòÉΓòÉ 2.13. Dynamic Memory Management ΓòÉΓòÉΓòÉ

o _alloca - Temporarily Reserve Storage Block
o calloc  - Reserve and Initialize Storage
o _debug_calloc - Reserve and Initialize Storage
o _debug_free - Release Storage Blocks
o _debug_heapmin - Release Unused Memory in the Heap
o _debug_malloc - Reserve Storage Blocks
o _debug_realloc - Change Reserved Storage Block Size
o _dump_allocated - Get Information about Allocated Storage
o free  - Release Storage Blocks
o _heap_check - Validate Run-Time Storage Heap
o _heapmin - Release Unused Memory in the Heap
o malloc  - Reserve Storage Block
o _heap_check - Validate Run-Time Storage Heap
o realloc  - Change Reserved Storage Block Size
o _tcalloc - Reserve Tiled Storage Block
o _tfree - Free Tiled Storage Block
o _tmalloc - Reserve Tiled Storage Block
o _trealloc - Reallocate Tiled Storage Block


ΓòÉΓòÉΓòÉ 2.14. Memory Objects ΓòÉΓòÉΓòÉ

o memccpy - Copy Bytes
o memchr  - Search Buffer
o memcmp  - Compare Buffers
o memcpy  - Copy Bytes
o memicmp - Compare Bytes
o memmove  - Copy Bytes
o memset  - Set Bytes to Value
o _swab - Swap Adjacent Bytes


ΓòÉΓòÉΓòÉ 2.15. Environment Interaction ΓòÉΓòÉΓòÉ

o abort  - Stop a Program
o exit  - End Program
o getenv  - Search for Environment Variables
o localeconv  - Query Locale Conventions
o longjmp  - Restore Stack Environment
o __parmdwords - Get Number of dwords in Parameter List
o setjmp  - Preserve Environment
o setlocale  - Set Locale
o system - Invoke the Command Processor


ΓòÉΓòÉΓòÉ 2.16. String Operations ΓòÉΓòÉΓòÉ

o strcat  - Concatenate Strings
o strchr  - Search for Character
o strcmp  - Compare Strings
o strcmpi - Compare Strings
o strcoll  - Compare Strings
o strcpy  - Copy Strings
o strcspn  - Compare Strings
o strdup - Duplicate String
o stricmp - Compare Strings
o strlen  - Determine String Length
o strncat  - Concatenate Strings
o strncmp  - Compare Strings
o strncpy  - Copy Strings
o strnicmp - Compare Strings
o strnset - strset - Set Characters in String
o strpbrk  - Find Characters in String
o strrchr  - Find Last Occurrence of Character in String
o strrev - Reverse String
o strnset - strset - Set Characters in String
o strspn  - Search Strings
o strstr  - Locate Substring
o strtok  - Tokenize String
o strxfrm  - Transform Strings


ΓòÉΓòÉΓòÉ 2.17. Character Testing ΓòÉΓòÉΓòÉ

o isalnum to isxdigit  - Test Integer Value
o _isascii - Test Integer Values
o _iscsym - _iscsymf - Test Integer
o _iscsym - _iscsymf - Test Integer


ΓòÉΓòÉΓòÉ 2.18. Character Case Mapping ΓòÉΓòÉΓòÉ

o strlwr - Convert Uppercase to Lowercase
o strupr - Convert Lowercase to Uppercase
o tolower - toupper  - Convert Character Case
o tolower - toupper  - Convert Character Case
o tolower - toupper  - Convert Character Case
o tolower - toupper  - Convert Character Case


ΓòÉΓòÉΓòÉ 2.19. Multibyte Character Manipulation ΓòÉΓòÉΓòÉ

o mblen  - Multibyte String Length
o mbstowcs  - Convert Multibyte Characters to wchar_t Characters
o mbtowc  - Convert Multibyte Character to wchar_t
o wctomb  - Convert wchar_t Character to Multibyte Character
o wcstombs  - Convert wchar_t String to Multibyte Character String
o wcscat  - Append wchar_t Strings
o wcschr  - Search wchar_t String for Given wchar_t
o wcscmp  - Compare wchar_t Strings
o wcscpy  - Copy wchar_t Strings
o wcscspn  - Find Offset of First wchar_t Match
o wcslen  - Calculate Length of wchar_t String
o wcsncat  - Concatenate wchar_t Strings
o wcsncmp  - Compare wchar_t Strings
o wcsncpy  - Copy wchar_t Strings
o wcspbrk  - Locate wchar_t Characters in String
o wcsspn  - Search wchar_t Characters in String
o wcsrchr  - Locate wchar_t Character in String
o wcswcs  - Locate wchar_t Substring in wchar_t String


ΓòÉΓòÉΓòÉ 2.20. C/C++ Tools Extensions ΓòÉΓòÉΓòÉ

o _access - Determine Access Mode
o _alloca - Temporarily Reserve Storage Block
o _atold - Convert ASCII String to Long Double
o _beginthread - Create New Thread
o _cabs - Calculate Absolute Value of Complex Number
o _cgets - Read String of Characters from Keyboard
o _chdir - Change Current Working Directory
o _chdrive - Change Current Working Drive
o _chmod - Change File Permission Setting
o _chsize - Alter Length of File
o _clear87 - Clear Floating-Point Status Word
o _close - Closes File Associated with Handle
o _control87 - Set Floating-Point Status Word
o _cprintf - Print Characters to Screen
o _cputs - Write String to Screen
o _creat - Create New File
o _cscanf - Read Data from Keyboard
o _cwait - Wait for Child Process
o _dup -Associate Second Handle with Open File
o _dup2 -Associate Second Handle with Open File
o _ecvt - Convert Floating-Point to Character
o _endthread - Terminate Current Thread
o __eof - Determine End of File
o _execl - _execvp - Load and Run Child Process
o _exit - End Process
o _fcloseall - Close All Open Streams
o _fcvt - Convert Floating-Point to String
o _fdopen - Associates Input Or Output With File
o _filelength - Determine File Length
o _fileno - Determine File Handle
o _flushall - Write Buffers to Files
o _fpreset - Reset Floating-Point Unit
o _fputchar - Write Character
o _freemod - Free User DLL
o _fstat - Information about Open File
o _ftime - Store Current Time
o _fullpath - Get Full Path Name of Partial Path
o _gcvt - Convert Floating-Point to String
o _getch - _getche - Read Character from Keyboard
o _getcwd - Get Path Name of Current Directory
o _getdcwd - Get Full Path Name of Current Directory
o _getdrive - Get Current Working Drive
o _getpid - Get Process Identifier
o _heapmin - Release Unused Memory in the Heap
o _isascii - Test Integer Values
o _isatty - Test Handle for Character Device
o _iscsym - _iscsymf - Test Integer
o _itoa - Convert Integer to String
o _kbhit - Test for Keystroke
o _lfind - _lsearch - Find Key in Array
o _loadmod - Load User DLL
o _lrotl - _lrotr - Rotate Bits
o _lseek - Move File Pointer
o _ltoa - Convert Long Integer to String
o _makepath - Create Path
o _matherr - Process Math Library Errors
o max - Return Larger of Two Values
o memccpy - Copy Bytes
o memicmp - Compare Bytes
o min - Return Lesser of Two Values
o _mkdir - Create New Directory
o _msize - Return Number of Bytes Allocated
o _onexit - Record Termination Function
o _open - Open File
o __parmdwords - Get Number of dwords in Parameter List
o _putch - Write Character to Screen
o _putenv - Modify Environment Variables
o _read - Read Into Buffer
o _rmdir - Remove Directory
o _rmtmp - Remove Temporary Files
o _rotl - _rotr - Bit Rotation
o _searchenv - Search for File
o _setmode - Set File Translation Mode
o signal Install Interrupt Handlers
o _sopen - Open Shared File
o spawnl - spawnvpe - Start and Run Child Processes
o _splitpath - Decompose Path Name
o _stat - Get Information about File or Directory
o _status87 - Get Floating-Point Status Word
o strcmpi - Compare Strings
o _strdate - Copy Current Date
o strdup - Duplicate String
o _strerror - Set Pointer to System Error String
o stricmp - Compare Strings
o strlwr - Convert Uppercase to Lowercase
o strnicmp - Compare Strings
o strnset - strset - Set Characters in String
o strrev - Reverse String
o _strtime - Copy Time
o strtold - Convert String to Long Double
o strupr - Convert Lowercase to Uppercase
o _swab - Swap Adjacent Bytes
o system - Invoke the Command Processor
o _tell - Get Pointer Position
o _tempnam - Produce Temporary File Name
o _toascii - _tolower - _toupper - Convert Character
o _tzset - Assign Values to Locale Information
o _ultoa - Convert Unsigned Long Integer to String
o _umask - Sets File Mask of Current Process
o _ungetch - Push Character Back to Keyboard
o _unlink - Delete File
o _utime - Set Modification Time
o _wait - Wait for Child Process
o _write - Writes from Buffer to File


ΓòÉΓòÉΓòÉ 2.21. Intrinsic Functions ΓòÉΓòÉΓòÉ

When optimization is on, the C/C++ Tools compiler by default generates code
instead of a function call for the following C library functions:

abs                 _clear87
_control87          fabs
labs                memchr
memcmp              memcpy
memmove             memset
_status87           strcat
strchr              strcmp
strcpy              strlen
strncat             strncmp
strncpy             strrchr

When you #include the appropriate header file in which the function prototype
and the #define and #pragma statements for the function are found, the
C/C++Tools compiler generates code instead of a function call for these
functions.

You can override the header either by undefining the macro or by placing the
name of the function in parentheses, thus disabling the processor substitution.
The function then remains a function call, and is not replaced by the code. The
size of your object module is reduced, but your application program runs more
slowly.

Note:  The following functions are built-in functions, meaning they do not have
       any backing library functions, and are always inlined:

_alloca             _disable
_enable             _facos
_fasin              _fcos
_fcossin            _fpatan
_fptan              _fsin
_fsincos            _fyl2x
_fyl2xp1            _f2xm1
_getTIBvalue        _inp
_inpd               _inpw
_interrupt          _outp
_outpd              _outpw
__parmdwords

The built-in functions are all defined in <builtin.h>, in addition to the
standard header definitions.


ΓòÉΓòÉΓòÉ 3. Memory Management Functions ΓòÉΓòÉΓòÉ

This section describes two types of memory management functions:

o Debug Memory Management Functions
o Tiled Memory Management Functions
These functions are extensions to the ANSI/SAA memory management functions that
you can use.

A brief description is provided for each function, as well as a description of
how the functions are invoked and used.


ΓòÉΓòÉΓòÉ 3.1. Debug Memory Management Functions ΓòÉΓòÉΓòÉ

The C/C++ Tools compiler provides a set of seven functions to assist you in
debugging memory management problems associated with memory allocated by the
calloc, malloc, or realloc functions. The debug memory management functions are
provided in both the standard and subsystem development libraries, and can help
you find where memory is being allocated, written to, or freed incorrectly.

This section describes the following debug memory management functions:

o _debug_calloc, _debug_free, _debug_heapmin, _debug_malloc, _debug_realloc

  These functions are variations of the calloc, free, _heapmin, malloc, and
  realloc functions respectively. They build internal data structures to allow
  checks to be made on the run-time heap. Each call to one of these functions
  also automatically calls the _heap_check function.

o _heap_check

  This function checks all memory blocks allocated or freed by the functions
  listed above to make sure that no overwriting has occurred outside the bounds
  of allocated blocks or in a free memory block.

o _dump_allocated

  This function prints out information about each memory block currently
  allocated by the functions listed above.

All output from these functions is sent to the OS/2 file handle 2, which is
usually associated with stderr.

Note:  The information provided by these functions is Diagnosis, Modification,
       and Tuning information only. It is not intended to be used as a
       programming interface.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Using the Debug Memory Management Functions
o Library Functions
o Tiled Memory Management Functions


ΓòÉΓòÉΓòÉ 3.1.1. Using the Debug Memory Management Functions ΓòÉΓòÉΓòÉ

To use the debug memory management functions:

 1. Define the macro __DEBUG_ALLOC__

    This macro defines the malloc, calloc, realloc, free, and _heapmin
    functions to the corresponding debug memory management function. You can
    define the macro in your source files, or on the command line (using the /D
    option).

 2. Include <stdlib.h> in each of your source files.

    If you define __DEBUG_ALLOC__ in your source file, that definition must
    appear before the #include directive.

 3. Place a #pragma strings(readonly) directive at the top of each source file.

    This directive is not essential, but it ensures that the file name passed
    to the debug memory management functions cannot be overwritten, and that
    only one copy of the file name string is included in the object module.

Once you have followed the above steps, the _debug_malloc, _debug_calloc,
_debug_realloc, _debug_free, and _debug_heapmin functions are automatically
called in place of the regular memory management functions in your code. Do not
parenthesize any calls to these functions, because parentheses will disable the
definition of the function name to the debug function name.

The _heap_check function is also called automatically by each of these
functions, or you can call it explicitly. To use the _dump_allocated function,
you must explicitly call it in your code.

Note:

o To use the debug memory management functions, set the language level to
  extended. Specify the /Se option on the command line, or include the #pragma
  langlvl(extended) directive in your code.
o The debug memory management functions are not available if you are using
  tiled memory (with the /Gt compiler option).
o All memory blocks allocated by the _debug_malloc, _debug_calloc, and
  _debug_realloc functions must be freed using _debug_free, not the free
  function. If you do not use _debug_free, a message is generated and the
  process terminates. To ensure that _debug_free is used, define the
  __DEBUG_ALLOC__ macro in all your modules.
o If you copy the examples from the online help and compile and run them, the
  format of the output you will see will be the same as that shown in the
  sample output, but the values may be different.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o #define
o #include
o malloc.h
o stdlib.h
o #pragma langlvl
o #pragma strings
o /D option
o /Gt option
o Debug Memory Management Functions
o Tiled Memory Management Functions


ΓòÉΓòÉΓòÉ 3.2. Tiled Memory Management Functions ΓòÉΓòÉΓòÉ

The C/C++ Tools compiler provides a set of four functions to allow you to
manipulate tiled memory. These functions are the 16-bit versions of the
C/C++Tools memory functions.

This section describes the following tiled memory functions:

o _tcalloc, _tfree, _tmalloc, _trealloc.

  These functions are variations of the calloc, free, malloc, and realloc
  functions, respectively. They work exactly like the original functions,
  except that the memory allocated or freed is guaranteed not to cross 64K
  boundaries, allowing object to be used in 16-bit programs.

The tiled memory functions should be used if you have applications that depend
on APIs or subroutines that are only available as 16-bit code.

Note:  Data items larger than 64K in size can be allocated. They will be
aligned on 64K boundaries, but they will also cross 64K boundaries.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Using the Tiled Memory Functions
o Library Functions


ΓòÉΓòÉΓòÉ 3.2.1. Using the Tiled Memory Functions ΓòÉΓòÉΓòÉ

To use the tiled memory management functions:

 1. Define the macro __TILED__ in your code.

    This macro defines the malloc, calloc, free, and realloc functions to the
    corresponding tiled memory function. You can also define the macro on your
    command line by setting the /Gt+ compiler option.

 2. Include <stdlib.h> in each of your source files.

    If you define __TILED__ in your source file, that definition must appear
    before the #include directive.

Once you have followed the above steps, the _tcalloc, _tfree, _tmalloc, and
_trealloc functions are automatically called in place of the regular memory
management functions in your code. Do not parenthesize any calls to these
functions, because parentheses will disable the definition of the function name
to the tiled memory function name.

Note:

o To use the tiled memory management functions, set the language level to
  extended. Specify the /Se option on the command line, or include the #pragma
  langlvl(extended) directive in your code.
o The debug memory management functions are not available if you are using
  tiled memory (with the /Gt compiler option).
o All memory blocks allocated by the _tcalloc, _tmalloc, and _trealloc
  functions must be freed using _tfree, not the free function. If you do not
  use _tfree, a message is generated and the process terminates. To ensure that
  _tfree is used, define the __TILED__ macro in all your modules.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o #define
o #include
o malloc.h
o stdlib.h
o /D option
o /Gt option
o Debug Memory Management Functions


ΓòÉΓòÉΓòÉ 4. Infinity and NaN Support ΓòÉΓòÉΓòÉ

The C/C++ Tools compiler supports the use of infinity and NaN (not-a-number)
values. Infinity is a value with an associated sign that is mathematically
greater in magnitude than any binary floating-point number. A NaN is a value in
floating-point computations that is not interpreted as a mathematical value,
and that contains a mask state and a sequence of binary digits.

The value of infinity can be computed from 1.0 / 0.0 . The value of a NaN can
be computed from 0.0 / 0.0 .

Depending on its bit pattern, a NaN can be either quiet (NaNQ) or signalling
(NaNS), as defined in the ANSI/IEEE Standard for Binary Floating-Point
Arithmetic (754-1982). A NaNQ is masked and never generates exceptions. A NaNS
may be masked and may generate an exception, but does not necessarily do so.
The C/C++ Tools compiler supports only quiet NaN values; all NaN values
discussed below refer to quiet NaNs.

NaN and infinity values are defined as macro constants in the <float.h> header
file.  The macros are:

Macro                Description
_INFINITYF           Infinity of type float
_INFINITY            Infinity of type double
_INFINITYL           Infinity of type long double

_INFF                Same as _INFINITYF
_INF                 Same as _INFINITY
_INFL                Same as _INFINITYL

_NANF                Quiet NaN of type float
_NAN                 Quiet NaN of type double
_NANL                Quiet NaN of type long double.

The corresponding negative values can be obtained by using the unary minus
operator (for example, -_INF).

Because these macros are actually references to constant variables, you cannot
use them to initialize static variables. For example, the following statements
are not allowed:

   static double infval = _INF;
   static float nanval = 1.0 + _NANF;

However, you can initialize static variables to the numeric values of infinity
and Nan:

   static double infval = 1.0 / 0.0;
   static float nanval =  0.0 / 0.0;

Note:  While positive and negative infinities are specific bit patterns, NaNs
       are not. A NaN value is not equal to itself or to any other value. For
       example, if you assign a NaN value to a variable x, you cannot check the
       value of x with the statement if (_NAN == x). Instead, use the statement
       if (x != x).

All relational and equality expressions involving NaN values always evaluate to
FALSE or zero (0), with the exception of not equal (!=), which always evaluates
to TRUE or one (1).

For information on the bit mapping and storage mapping of NaN and infinity
values, see the Programming Guide.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Infinity and NaN in Library Functions
o Assignment Expression
o Equality
o Relational
o float.h


ΓòÉΓòÉΓòÉ 4.1. Infinity and NaN in Library Functions ΓòÉΓòÉΓòÉ

When the language level is set to extended (using the /Se option or the #pragma
langlvl(extended) directive), which is the default, infinity and NaN values can
be passed as arguments to the scanf and printf families of library functions,
and to the string conversion and math functions. At other language levels,
these functions work as described in this reference.

The following sections describe how the library functions handle the infinity
and NaN values:

o scanf Family
o printf Family
o String Conversion Functions
o Math Functions


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Infinity and NaN Support
o #pragma langlvl
o /Se option.


ΓòÉΓòÉΓòÉ 4.1.1. scanf Family ΓòÉΓòÉΓòÉ

The scanf family of functions includes the SAA functions scanf, fscanf, and
sscanf. When reading in floating-point numbers, these functions convert the
strings INFINITY, INF, and NAN (in upper-, lower-, or mixed case) to the
corresponding floating-point value. The sign of the value is determined by the
format specification.

Given a string that consists of NAN, INF, or INFINITY, followed by other
characters, the scanf functions read in only the NaN or infinity value, and
consider the rest of the string to be a second input field. For example, Nancy
would be scanned as two fields, Nan and cy.

Note:  In the case of a string that begins with INF, the functions check the
       fourth letter. If that letter is not I (in upper- or lowercase), INF is
       read and converted and the rest of the string is left for the next
       format specification. If the fourth letter is I, the functions continue
       to scan for the full INFINITY string. If the string is other than
       INFINITY, the entire string is discarded.

Example of fscanf with NaN and Infinity Values


ΓòÉΓòÉΓòÉ <hidden> Example of fscanf with NaN and Infinity Values ΓòÉΓòÉΓòÉ

/************************************************************************
*

In the following example, fscanf converts NaN and infinity strings to their
numeric values.

                                                                        *
************************************************************************/

#include <stdio.h>

int main(void)
{
   int n, count;
   double d1, d2, d3;
   FILE *stream;

   stream = tmpfile();

   fputs(" INFINITY NAn INF", stream);

   rewind(stream);

   n = fscanf(stream, "%lF%lf%lF%n", &d1, &d2, &d3, &count);

   if (n != EOF)
   {
      printf("Number of fields converted = %d\n", n);
      printf("Number of characters read = %d\n", count);
      printf("Output = %f %F %F\n", d1, d2, d3);
   }

   return 0;

   /* The expected output is:

      Number of fields converted = 3
      Number of characters read = 17
      Output = infinity NAN INFINITY  */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Infinity and NaN Support
o fscanf  - Read Formatted Data
o scanf  - Read Data
o sscanf  - Read Data


ΓòÉΓòÉΓòÉ 4.1.2. printf Family ΓòÉΓòÉΓòÉ

The printf family of functions includes the SAA functions printf, fprintf,
sprintf, vfprintf, vprintf, and vsprintf. These functions convert
floating-point values of infinity and NaN to the strings "INFINITY" or
"infinity" and "NAN" or "nan".

The case is determined by the format specification, as is the sign (positive or
negative). When converting these values, the printf functions ignore the
precision width given by the format specification.

Example of printf with Nan and Infinity Values


ΓòÉΓòÉΓòÉ <hidden> Example of printf with Nan and Infinity Values ΓòÉΓòÉΓòÉ

/************************************************************************
*

In the following example, printf converts the NaN and infinity values and
prints out the corresponding string.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <float.h>

int main(void)
{
   double infval = -(_INF);
   float nanval = _NANF;

   printf("-_INF is the same as %-15.30f\n", infval);
   printf("_NANF is the same as %-15.30F\n", nanval);

   return 0;

   /* The expected output is:

      -_INF is the same as -infinity
      _NANF is the same as NAN        */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Infinity and NaN Support
o fprintf  - Write Formatted Data
o printf  - Formatted Print
o sprintf  - Formatted Print to Buffer
o vfprintf  - Print Argument Data
o vprintf  - Print Argument Data
o vsprintf  - Print Argument Data


ΓòÉΓòÉΓòÉ 4.1.3. String Conversion Functions ΓòÉΓòÉΓòÉ

The string conversion functions include the SAA functions atof and strtod, and
the C/C++ Tools standard extensions _atold, _ecvt, _fcvt, _gcvt, and strtold.

The atof, _atold, strtod, and strtold functions accept the strings INFINITY,
INF, and NAN (in upper-, lower-, or mixed case) as input, and convert these
strings to the corresponding macro value defined in <float.h>. The _ecvt,
_fcvt, and _gcvt functions convert infinity and NaN values to the strings
INFINITY and NAN, respectively.

Note:  If a signalling NaN string is passed to a string conversion function, a
quiet NaN value is returned, and no signal is raised.

Example of atof with NaN and Infinity Values


ΓòÉΓòÉΓòÉ <hidden> Example of atof with NaN and Infinity Values ΓòÉΓòÉΓòÉ

/************************************************************************
*

The following example uses atof to convert the strings "naN" and "infinity" to
the corresponding macro value.

                                                                        *
************************************************************************/

#include <stdlib.h>
#include <stdio.h>

int main(void)
{
   char *nanstr;
   char *infstr;

   nanstr = "naN";
   printf( "Result of atof = %.10e\n", atof(nanstr) );

   infstr = "inf";
   printf( "Result of atof = %.10E\n", atof(infstr) );

   return 0;

   /* The expected output is:

      Result of atof = nan
      Result of atof = INFINITY  */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Infinity and NaN Support
o atof  - Convert Character Strings
o _atold - Convert ASCII String to Long Double
o _ecvt - Convert Floating-Point to Character
o _fcvt - Convert Floating-Point to String
o _gcvt - Convert Floating-Point to String
o strtod  - Convert Character String to Numeric
o strtold - Convert String to Long Double


ΓòÉΓòÉΓòÉ 4.1.4. Math Functions ΓòÉΓòÉΓòÉ

Most math functions accept infinity, negative infinity, and NaN values as
input. (For information on those functions that do not accept these values, see
Math Functions without Infinity and NaN Support.) In general, a NaN value as
input will result in a NaN value as output, and infinity values as input
usually result in infinity values. If the input value is outside the domain or
range of the function, errno is set to EDOM or ERANGE, respectively.

The following tables display the results of each math function when NaN or
infinity values are input, and the associated errno value if one exists. The
first table lists the functions that take only one argument; the second lists
those that take two arguments.

Note:  In some cases, infinity is always a valid input value for the function
regardless of the language level (for example, atan). These cases do not appear
in the tables.

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé      NaN and Infinity Values in Math Functions              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé FUNCTION      Γöé INPUT       Γöé RESULT       Γöé "ERRNO" VALUE   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "         Γöé NaN        Γöé NaN "       Γöé          Γöé
Γöé acos        Γöé infinity      Γöé 0         Γöé EDOM       Γöé
Γöé asin "       Γöé -infinity     Γöé 0 "        Γöé EDOM       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "atan"       Γöé NaN        Γöé NaN        Γöé          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "         Γöé NaN        Γöé NaN        Γöé          Γöé
Γöé ceil        Γöé infinity      Γöé infinity      Γöé          Γöé
Γöé floor "      Γöé -infinity     Γöé -infinity     Γöé          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "         Γöé NaN        Γöé NaN        Γöé EDOM       Γöé
Γöé cos        Γöé infinity      Γöé NaN        Γöé ERANGE      Γöé
Γöé tan "       Γöé -infinity     Γöé NaN        Γöé ERANGE      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "cosh"       Γöé NaN        Γöé NaN        Γöé          Γöé
Γöé          Γöé infinity      Γöé infinity      Γöé ERANGE      Γöé
Γöé          Γöé -infinity     Γöé infinity      Γöé ERANGE      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "erf"       Γöé NaN        Γöé NaN "       Γöé EDOM       Γöé
Γöé          Γöé infinity      Γöé 1         Γöé          Γöé
Γöé          Γöé -infinity     Γöé -1 "        Γöé          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "erfc"       Γöé NaN        Γöé NaN "       Γöé EDOM       Γöé
Γöé          Γöé infinity      Γöé 0         Γöé          Γöé
Γöé          Γöé -infinity     Γöé 2 "        Γöé          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "exp"       Γöé NaN        Γöé NaN        Γöé          Γöé
Γöé          Γöé infinity      Γöé infinity "     Γöé ERANGE      Γöé
Γöé          Γöé -infinity     Γöé 0 "        Γöé ERANGE      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "fabs"       Γöé NaN        Γöé NaN        Γöé          Γöé
Γöé          Γöé infinity      Γöé infinity      Γöé          Γöé
Γöé          Γöé -infinity     Γöé infinity      Γöé          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "frexp"      Γöé NaN        Γöé NaN, "0"      Γöé EDOM       Γöé
Γöé          Γöé infinity      Γöé NaN, "0"      Γöé EDOM       Γöé
Γöé          Γöé -infinity     Γöé NaN, "0"      Γöé EDOM       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "gamma"      Γöé NaN        Γöé NaN        Γöé EDOM       Γöé
Γöé          Γöé infinity      Γöé infinity      Γöé ERANGE      Γöé
Γöé          Γöé -infinity     Γöé NaN        Γöé EDOM       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "         Γöé NaN        Γöé NaN        Γöé          Γöé
Γöé log        Γöé infinity "     Γöé infinity      Γöé          Γöé
Γöé log10 "      Γöé 0         Γöé -infinity     Γöé ERANGE      Γöé
Γöé          Γöé <0 "        Γöé NaN        Γöé EDOM       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "modf"       Γöé NaN        Γöé NaN, NaN      Γöé EDOM       Γöé
Γöé          Γöé infinity      Γöé NaN, infinity   Γöé EDOM       Γöé
Γöé          Γöé -infinity     Γöé NaN, -infinity   Γöé EDOM       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "sin"       Γöé NaN        Γöé NaN        Γöé EDOM       Γöé
Γöé          Γöé infinity      Γöé NaN        Γöé ERANGE      Γöé
Γöé          Γöé -infinity     Γöé NaN        Γöé ERANGE      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "sinh"       Γöé NaN        Γöé NaN        Γöé EDOM       Γöé
Γöé          Γöé infinity      Γöé infinity      Γöé ERANGE      Γöé
Γöé          Γöé -infinity     Γöé -infinity     Γöé ERANGE      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "sqrt"       Γöé NaN        Γöé NaN        Γöé          Γöé
Γöé          Γöé infinity      Γöé infinity "     Γöé          Γöé
Γöé          Γöé -infinity     Γöé 0 "        Γöé EDOM       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "tanh"       Γöé NaN        Γöé NaN "       Γöé EDOM       Γöé
Γöé          Γöé infinity      Γöé 1         Γöé          Γöé
Γöé          Γöé -infinity     Γöé -1 "        Γöé          Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The functions in the following table take two arguments. The results from NaN
and infinity values vary depending on which argument they are passed as.

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé      Infinity and NaN Values in Math Functions              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé FUNCTION    Γöé ARGUMENT 1   Γöé ARGUMENT 2   Γöé RESULT     Γöé "ERRNO"    Γöé
Γöé        Γöé        Γöé        Γöé        Γöé VALUE     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "atan2"    Γöé NaN      Γöé any number   Γöé NaN      Γöé EDOM     Γöé
Γöé        Γöé any number   Γöé NaN      Γöé NaN      Γöé        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "fmod"     Γöé NaN      Γöé any number   Γöé NaN      Γöé EDOM     Γöé
Γöé        Γöé any number   Γöé NaN      Γöé NaN      Γöé EDOM     Γöé
│        │ ёinfinity   │ any number   │ 0       │ EDOM     │
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "ldexp"    Γöé infinity    Γöé any number   Γöé infinity    Γöé ERANGE    Γöé
Γöé        Γöé -infinity   Γöé any number   Γöé -infinity   Γöé ERANGE    Γöé
Γöé        Γöé NaN      Γöé any number   Γöé NaN      Γöé EDOM     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
│ "pow"     │ ёinfinity   │ "0"      │ NaN      │ EDOM     │
Γöé        Γöé infinity    Γöé -infinity   Γöé NaN      Γöé EDOM     Γöé
│        │ -infinity   │ ёinfinity   │ NaN      │ EDOM     │
Γöé        Γöé -infinity   Γöé <-1      Γöé NaN      Γöé EDOM     Γöé
Γöé        Γöé -infinity   Γöé <1, >-1    Γöé NaN      Γöé EDOM     Γöé
Γöé        Γöé -infinity   Γöé >1       Γöé NaN      Γöé EDOM     Γöé
Γöé        Γöé NaN      Γöé any number   Γöé NaN      Γöé EDOM     Γöé
Γöé        Γöé any number   Γöé NaN      Γöé NaN      Γöé EDOM     Γöé
Γöé        Γöé =<0      Γöé infinity    Γöé NaN      Γöé EDOM     Γöé
│        │ 1       │ ёinfinity   │ NaN      │ EDOM     │
│        │ ёinfinity   │ ё1       │ 0       │ ERANGE    │
Γöé        Γöé >0, <1     Γöé infinity    Γöé 0       Γöé ERANGE    Γöé
Γöé        Γöé >0, <1     Γöé -infinity   Γöé infinity    Γöé ERANGE    Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Note:  If a signalling NaN is passed to a math function, the behavior is
       undefined.


ΓòÉΓòÉΓòÉ 4.1.5. Math Functions without Infinity and NaN Support ΓòÉΓòÉΓòÉ

The following floating-point unit functions are not supported for use with
infinity or NaN values. In general, a NaN or infinity value as input for these
functions will result in an undefined value, an invalid operation exception, or
both. These functions do not set errno.

_facos      _fasin
_fcos       _fcossin
_fpatan     _fptan
_fsin       _fsincos
_fsqrt      _fyl2x
_fyl2xp1    _f2xm1

Note:  If you expect the return value of a math function to be infinity or NaN,
you should use the functions that are supported for these values. The advantage
in using the floating-point unit math functions is a reduction in the
processing time. :enote.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Infinity and NaN Support
o math.h
o acos  - Calculate Arccosine
o asin  - Calculate Arcsine
o atan - atan2  - Calculate Arctangent
o ceil - Integer >= Argument
o cos  - Calculate Cosine
o cosh  - Calculate Hyperbolic Cosine
o erf  - Calculate Error Functions
o exp  - Exponential Function
o fabs  - Calculate Floating-Point Absolute Value
o floor - Integer <= Argument
o fmod  - Floating-Point Remainder
o frexp  - Separate Floating-Point Value
o gamma  - Gamma Function
o ldexp  - Multiply by a Power of Two
o log  - Calculate Natural Logarithm
o log10  - Calculate Base 10 Logarithm
o modf  - Separate Floating-Point Value
o pow  - Compute Power
o sin  - Calculate Sine
o sinh  - Calculate Hyperbolic Sine
o sqrt  - Calculate Square Root
o tan  - Calculate Tangent
o tanh  - Calculate Hyperbolic Tangent


ΓòÉΓòÉΓòÉ 5. Using Low-Level I/O Functions ΓòÉΓòÉΓòÉ

The C/C++ Tools compiler supports both stream I/O and low-level I/O. The
primary difference between the two types of I/O is that low-level I/O leaves
the responsibility of buffering and formatting up to the user.

In general, you should not mix input or output from low-level I/O with that
from stream I/O. The only way to communicate between stream I/O and low-level
I/O is by using the _fdopen or _fileno functions.

The low-level I/O functions include:

_access        _fstat
_chmod         _isatty
_chsize        _lseek
_close         _open
_creat         _read
_dup           _setmode
_dup2          _sopen
__eof          _stat
_fdopen        _tell
_filelength    _umask
_fileno        _write

When you are using the low-level I/O functions, you should be aware of the
following information:

o A handle is a value created by the system and used by low-level I/O that
  identifies a file. The conversion between C and OS/2 API handles is given by:

       API_handle = C_handle

  Handles may be passed between library environments without restriction.

  If a handle is acquired other than by using the C/C++ Tools library functions
  _open, _creat, _sopen, or _fileno, the function _setmode must be run for that
  handle before using it with the C/C++ Tools library functions.

o The default open-sharing mode is SH_DENYWR. Use _sopen to obtain other
  sharing modes.

o Text mode will delete `\r' characters on input and will change `\n' to `\r\n'
  on output.

o In a multithread environment, it is your responsibility to ensure that two
  threads do not attempt to perform low level I/O operations on the same file
  at the same time. You must make sure that one I/O process is completed before
  another begins.

o Low level I/O uses a named shared memory segment, with a name of the form
  \SHAREMEM\DDE4xxxx.xxx, where x may be any character other than blank. Using
  a named shared memory segment of this form may cause low level I/O to operate
  incorrectly.

o If the file mode is text, the low-level I/O functions treat the character x1a
  in the following ways:

   - The character x1a is treated as end of file on input if it is detected in
     a nonseekable file. It is only treated as end of file if it is the last
     character of a seekable file.

   - If a file is opened as text with either the O_APPEND or O_RDWR flags, and
     x1a is the last character of the file, the last character of the file is
     deleted.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Low-Level Input/Output


ΓòÉΓòÉΓòÉ 6. Library Functions ΓòÉΓòÉΓòÉ

The C/C++ Tools libraries are divided into two parts:

o Standard libraries, which define the SAA features and the C/C++ Tools
  standard extensions to SAA

o Subsystem libraries, which are a subset of the standard library, and are used
  for subsystem development.

This section lists alphabetically and describes all the functions that the
C/C++Tools product offers, including the extensions to the SAA C definition.
For information on the subsystem libraries and the functions in them, see the
chapter called "Developing Subsystems" in the Programming Guide.

Each function description includes the following subsections:

Format
      The prototyped declaration of the function and the header file in which
      it is found.  You do not need to include the declaration in your code; it
      is included with the header file.
Language Level
      The C language standard that each function belongs to. The standard is
      one of the following:

   ANSI      Functions defined in the ANSI C standard.
   SAA       Functions defined in the SAA C standard.
   POSIX     Functions defined in the POSIX C standard.
   Extension Functions offered by the C/C++ Tools product as extensions to the
             above standards.
Description
      A brief description of what the function does, what parameters it takes,
      and how to use the function.
Example
      A short example of how to use the function.
Related Information
      A list of other functions that are similar to or related to the function.

You can use the Copy to File choice from the Services pull-down menu to copy
any function example to a separate file (called TEXT.TMP by default).  You can
then compile, link, and run the example.


ΓòÉΓòÉΓòÉ 6.1. abort  - Stop a Program ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

void abort(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA, Extension

The abort function causes an abnormal program termination and returns control
to the host environment.  The abort function is similar to exit, except that
abort does not flush buffers and close open files before ending the program.
Calls to abort raise the SIGABRT signal.

Example of abort


ΓòÉΓòÉΓòÉ <hidden> Example of abort ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example tests for successful opening of the file myfile. If an error
occurs, an error message is printed and the program ends with a call to the
abort function.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>

int main(void)
{

   FILE *stream;

   if ((stream = fopen("myfile.dat", "r")) == NULL)
   {
      perror("Could not open data file");
      abort();
   }
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o exit  - End Program
o _exit - End Process
o signal Install Interrupt Handlers
o stdlib.h


ΓòÉΓòÉΓòÉ 6.2. abs  - Calculate Integer Absolute Value ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

int abs(int n);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The abs function returns the absolute value of an integer argument n.

There is no error return value.  The result is undefined when the absolute
value of the argument cannot be represented as an integer.  The value of the
minimum allowable integer is defined by INT_MIN in the <limits.h> include file.

Example of abs


ΓòÉΓòÉΓòÉ <hidden> Example of abs ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example calculates the absolute value of an integer x and assigns it to y.

                                                                        *
************************************************************************/

#include <stdlib.h>
#include <stdio.h>

int main(void)
{
    int x = -4, y;

    y = abs(x);

    printf("The absolute value of x is %d.\n", y);

    /********************* Output **************************
            The absolute value of x is 4.
    */
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _cabs - Calculate Absolute Value of Complex Number
o fabs  - Calculate Floating-Point Absolute Value
o labs  - Calculate long Absolute Value
o limits.h
o stdlib.h


ΓòÉΓòÉΓòÉ 6.3. _access - Determine Access Mode ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <io.h>

int _access(char *pathname, int mode);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _access function determines whether the specified file exists and whether
you can get access to it in the given mode.  The following list gives possible
values for the mode and their meaning in the access call:

Value    Meaning
 06      Check for permission to read from and write to the file.
 04      Check for permission to read from the file.
 02      Check for permission to write to the file.
 00      Check only for the existence of the file.

The _access function returns the value 0 if you can get access to the file in
the specified mode. A return value of -1 shows that the file does not exist or
is inaccessible in the given mode, and the system sets errno to one of the
following values:

Value          Meaning
EACCESS        Access is denied; the permission setting of the file does not
               allow you to get access to the file in the specified mode.
ENOENT         The system cannot find the file or the path that you specified,
               or the file name was incorrect.
EINVAL         The mode specified was not valid.
EOS2ERR        The call to the operating system was not successful.

Example of _access


ΓòÉΓòÉΓòÉ <hidden> Example of _access ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example checks for the existence of the file sample.dat. If the file does
not exist, it is created.

                                                                        *
************************************************************************/

#include <io.h>
#include <stdio.h>
#include <stdlib.h>

int main(void)
{

   if (-1 == _access("sample.dat",00))
   {
      printf("File sample.dat does not exist.\n");
      printf("Creating sample.dat.\n");
      system("echo Sample Program > sample.dat");
      if (0 == _access("sample.dat",00))
         printf("File sample.dat created.\n");
   }
   else
      printf("File sample.dat exists.\n");

   return 0;

/****************  The output should be similar to:  ********************

      File sample.dat does not exist.
      Creating sample.dat.
      File sample.dat created.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _chmod - Change File Permission Setting
o _sopen - Open Shared File
o _umask - Sets File Mask of Current Process
o io.h


ΓòÉΓòÉΓòÉ 6.4. acos  - Calculate Arccosine ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h>

double acos(double x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The acos function calculates the arc cosine of x, expressed in radians, in the
range 0 to у.

The value of x must be between -1 and 1 inclusive. If x is less than -1 or
greater than 1, acos sets errno to EDOM and returns 0.

Example of acos


ΓòÉΓòÉΓòÉ <hidden> Example of acos ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example prompts for a value for x.  It prints an error message if x is
greater than 1 or less than -1;  otherwise, it assigns the arc cosine of x to
y.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>
#include <math.h>

#define MAX  1.0
#define MIN -1.0

int main(void)
{
  double x, y;

  printf( "Enter x\n" );
  scanf( "%lf", &x );

  /* Output error if not in range */
  if ( x > MAX )
    printf( "Error: %lf too large for acos\n", x );
  else if ( x < MIN )
    printf( "Error: %lf too small for acos\n", x );
  else {
    y = acos( x );
    printf( "acos( %lf ) = %lf\n", x, y );
  }
}

/*******  Expected output if 0.4 is entered:  *********

Enter x
acos( 0.400000 ) = 1.159279
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o asin  - Calculate Arcsine
o atan - atan2  - Calculate Arctangent
o cos  - Calculate Cosine
o cosh  - Calculate Hyperbolic Cosine
o _facos - Calculate Arccosine
o _fcos - Calculate Cosine
o _fcossin - Calculate Cosine and Sine
o _fsincos - Calculate Sine and Cosine
o sin  - Calculate Sine
o sinh  - Calculate Hyperbolic Sine
o tan  - Calculate Tangent
o tanh  - Calculate Hyperbolic Tangent
o math.h


ΓòÉΓòÉΓòÉ 6.5. _alloca - Temporarily Reserve Storage Block ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>  /* also defined in <malloc.h> */
                     /*      and <builtin.h>       */

void *_alloca(size_t size);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extended

The _alloca function is a built-in function that temporarily allocates size
bytes of storage space from the program's stack. The memory space is
automatically freed when the function that called _alloca returns.

Note:  The _alloca function is faster than other allocation functions such as
malloc, but it has several limitations:

o Because it is a built-in function and has no backing code in the library:

   - You cannot take the address of _alloca.
   - You cannot parenthesize an _alloca function call because parentheses
     specify a call to the backing code for the function in the library, and
     _alloca has no backing code.

o Because _alloca automatically frees storage after the function that calls it
  returns, you cannot pass the pointer value returned by _alloca as an argument
  to the free function.
o You cannot pass memory allocated by _alloca to 16-bit programs, because it is
  never tiled.

Because _alloca uses automatic storage, programs calling _alloca must not be
compiled using the /Gs+ switch. This switch disables stack probes and does not
guarantee that enough stack storage will be available. You should use the /Gs-
switch, which is the default setting.

The _alloca function returns a pointer to the reserved space. If _alloca cannot
reserve the requested space, the program gets an out of stack exception.

Example of _alloca


ΓòÉΓòÉΓòÉ <hidden> Example of alloca ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example uses srand to generate five random numbers.  The numbers determine
how much space _alloca is to allocate for the array barstr.  The result is a
ragged two-dimensional array of strings.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>
#include <time.h>

int main(void)
{
    char *fullbar = "1 2 3 4 5";
    int range, rval;
    char *barstr[5];
    int i;

    printf("Bar representation of 5 random numbers\n ");
    printf("(each generated from 1 to 5):\n\n");

    srand( (unsigned int)time(NULL) ); /* set seed for rand function  */
                                       /* using time in seconds       */
    for (i = 0; i < 5; i++)
    {
       rval = (rand() + 1) % 5; /* generate random number from 0 to 4  */

       /* for partial copy of fullbar, allocate space on stack
          for barstr from 2 to 10 characters long + one space for
          a null character */
       barstr[i] = _alloca( (rval * sizeof(char) << 1) + 3 );
       memset(barstr[i], '\0', (rval 8 sizeof(char) <<1) + 3);

       /* copy random sized portion of fullbar  */
       strncpy(barstr[i], fullbar, ((rval +1) * 2) );

       printf("%s\n", barstr[i]);    /*  print random length bar  */
    }

    return 0;

    /***************  Possible output could be:  ********************

       Bar representation of 5 random numbers
       (each generated from 1 to 5):

       1
       1 2 3 4
       1 2 3
       1 2 3 4 5
       1 2                                */
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o calloc  - Reserve and Initialize Storage
o free  - Release Storage Blocks
o malloc  - Reserve Storage Block
o realloc  - Change Reserved Storage Block Size
o /Gs option
o malloc.h
o stdlib.h


ΓòÉΓòÉΓòÉ 6.6. asctime  - Convert Time ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <time.h>

char *asctime(const struct tm *time);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The asctime function converts time stored as a structure pointed to by time to
a character string.  The time value may be obtained from a call to gmtime or
localtime;  either returns a pointer to a tm structure defined in <time.h>. See
gmtime  - Convert Time for a description of the tm structure fields.

The string result that asctime produces contains exactly 26 characters and has
the format:

   "%.3s %.3s%3d %.2d:%.2d:%.2d %d\n"

See printf  - Formatted Print for a description of format specifications. The
following are examples of the string returned:

   Sat Jul 04 02:03:55 1991\n\0
or
   Sat Jul 04  2:03:55 1991\n\0

The asctime function uses a 24-hour-clock format.  The days are abbreviated to:
Sun, Mon, Tue, Wed, Thu, Fri, and Sat.  The months are abbreviated to:  Jan,
Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, and Dec.  All fields have
constant width. Days with only one digit are preceded either with a zero or a
blank space. The new-line character (\n) and the null character (\0) occupy the
last two positions of the string.

The time and date functions begin at 00:00:00 Universal Time, January 1, 1970.

The asctime function returns a pointer to the resulting character string.
There is no error return value.

Note:  The asctime, ctime, and other time functions may use a common,
       statically allocated buffer to hold the return string.  Each call to one
       of these functions may destroy the result of the previous call.

Example of asctime


ΓòÉΓòÉΓòÉ <hidden> Example of asctime ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example polls the system clock and prints a message giving the current
time.

                                                                        *
************************************************************************/

#include <time.h>
#include <stdio.h>

int main(void)
{
    struct tm *newtime;
    time_t ltime;

        /* Get the time in seconds */
    time(<ime);
        /* Convert it to the structure tm */
    newtime = localtime(<ime);

        /* Print the local time as a string */
    printf("The current date and time are %s",
             asctime(newtime));
}

/****************  Output should be similar to:  ******************

The current date and time are Fri Mar 26 13:29:51 1993
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o ctime  - Convert Time
o gmtime  - Convert Time
o localtime  - Convert Time
o mktime  - Convert Local Time
o strftime  - Convert to Formatted Time
o time  - Determine Current Time
o printf  - Formatted Print
o time.h


ΓòÉΓòÉΓòÉ 6.7. asin  - Calculate Arcsine ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h>

double asin(double x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The asin function calculates the arc sine of x, in the range -у/2 to у/2
radians.

The value of x must be between -1 and 1.  If x is less than -1 or greater than
1, asin sets errno to EDOM, and returns a value of 0.

Example of asin


ΓòÉΓòÉΓòÉ <hidden> Example of asin ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example prompts for a value for x.  It prints an error message if x is
greater than 1 or less than -1;  otherwise, it assigns the arc sine of x to y.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>
#include <math.h>

#define MAX  1.0
#define MIN -1.0

int main(void)
{
  double x, y;

  printf( "Enter x\n" );
  scanf( "%lf", &x );

  /* Output error if not in range */
  if ( x > MAX )
    printf( "Error: %lf too large for asin\n", x );
  else if ( x < MIN )
    printf( "Error: %lf too small for asin\n", x );
  else
  {
    y = asin( x );
    printf( "asin( %lf ) = %lf\n", x, y );
  }
}

/****************  Output should be similar to:  ******************

Enter x
asin( 0.200000 ) = 0.201358
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o acos  - Calculate Arccosine
o atan - atan2  - Calculate Arctangent
o cos  - Calculate Cosine
o cosh  - Calculate Hyperbolic Cosine
o _fasin - Calculate Arcsine
o _fcossin - Calculate Cosine and Sine
o _fsin - Calculate Sine
o _fsincos - Calculate Sine and Cosine
o sin  - Calculate Sine
o sinh  - Calculate Hyperbolic Sine
o tan  - Calculate Tangent
o tanh  - Calculate Hyperbolic Tangent
o math.h


ΓòÉΓòÉΓòÉ 6.8. assert  - Verify Condition ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <assert.h>

void assert(int expression);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The assert function prints a diagnostic message to stderr and aborts the
program if expression is false (zero). The diagnostic message has the format:
Assertion failed: expression, file filename, line line-number.

The assert function takes no action if the expression is true (nonzero).

Use the assert function to identify program logic errors.  Choose an expression
that holds true only if the program is operating as you intend.  After you have
debugged the program, you can use the special no-debug identifier NDEBUG to
remove the assert calls from the program.  If you define NDEBUG to any value
with a #define directive, the C preprocessor expands all assert invocations to
void expressions. If you use NDEBUG, you must define it before you include
<assert.h> in the program.

There is no return value.

Note:  The assert function is a macro. Do not use the #undef directive with the
assert function.

Example of assert


ΓòÉΓòÉΓòÉ <hidden> Example of assert ΓòÉΓòÉΓòÉ

/************************************************************************
*

In this example, the assert function tests the string argument for a null
string and an empty string and verifies that the length argument is positive
before processing these arguments.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <assert.h>

void analyze (char *, int);

int main(void)
{
   char *string = "ABC";
   int length = 3;

   analyze(string, length);
   printf("The string %s is not null or empty, "
          "and has length %d \n", string, length);
}

void analyze(char *string, int length)
{
   assert(string != NULL);            /* cannot be NULL */
   assert(*string != '\0');    /* cannot be empty */
   assert(length > 0);          /* must be positive */
}

/****************  Output should be similar to:  ******************

The string ABC is not null or empty, and has length 3
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o abort  - Stop a Program
o assert.h
o #define
o #undef


ΓòÉΓòÉΓòÉ 6.9. atan - atan2  - Calculate Arctangent ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h>

double atan(double x);

double atan2(double y, double x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The atan and atan2 functions calculate the arc tangent of x and y/x,
respectively.

The atan function returns a value in the range -у/2 to у/2 radians. The atan2
function returns a value in the range -у to у radians.  If both arguments of
atan2 are zero, the function sets errno to EDOM, and returns a value of zero
(0).

Example of atan - atan2


ΓòÉΓòÉΓòÉ <hidden> Example of atan - atan2 ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example calculates arc tangents using the atan and atan2 functions.

                                                                        *
************************************************************************/

#include <math.h>
#include <stdio.h>

int main(void)
{
    double a,b,c,d;

    c = 0.45;
    d = 0.23;

    a = atan(c);
    b = atan2(c,d);

    printf("atan( %lf ) = %lf\n", c, a);
    printf("atan2( %lf, %lf ) = %lf\n", c, d, b);
}

/****************  Output should be similar to:  ******************

atan( 0.450000 ) = 0.422854
atan2( 0.450000, 0.230000 ) = 1.098299
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o acos  - Calculate Arccosine
o asin  - Calculate Arcsine
o cos  - Calculate Cosine
o cosh  - Calculate Hyperbolic Cosine
o _fpatan - Calculate Arctangent
o _fptan - Calculate Tangent
o sin  - Calculate Sine
o sinh  - Calculate Hyperbolic Sine
o tan  - Calculate Tangent
o tanh  - Calculate Hyperbolic Tangent
o math.h


ΓòÉΓòÉΓòÉ 6.10. atexit  - Record Program Termination Function ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

int atexit(void (*func)(void));


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The atexit function records a function, pointed to by func, that the system
calls at normal program termination.  For portability, you should use atexit to
register up to 32 functions only. The functions are executed in a last in,
first out order.

The atexit function returns zero (0) if it is successful, and nonzero if it
fails.

Example of atexit


ΓòÉΓòÉΓòÉ <hidden> Example of atexit ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses the atexit function to call the function goodbye at program
termination.

                                                                        *
************************************************************************/

#include <stdlib.h>
#include <stdio.h>

int main(void)
{
   void goodbye(void);
   int rc;

   rc = atexit(goodbye);
   if (rc != 0)
      perror("Error in atexit");
   exit(0);
}

void goodbye(void)
   /* This function is called at normal program termination */
{
   printf("The function goodbye was called at program termination\n");
}

/****************  Output should be similar to:  ******************

The function goodbye was called at program termination
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o exit  - End Program
o _exit - End Process
o _onexit - Record Termination Function
o signal Install Interrupt Handlers
o stdlib.h


ΓòÉΓòÉΓòÉ 6.11. atof  - Convert Character Strings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

double atof(const char *string);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA, Extension

This function converts a character string to a double-precision floating-point
value.

The input string is a sequence of characters that can be interpreted as a
numerical value of the specified return type.  The function stops reading the
input string at the first character that it cannot recognize as part of a
number;  this character can be the null character that ends the string.

The atof function expects a string in the following form:

 ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ
  Γöé        Γöé  Γöé    Γöé  Γöé                 Γöé
  ΓööΓöÇΓöÇwhitespaceΓöÇΓöÇΓöÿ  Γö£ΓöÇΓöÇ + ΓöÇΓöÇΓöñ  Γö£ΓöÇdigitsΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöñ
           Γöé    Γöé  Γöé      Γöé    Γöé  Γöé     Γöé  Γöé
           ΓööΓöÇΓöÇ - ΓöÇΓöÇΓöÿ  Γöé      ΓööΓöÇΓöÇ . ΓöÇΓöÿ  ΓööΓöÇdigitsΓöÇΓöÿ  Γöé
                 Γöé                 Γöé
                 ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ . ΓöÇΓöÇdigitsΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ
  Γöé              Γöé
  Γö£ΓöÇΓöÇeΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇdigitsΓöÇΓöÇΓöÿ
  Γöé   Γöé  Γöé   Γöé
  ΓööΓöÇΓöÇEΓöÇΓöÇΓöÿ  Γö£ΓöÇ + ΓöÇΓöñ
       Γöé   Γöé
       ΓööΓöÇ - ΓöÇΓöÿ

The white space consists of the same characters for which the isspace function
is true, such as spaces and tabs.  The atof function ignores leading
white-space characters.

For the atof function, digits is one or more decimal digits;  if no digits
appear before the decimal point, at least one digit must appear after the
decimal point.  The decimal digits can precede an exponent, introduced by the
letter e or E.  The exponent is a decimal integer, which may be signed. The
string can also be "infinity", "inf", or "nan". These strings are case
insensitive, and can be preceded by a unary minus (-). They are converted to
infinity and NaN values.

The atof function returns a double value produced by interpreting the input
characters as a number.  The return value is 0 if the function cannot convert
the input to a value of that type.  The return value is undefined in case of
overflow.

Example of atof


ΓòÉΓòÉΓòÉ <hidden> Example of atof ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example shows how to convert numbers stored as strings to numerical values
using the atof function.

                                                                        *
************************************************************************/

#include <stdlib.h>

int main(void)
{
    double x;
    char *s;

    s = " -2309.12E-15";
    x = atof(s);     /* x = -2309.12E-15 */
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o atoi  - Convert Character Strings
o atol  - Convert Character Strings
o _atold - Convert ASCII String to Long Double
o strtod  - Convert Character String to Numeric
o strtol  - Convert Character String to Numeric
o strtold - Convert String to Long Double
o Infinity and NaN Support
o stdlib.h


ΓòÉΓòÉΓòÉ 6.12. atoi  - Convert Character Strings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

int atoi(const char *string);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

This function converts a character string to an integer value.

The input string is a sequence of characters that can be interpreted as a
numerical value of the specified return type.  The function stops reading the
input string at the first character that it cannot recognize as part of a
number;  this character can be the null character which ends the string.

The atoi function does not recognize decimal points nor exponents.  The string
argument for this function has the form:

ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇdigitsΓöÇΓöÇ
  Γöé        Γöé  Γöé    Γöé
  ΓööΓöÇΓöÇwhitespaceΓöÇΓöÇΓöÿ  Γö£ΓöÇΓöÇ + ΓöÇΓöÇΓöñ
           Γöé    Γöé
           ΓööΓöÇΓöÇ - ΓöÇΓöÇΓöÿ

where whitespace consists of the same characters for which the isspace function
is true, such as spaces and tabs.  The atoi function ignores leading
white-space characters. digits is one or more decimal digits.

atoi returns an int value produced by interpreting the input characters as a
number.  The return value is 0 if the function cannot convert the input to a
value of that type.  The return value is undefined in the case of an overflow.

 Example of atoi


ΓòÉΓòÉΓòÉ <hidden> Example of atoi ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example shows how to convert numbers stored as strings to numerical values
using the atoi function.

                                                                        *
************************************************************************/

#include <stdlib.h>

int main(void)
{
    int i;
    char *s;

    s = " -9885";
    i = atoi(s);     /* i = -9885 */
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o atof  - Convert Character Strings
o atol  - Convert Character Strings
o _atold - Convert ASCII String to Long Double
o strtod  - Convert Character String to Numeric
o strtol  - Convert Character String to Numeric
o strtold - Convert String to Long Double
o stdlib.h


ΓòÉΓòÉΓòÉ 6.13. atol  - Convert Character Strings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

long int atol(const char *string);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

This function converts a character string to a long value.

The input string is a sequence of characters that can be interpreted as a
numerical value of the specified return type.  The function stops reading the
input string at the first character that it cannot recognize as part of a
number;  this character can be the null character that ends the string.

The atol function does not recognize decimal points nor exponents.  The string
argument for this function has the form:

ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇdigitsΓöÇΓöÇ
  Γöé        Γöé  Γöé    Γöé
  ΓööΓöÇΓöÇwhitespaceΓöÇΓöÇΓöÿ  Γö£ΓöÇΓöÇ + ΓöÇΓöÇΓöñ
           Γöé    Γöé
           ΓööΓöÇΓöÇ - ΓöÇΓöÇΓöÿ

where whitespace consists of the same characters for which the isspace function
is true, such as spaces and tabs.  The atol function ignores leading
white-space characters. digits is one or more decimal digits.

atol returns a long value produced by interpreting the input characters as a
number.  The return value is 0L if the function cannot convert the input to a
value of that type.  The return value is undefined in case of overflow.

Example of atol


ΓòÉΓòÉΓòÉ <hidden> Example of atol ΓòÉΓòÉΓòÉ

/************************************************************************
*

The example shows how to convert numbers stored as strings to numerical values
using the atol function.

                                                                        *
************************************************************************/

#include <stdlib.h>

int main(void)
{
    long l;
    char *s;

    s = "98854 dollars";
    l = atol(s);     /* l = 98854 */
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o atof  - Convert Character Strings
o atoi  - Convert Character Strings
o _atold - Convert ASCII String to Long Double
o strtod  - Convert Character String to Numeric
o strtol  - Convert Character String to Numeric
o strtold - Convert String to Long Double
o stdlib.h


ΓòÉΓòÉΓòÉ 6.14. _atold - Convert ASCII String to Long Double ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>    /* also defined in <math.h> */

long double _atold(const char *nptr);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _atold function converts a character string pointed to by nptr to a long
double value.  The function continues until it reads a character it does not
recognize  as part of a number.  This character may be the ending null
character. Except for its behavior on error, _atold is equivalent to

   strtold(nptr, (char **)NULL)

The string pointed to by nptr must have the following format:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé                                        Γöé
Γöé >>ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ>       Γöé
Γöé   ΓööΓöÇwhitespaceΓöÇΓöÿ  ΓööΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇdigitsΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÿ        Γöé
Γöé            Γö£ΓöÇ + ΓöÇΓöñ  Γöé     ΓööΓöÇ.ΓöÇΓöÿ  ΓööΓöÇdigitsΓöÇΓöÿ Γöé         Γöé
Γöé            ΓööΓöÇ Γö┤ ΓöÇΓöÿ  ΓööΓöÇ.ΓöÇΓöÇdigitsΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ         Γöé
Γöé                                        Γöé
Γöé >ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ><                      Γöé
Γöé   ΓööΓöÇΓö¼ΓöÇ e ΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇdigitsΓöÇΓöÿ                        Γöé
Γöé    ΓööΓöÇ E ΓöÇΓöÿ  Γö£ΓöÇ + ΓöÇΓöñ                             Γöé
Γöé        ΓööΓöÇ Γö┤ ΓöÇΓöÿ                             Γöé
Γöé                                        Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The digits are one or more decimal digits.  If no digits appear before the
decimal point, at least one digit must follow the decimal point. You can place
an exponent expressed as a decimal integer after the digits. The exponent can
be signed.

The value of nptr can also be one of the strings infinity, inf, or nan.  These
strings are case insensitive, and can be preceded by a unary minus (-). They
are converted to infinity and NaN values. For more information on NaN and
infinity values, see Infinity and NaN Support.

The _atold function ignores any whitespace characters, as defined by the
isspace function.

The _atold function returns the converted long double value. In the case of an
underflow, it returns 0. In the case of a positive overflow, _atold returns
positive _LHUGE_VAL, and negative _LHUGE_VAL for a negative overflow.

Example of _atold


ΓòÉΓòÉΓòÉ <hidden> Example of _atold ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example uses _atold to convert two strings, "  -001234.5678e10end of
string" and "NaNQ", to their corresponding long double values.

                                                                        *
************************************************************************/

#include <stdlib.h>
#include <stdio.h>

int main(void)
{
  char *string;

  string = "  -001234.5678e10end of string";
  printf("_atold = %.10Le\n", _atold(string) );

  string = "NaNQ";
  printf("_atold = %.10Le\n", _atold(string) );

  return 0;

  /* The expected output is:

     _atold = -1.2345678000e+13
     _atold = nan                */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o atof  - Convert Character Strings
o atoi  - Convert Character Strings
o atol  - Convert Character Strings
o strtod  - Convert Character String to Numeric
o strtol  - Convert Character String to Numeric
o strtold - Convert String to Long Double
o stdlib.h
o math.h


ΓòÉΓòÉΓòÉ 6.15. _beginthread - Create New Thread ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>     /* also defined in <process.h> */

int _beginthread(void (*start_address) (void *),
                     (void *)stack,
                     unsigned stack_size,
                     void *arglist);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _beginthread function creates a new thread. It takes the following
arguments:

start_address
  This parameter is the address of the function that the newly created thread
  will execute. When the thread returns from that function, it is terminated
  automatically. You can also explicitly terminate the thread by calling
  _endthread.
stack
  This parameter is ignored, but is retained to ease migration of C/2 programs.
  The C/2 compiler requires the second parameter to be the address of the
  bottom of the stack that the new thread will use. Because the OS/2 operating
  system automatically takes care of stack allocation, the parameter is not
  needed.
stack_size
  The size of the stack, in bytes, which is to be allocated for the new thread.
  The stack size should be a nonzero multiple of 4K and a minimum of 8K. Memory
  is used when needed, one page at a time.
arglist
  A parameter to be passed to the newly created thread. It is the size of a
  pointer, and is usually the address of a data item to be passed to the new
  thread, such as a char string. It provides _beginthread with a value to pass
  to the child thread. NULL can be used as a placeholder.

The function that the new thread will perform must be declared and compiled
using _Optlink linkage.

An alternative to this function is the OS/2 DosCreateThread API. If you use
DosCreateThread, you must also use a #pragma handler statement for the thread
function to ensure proper C exception handling. You should also call the
_fpreset function at the start of the thread to preset the 387 control status
word properly. The use of DosCreateThread requires the use of _endthread to
terminate the thread.

Note:  When using the _beginthread and _endthread functions, you must specify
the /Gm+ compiler option to use the multithread libraries.

If successful, _beginthread returns the thread ID number of the new thread. It
returns -1 to indicate an error.

Example of _beginthread


ΓòÉΓòÉΓòÉ <hidden> Example of _beginthread ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example uses _beginthread to start a new thread bonjour, which prints
Bonjour! five times and then implicitly ends itself. The program then prints a
statement indicating the thread identifier number for bonjour.

Note:  To run this example, you must compile it using the /Gm+ compiler option.

                                                                        *
************************************************************************/

#define INCL_DOS
#include <os2.h>
#include <stdio.h>
#include <stdlib.h>

static int wait = 1;

void bonjour(void *arg)
{
   int i = 0;

   while (wait)
           /* wait until the thread id has been printed */
      DosSleep(0l);

   while ( i++ < 5 )
      printf("Bonjour!\n");
}

int main(void)
{
   unsigned long tid;

   tid = _beginthread(bonjour, NULL, 8192, NULL);

   if ( tid == -1 )
   {
      printf("Unable to start thread.\n");
      exit(-1);
   }
   else
   {
      printf("Thread started
              with thread identifier number %d.\n", tid);
      wait = 0;
   }

   DosWaitThread( &tid, DCWW_WAIT );
               /* wait for thread bonjour to end */
               /*  before ending main thread      */

   return 0;

/* The expected output
       (with possible thread id number) is:

      Thread started with thread identifier number 2.
      Bonjour!
      Bonjour!
      Bonjour!
      Bonjour!
      Bonjour!                                                  */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _endthread - Terminate Current Thread
o _threadstore - Access Thread-Specific Storage
o /Gm+ option
o stdlib.h
o process.h


ΓòÉΓòÉΓòÉ 6.16. Bessel Functions ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h> /* SAA extensions to ANSI */

double _j0(double x);

double _j1(double x);

double _jn(int n, double x);

double _y0(double x);

double _y1(double x);

double _yn(int n, double x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: SAA

Bessel functions solve certain types of differential equations.  The _j0, _j1,
and _jn functions are Bessel functions of the first kind for orders 0, 1, and
n, respectively.

The _y0, _y1, and _yn functions are Bessel functions of the second kind for
orders 0, 1, and n, respectively.  The argument x must be positive.  The
argument n should be greater than or equal to zero. If n is less than zero, it
will be a negative exponent.

For _j0, _j1, _y0, or _y1, if the absolute value of x is too large, the
function sets errno to ERANGE, and returns 0.  For _y0, _y1, or _yn, if x is
negative, the function sets errno to EDOM and returns the value -HUGE_VAL.  For
_y0, _y1, or _yn, if x causes overflow, the function sets errno to ERANGE and
returns the value -HUGE_VAL.

Example of Bessel Functions


ΓòÉΓòÉΓòÉ <hidden> Example of Bessel Functions ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example computes y to be the order 0 Bessel function of the first kind for
x and z to be the order 3 Bessel function of the second kind for x.

                                                                        *
************************************************************************/

#include <math.h>

int main(void)
{
    double x, y, z;
    x = 4.27;

    y = _j0(x);      /* y = -0.3660 is the order 0 bessel */
                     /* function of the first kind for x  */
    z = _yn(3,x);    /* z = -0.0875 is the order 3 bessel */
                     /* function of the second kind for x */
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o erf  - Calculate Error Functions
o gamma  - Gamma Function
o math.h


ΓòÉΓòÉΓòÉ 6.17. bsearch  - Search Arrays ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>  /* also defined in <search.h> */

void *bsearch(const void *key, const void *base, size_t num,
              size_t size, int (*compare) (const void *element1,
              const void *element2));


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA, Extension

The bsearch function performs a binary search of an array of num elements, each
of size bytes The array must be sorted in ascending order by the function
pointed to by compare.  The base is a pointer to the base of the array to
search, and key is the value being sought.

The compare variable is a pointer to a function you must supply that compares
two array elements and returns a value specifying their relationship.  The
bsearch function calls this function one or more times during the search,
passing the key and the pointer to one array element on each call.  The
function must compare the elements and then return one of the following values:

Value             Meaning
Less than 0       element1 less than element2
0                 element1 identical to element2
Greater than 0    element1 greater than element2

The bsearch function returns a pointer to key in the array to which base
points.  If two keys are equal, which element key will point to is unspecified.
If bsearch cannot find the key, it returns NULL.

Example of bsearch


ΓòÉΓòÉΓòÉ <hidden> Example of bsearch ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example performs a binary search on the argv array of pointers to the
program parameters and finds the position of the argument PATH. It first
removes the program name from argv, and then sorts the array alphabetically
before calling bsearch. The functions compare1 and compare2 compare the values
pointed to by arg1 and arg2 and return the result to bsearch.

                                                                        *
************************************************************************/

#include <stdlib.h>
#include <stdio.h>
#include <string.h>

int compare1(const void *arg1, const void *arg2);
int compare2(const void *arg1, const void *arg2);

int main(int argc, char *argv[])
{
   char **result;
   char *key = "PATH";
   int i;
   argv++;
   argc--;

   qsort((char *)argv, argc, sizeof(char *), compare1);

   result = (char**)bsearch(key, argv, argc, sizeof(char *), compare2);
   if (result != NULL)
   {
      printf("result = <%s>\n",*result);
   }
   else printf("result is null\n");
}

int compare1(const void *arg1, const void *arg2)
{
   return (strcmp(*(char **)arg1, *(char **)arg2));
}

int compare2(const void *arg1, const void *arg2)
{
   return (strcmp((char *)arg1, *(char **)arg2));
}

/********************  Output should be similar to:  **************

progname where is PATH in this phrase?
result = <PATH>
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _lfind - _lsearch - Find Key in Array
o qsort  - Sort Array
o stdlib.h


ΓòÉΓòÉΓòÉ 6.18. _cabs - Calculate Absolute Value of Complex Number ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h>

double _cabs(struct complex z);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _cabs function calculates the absolute value of a complex number.  This
complex number is represented as a structure with the tag complex containing
the real and imaginary parts.  The following type declaration is in <math.h>:

   struct complex {double x,y;};

A call to _cabs is equivalent to:

   sqrt(z.x * z.x + z.y * z.y)

Note:  For portability, use the SAA function hypot to replace _cabs.

The _cabs function returns the absolute value as a double value.  If an
overflow results, _cabs calls the _matherr routine and, if necessary, sets
errno to ERANGE and returns the value HUGE_VAL.

Example of _cabs


ΓòÉΓòÉΓòÉ <hidden> Example of _cabs ΓòÉΓòÉΓòÉ

/************************************************************************
*                                                                          *
The following program computes the absolute value of the complex number (3.0,
4.0).

                                                                        *
************************************************************************/

#include <math.h>
#include <stdio.h>

int main(void)
{
    struct complex value;
    double d;

    value.x = 3.0;
    value.y = 4.0;
    d = _cabs(value);
    printf("The complex absolute value of %f and %f is
             %f\n", value.x, value.y, d);

    return 0;

/************  Output should be:  *******************************
/*                                                              */
   The complex absolute value of 3.000000 and 4.000000 is 5.000000 */
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o abs  - Calculate Integer Absolute Value
o fabs  - Calculate Floating-Point Absolute Value
o hypot  - Calculate Hypotenuse
o labs  - Calculate long Absolute Value
o _matherr - Process Math Library Errors
o sqrt  - Calculate Square Root
o math.h


ΓòÉΓòÉΓòÉ 6.19. calloc  - Reserve and Initialize Storage ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>  /* also defined in <malloc.h> */

void *calloc(size_t num, size_t size);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The calloc function reserves storage space for an array of num elements, each
of length size bytes.  The calloc function then gives all the bits of each
element an initial value of 0.

The calloc function returns a pointer to the reserved space.  The storage space
to which the return value points is guaranteed to be suitably aligned for
storage of any type of object.  To get a pointer to a type, use a type cast on
the return value.  The return value is NULL if there is not enough storage, or
if num or size is 0.

Example of calloc


ΓòÉΓòÉΓòÉ <hidden> Example of calloc ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example prompts for the number of array entries required and then reserves
enough space in storage for the entries. If calloc is successful, the example
prints out each entry;  otherwise, it prints out an error.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
  long * array;                               /* start of the array */
  long * index;                               /* index variable     */
  int    i;                                   /* index variable     */
  int  num;                       /* number of entries of the array */

  printf( "Enter the size of the array\n" );
  scanf( "%i", &num );

                                            /* allocate num entries */
  if ( (index = array = calloc( num, sizeof( long ))) != NULL )
  {

    for ( i = 0; i < num; ++i )           /* put values in array    */
       *index++ = i;                      /* using pointer notation */

    for ( i = 0; i < num; ++i )           /* print the array out    */
      printf( "array[ %i ] = %i\n", i, array[i] );
  }
  else
  { /* out of storage */
    perror( "Out of storage" );
    abort();
  }
}

/******************  Output should be similar to:  **********************

Enter the size of the array
array[ 0 ] = 0
array[ 1 ] = 1
array[ 2 ] = 2
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _alloca - Temporarily Reserve Storage Block
o _debug_calloc - Reserve and Initialize Storage
o malloc  - Reserve Storage Block
o _tcalloc - Reserve Tiled Storage Block
o free  - Release Storage Blocks
o malloc  - Reserve Storage Block
o realloc  - Change Reserved Storage Block Size
o malloc.h
o stdlib.h


ΓòÉΓòÉΓòÉ 6.20. ceil - Integer >= Argument ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h>

double ceil(double x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The ceil function computes the smallest integer that is greater than or equal
to x.

The ceil function returns a double value.

Example of ceil


ΓòÉΓòÉΓòÉ <hidden> Example of ceil ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example sets y to the smallest integer greater than 1.05, and then to the
smallest integer greater than -1.05.  The results are 2. and -1., respectively.

                                                                        *
************************************************************************/

#include <math.h>

int main(void)
{
   double y, z;

   y = ceil(1.05);       /* y = 2.0 */
   z = ceil(-1.05);      /* z = -1.0 */
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o floor - Integer <= Argument
o fmod  - Floating-Point Remainder
o math.h


ΓòÉΓòÉΓòÉ 6.21. _cgets - Read String of Characters from Keyboard ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <conio.h>

char *_cgets(char *str);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _cgets function reads a string of characters directly from the keyboard and
stores the string and its length in the location pointed to by str.

The _cgets function continues to read characters until it meets a
carriage-return followed by a line-feed (CR-LF) or until it reads the specified
number of characters. It stores the string starting at str[2]. If _cgets reads
a CR-LF combination, it replaces this combination with a null character ('\0')
before storing the string. The _cgets function then stores the actual length of
the string in the second array element, str[1].

The str variable must be a pointer to a character array. The first element of
the array, str[0], must contain the maximum length, in characters, of the
string to be read.  The array must have enough elements to hold the string, a
final null character, and 2 additional bytes.

If successful, the _cgets function returns a pointer to the actual start of the
string, str[2]. Otherwise, _cgets returns NULL.

Example of _cgets


ΓòÉΓòÉΓòÉ <hidden> Example of _cgets ΓòÉΓòÉΓòÉ

/************************************************************************
*                                                                          *

This example creates a buffer and initializes the first byte to the size of the
buffer. The program then accepts an input string using cgetsand displays the
size and text of that string.

                                                                        *
************************************************************************/


#include <conio.h>
#include <stdio.h>

void nothing(void)
{
}

int main(void)
{
    char buffer[82] = { 80, 0 };
    char * buffer2;
    int i;

    _cputs("\nPress any key to continue.");
    printf("\n");

    while (_kbhit() == 0)
    {
    nothing();
    }

    _getch();
    _cputs("\nEnter a line of text:");
    printf("\n");

    buffer2= _cgets(buffer);
    printf("\nText entered was: %s",buffer2);

    return 0;
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o conio.h
o _cputs - Write String to Screen
o fgets  - Read a String
o gets  - Read a Line
o _getch - _getche - Read Character from Keyboard


ΓòÉΓòÉΓòÉ 6.22. _chdir - Change Current Working Directory ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <direct.h>

int _chdir(char *pathname);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _chdir function causes the current working directory to change to the
directory specified by pathname.  The pathname must refer to an existing
directory.

Note:  This function can change the current working directory on any drive.  It
cannot change the default drive.  For example, if A:\BIN is the current working
directory and A: is the default drive, the following changes only the current
working directory on drive C:.

   _chdir ("c:\\emp");

A: is still the default drive.

An alternative to this function is the DosSetCurrentDir API call.

The _chdir function returns a value of 0 if the working directory was
successfully changed. A return value of -1 indicates an error;  in this case,
_chdir sets errno to ENOENT, showing that _chdir cannot find the specified path
name.  No error occurs if pathname specifies the current working directory.

Example of _chdir


ΓòÉΓòÉΓòÉ <hidden> Example of _chdir ΓòÉΓòÉΓòÉ

/************************************************************************
*                                                                          *
This example changes the current working directory to the root directory, and
then to the \red\green\blue directory:

                                                                        *
************************************************************************/

#include <direct.h>
#include <stdio.h>

int main(void)
{

    printf("Changing to the root directory.\n");

    if (_chdir("\\"))
       perror(NULL);
    else
       printf("Changed to the root directory.\n\n");

    printf("Changing to directory '\\red\\green\\blue'.\n");

    if (_chdir("\\red\\green\\blue"))
       perror(NULL);
    else
       printf("Changed to directory '\\red\\green\\blue'.\n");

    return 0;

/***********  The output should be similar to:  **********

  Changing to the root directory.
  Changed to the root directory.

  Changing to directory '\red\green\blue'.
  Changed to directory '\red\green\blue'.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _chdrive - Change Current Working Drive
o _getcwd - Get Path Name of Current Directory
o _getdcwd - Get Full Path Name of Current Directory
o _getdrive - Get Current Working Drive
o system - Invoke the Command Processor
o _mkdir - Create New Directory
o _rmdir - Remove Directory
o system - Invoke the Command Processor
o direct.h


ΓòÉΓòÉΓòÉ 6.23. _chdrive - Change Current Working Drive ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <direct.h>

int _chdrive(int drive);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _chdrive function changes the current working drive to the drive specified.
The drive variable is an integer value representing the number of the new
working drive (A: is 1, B: is 2, and so on).

To change the default drive, include <os2.h>, define INCL_DOSFILEMGR, and use
DosSetDefaultDisk to pass the appropriate command to the operating system. You
can also use DosQueryCurrentDisk to query the disk. For more information, refer
to the OS/2 2.0 Toolkit documentation.

If _chdrive is successful in changing the working drive, it returns 0.  A
return value of -1 indicates an error; in this case, _chdrive sets errno to
EOS2ERR.

Example of _chdrive


ΓòÉΓòÉΓòÉ <hidden> Example of _chdrive ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example uses _chdrive to change the current working drive to C:.

                                                                        *
************************************************************************/

#include <direct.h>
#include <stdio.h>

int main(void)
{
    if (_chdrive(3))
         printf("Cannot change current working drive
                  to 'C' drive.\n");
    else
    {
         printf("Current working drive changed to ");
         printf("'%c' drive.\n", ('A'+_getdrive() - 1) );
    }

    return 0;


/**************  The output should be similar to:  **********************

   Current working drive changed to 'C' drive.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _chdir - Change Current Working Directory
o _getcwd - Get Path Name of Current Directory
o _getdcwd - Get Full Path Name of Current Directory
o _getdrive - Get Current Working Drive
o _mkdir - Create New Directory
o _rmdir - Remove Directory
o direct.h


ΓòÉΓòÉΓòÉ 6.24. _chmod - Change File Permission Setting ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <io.h>
#include <sys\stat.h>

int _chmod(char *pathname, int pmode);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _chmod function changes the permission setting of the file specified by
pathname. The permission setting controls access to the file for reading or
writing. The pmode expression contains one or both of the constants S_IWRITE
and S_IREAD, defined in <sys\stat.h>. You can use the _chmod function only if
the file is closed. The meanings of the values of the pmode argument are:

Value                   Meaning
S_IREAD                 Reading permitted
S_IWRITE                Writing permitted
S_IREAD | S_IWRITE      Reading and writing permitted.

If you do not give permission to write to the file, the _chmod function makes
the file read-only. With the OS/2 operating system, all files are readable; you
cannot give write-only permission. Thus, the modes S_IWRITE and S_IREAD |
S_IWRITE set the same permission.

Specifying a pmode of S_IREAD is similar to making a file read-only with the
ATTRIB system command.

The _chmod function returns the value 0 if it successfully changes the
permission setting.  A return value of -1 shows an error; in this case, the
_chmod function set errno to one of the following values:

Value          Meaning
ENOENT         The system cannot find the file or the path that you specified,
               or the file name was incorrect.
EOS2ERR        The call to the operating system was not successful.
EINVAL         The mode specified was not valid.

Example of _chmod


ΓòÉΓòÉΓòÉ <hidden> Example of _chmod ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example opens the file chmod.dat for writing after checking the file to
see if writing is permissible. It then writes from the buffer to the opened
file. This program takes file names passed as arguments and sets each to
read-only.

                                                                        *
************************************************************************/

#include <sys\stat.h>
#include <io.h>
#include <stdio.h>
#include <stdlib.h>

int main(void)
{
   if (-1 == _access("chmod.dat",00))
                        /* Check if file exists. */
   {
      printf("\nCreating chmod.dat.\n");
      system("echo Sample Program > chmod.dat");
      printf("_chmod chmod.dat to be readonly.\n");

      if (-1 == _chmod("chmod.dat",S_IREAD))
         perror("_chmod failed");

      if (-1 == _access("chmod.dat",02))
         printf("File chmod.dat is now readonly.\n\n");

      printf("Run this program again to erase chmod.dat.\n\n");
   }
   else
   {
      printf("\nFile chmod.dat exist.\n");
      printf("_chmod chmod.dat to become writable.\n");

      if (-1 == _chmod("chmod.dat",S_IWRITE))
         perror("_chmod failed");

      system("erase  chmod.dat");

      printf("File chmod.dat removed.\n\n");
   }
   return 0;

/************  If chmod.dat does not exist,  ************************
*******  the output should be similar to:  ****************

      Creating chmod.dat.
      _chmod chmod.dat to be readonly.
      File chmod.dat is now readonly.
      Run this program again to erase chmod.dat.

**********************************************************/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _access - Determine Access Mode
o _sopen - Open Shared File
o _umask - Sets File Mask of Current Process
o sys\stat.h
o io.h


ΓòÉΓòÉΓòÉ 6.25. _chsize - Alter Length of File ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <io.h>

int _chsize(int handle, long size);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _chsize function lengthens or cuts off the file associated with handle to
the length specified by size. You must open the file in a mode that permits
writing. The _chsize function adds null characters (\0) when it lengthens the
file. When _chsize cuts off the file, it erases all data from the end of the
shortened file to the end of the original file.

The _chsize function returns the value 0 if it successfully changes the file
size.  A return value of -1 shows an error, and _chsize sets errno to one of
the following values:

Value          Meaning
EACCESS        The specified file is locked against access.
EBADF          The file handle is not valid, or the file is not open for
               writing.
ENOSPC         There is no space left on the device.
EOS2ERR        The call to the operating system was not successful.

Example of _chsize


ΓòÉΓòÉΓòÉ <hidden> Example of _chsize ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example opens a file named sample.dat and returns the current length of
that file. It then alters the size of sample.dat and returns the new length of
that file.

                                                                        *
************************************************************************/

#include <io.h>
#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>

int main(void)
{
   long length;
   int  fh;

   printf("\nCreating sample.dat.\n");
   system("echo Sample Program > sample.dat");

   if (-1 == (fh = _open("sample.dat",O_RDWR | O_APPEND)))
   {
      printf("Unable to open sample.dat.\n");
      return 1;
   }

   if (-1 == (length = _filelength(fh)))
   {
      printf("Unable to determine length of sample.dat.\n");
      return 1;
   }

   printf("Current length of sample.dat is %d.\n",length);
   printf("Changing the length of sample.dat to 20.\n");

   if (-1 == (_chsize(fh,20)))
   {
      perror("_chsize failed");
      return 1;
   }

   if (-1 == (length = _filelength(fh)))
   {
      printf("Unable to determine length of sample.dat.\n");
      return 1;
   }
   printf("New length of sample.dat is %d.\n",length);

   _close(fh);
   return 0;

/*****  The output should be similar to:  ************

      Creating sample.dat.
      Current length of sample.dat is 17.
      Changing the length of sample.dat to 20.
      New length of sample.dat is 20.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _filelength - Determine File Length
o _lseek - Move File Pointer
o io.h


ΓòÉΓòÉΓòÉ 6.26. clearerr  - Reset Error Indicators ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

void clearerr (FILE *stream);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The clearerr function resets the error indicator and end-of-file indicator for
the specified stream. Once set, the indicators for a specified stream remain
set until your program calls clearerr or rewind. The fseek function also clears
the end-of-file indicator.

Example of clearerr


ΓòÉΓòÉΓòÉ <hidden> Example of clearerr ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example reads a data stream and then checks that a read error has not
occurred.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>

FILE *stream;
int c;

int main(void)
{
   if ((stream = fopen("myfile.dat", "r")) != NULL)
   {
      if ((c=getc(stream)) == EOF)
      {
         if (ferror(stream))
         {
            perror("Read error");
            clearerr(stream);
         }
      }
   }
   else
      exit(0);
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o feof  - Test End-of-File Indicator
o ferror  - Test for Read/Write Errors
o perror  - Print Error Message
o rewind  - Adjust Current File Position
o strerror  - Set Pointer to Runtime Error Message
o _strerror - Set Pointer to System Error String
o stdio.h


ΓòÉΓòÉΓòÉ 6.27. _clear87 - Clear Floating-Point Status Word ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <float.h>  /* also defined in <builtin.h> */

unsigned int _clear87(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _clear87 function gets the floating-point status word and then clears it.
The floating-point status word is a combination of the numeric coprocessor
status word and other conditions that the numeric exception handler detects,
such as floating-point stack overflow and underflow.

The _clear87 function only affects the current thread. It does not affect any
other threads that may be processing.

The bits in the value returned reflect the floating-point status before the
call to _clear87 was made.

Example of _clear87


ΓòÉΓòÉΓòÉ <hidden> Example of _clear87 ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example takes a number close to 0 as a double and assigns it to a float.
The result is a loss of significance, y becomes a denormal number, and the
underflow bit of the floating-point status word is set. The _clear87 function
gets the current floating-point status word and then clears it, and the printf
function prints it as immediate data. The result shows the change in the
floating-point word because of the loss of significance.

The program then assigns the denormal y to another variable, causing the
denormal bit to be set in the floating-point status word.  Again, the _clear87
gets the current status word and clears it, and printf prints it to the screen.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <float.h>

double a = 1e-40;
double b;
float y;

int main(void)
{
   unsigned int statword;
   unsigned int old_cw;

   /*  change control word to mask all exceptions */
   _control87(0x037f,0xffff);

   /* Assignment of the double to the float y is inexact; */
   /*       the underflow bit is set.                     */
   y = a;
   statword = _clear87();
   printf("floating-point status = 0x%.4x after underflow\n",
           statword);

   statword = _status87();
   printf("cleared floating-point status word = 0x%.4x\n",
           statword);

   /*  reset floating point status word  */
   _fpreset();

   /*  change control word to mask all exception */
   _control87(0x037f,0xffff);

   /* Reassigning the denormal y to the double b */
   /*   causes the denormal bit to be set. */
   b = y;
   statword = _clear87();
   printf("floating-point status = 0x%.4x for denormal\n",
           statword);

   /*  reset floating point status word  */
   _fpreset();

   return 0;


   /* The expected output is:

      floating-point status = 0x0030 after underflow
      cleared floating-point status word = 0x0000
      floating-point status = 0x0002 for denormal  */
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _control87 - Set Floating-Point Status Word
o _status87 - Get Floating-Point Status Word
o _fpreset - Reset Floating-Point Unit
o float.h


ΓòÉΓòÉΓòÉ 6.28. clock  - Determine Processor Time ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <time.h>

clock_t clock(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The clock function returns an approximation of the processor time used by the
program since the beginning of an implementation-defined time-period that is
related to the program invocation. To obtain the time in seconds, divide the
value returned by clock by the value of the macro CLOCKS_PER_SEC.

If the value of the processor time is not available or cannot be represented,
clock returns the value (clock_t)-1.

To measure the time spent in a program, call the clock function at the start of
the program, and subtract its return value from the value returned by
subsequent calls to clock.

Example of clock


ΓòÉΓòÉΓòÉ <hidden> Example of clock ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example prints the time elapsed since the program was invoked.

                                                                        *
************************************************************************/

#include <time.h>
#include <stdio.h>

double time1, timedif;/* use doubles to show small values */

int main(void)
{
    time1 = (double) clock();            /* get initial time */
    time1 = time1 / CLOCKS_PER_SEC;      /*    in seconds    */
   .
   .
   .
    /* call clock a second time */
    timedif = ( ((double) clock()) / CLOCKS_PER_SEC) - time1;
    printf("The elapsed time is %lf seconds\n", timedif);
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o difftime  - Compute Time Difference
o time  - Determine Current Time
o time.h


ΓòÉΓòÉΓòÉ 6.29. _control87 - Set Floating-Point Status Word ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <float.h>  /* also defined in <builtin.h> */

unsigned int _control87(unsigned int new, unsigned int mask);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _control87 function gets the current floating-point control word and then
sets it. The floating-point control word specifies the precision, rounding, and
infinity modes of the floating-point chip.

You can mask or unmask current floating-point exceptions using the _control87
function. If the value for the mask is equal to 0, _control87 gets the
floating-point control word. If the mask is nonzero, _control87 sets a new
value for the control word in the manner described below, and returns the
previous value of the control word. For any bit in the mask equal to 1, the
corresponding bit in new updates the control word. This is equivalent to the
expression:

   fpcntrl = ((fpcntrl & ~ mask) Γöé (new & mask))

where fpcntrl is the floating-point control word.

The _control87 function is used for the current thread only. It does not affect
any other threads that may be processing.

Warning: If you change the content of the floating-point control word:

o The behavior of the math functions with regard to domain and range errors may
  be undefined.
o Math functions may not handle infinity and NaN values correctly.
o Some floating-point exceptions may not occur, while other new ones may occur.
o Resetting the EM_INEXACT bit may cause SIG_FPE exceptions, which decrease
  performance.
o If the precision or rounding bits are modified, you can reduce the precision
  available for float and double variables.
For information on bits in the control word and handling floating-point
exceptions, see the Programming Guide.

The bits in the returned value reflect the floating-point control word before
the call.

Example of _control187


ΓòÉΓòÉΓòÉ <hidden> Example of _control187 ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example prints the initial control word in hexadecimal, and then
illustrates different representations of 0.1, depending on the precision.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <float.h>

double a = .13;

int main(void)
{
    printf("control = 0x%.4x\n",
    _control87(CW_DEFAULT, 0));
                      /* Get control word */

    printf("a*a = .0169 = %.15e\n",a*a);
    _control87(PC_24, MCW_PC);
                     /* Set precision to 24 bits */

    printf("a*a = .0169 (rounded to 24 bits) = %.15e\n",a*a);

    _control87(CW_DEFAULT, 0xffff);
                     /* Restore to initial default */
    printf("a*a = .0169 = %.15e\n",a*a);

    return 0;

    /* Possible output could be:

       control = 0x0362
       a*a = .0169 = 1.690000000000000e-02
       a*a = .0169 (rounded to 24 bits) = 1.689999046325684e-03
       a*a = .0169 = 1.690000000000000e-02                      */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _clear87 - Clear Floating-Point Status Word
o _status87 - Get Floating-Point Status Word
o _fpreset - Reset Floating-Point Unit
o Floating Point Variables
o signal Install Interrupt Handlers
o float.h


ΓòÉΓòÉΓòÉ 6.30. _close - Closes File Associated with Handle ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <io.h>

int _close(int handle);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _close function closes the file associated with the handle. Use _close if
you opened the handle with _open. If you opened the handle with fopen, use
fclose to close it.

The _close function returns 0 if it successfully closes the file. A return
value of -1 shows an error, and _close sets errno to EBADF, showing an
incorrect file handle argument.

Example of _close


ΓòÉΓòÉΓòÉ <hidden> Example of _close ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example opens the file edclose.dat and then closes it using the _close
function.

                                                                        *
************************************************************************/

#include <io.h>
#include <stdio.h>
#include <fcntl.h>
#include <sys\stat.h>

int main(void)
{
   int fh;

   printf("\nCreating edclose.dat.\n");

   if ( -1 ==
           (fh = _open("edclose.dat",
                      O_RDWR | O_CREAT | O_TRUNC,
                      S_IREAD | S_IWRITE)))
   {
      perror("Unable to open edclose.dat");
      return 1;
   }

   printf("File was successfully opened.\n");

   if ( -1 == _close(fh))
   {
      perror("Unable to close edclose.dat");
      return 1;
   }

   printf("File was successfully closed.\n");
   return 0;

/****************  The output should be similar to:  ********************

      Creating edclose.dat.
      File was successfully opened.
      File was successfully closed.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fclose  - Close Stream
o _creat - Create New File
o _open - Open File
o _sopen - Open Shared File
o io.h


ΓòÉΓòÉΓòÉ 6.31. cos  - Calculate Cosine ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h>

double cos(double x);  /* Calculate the cosine of x */


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The cos function calculates the cosine of x. The value x is expressed in
radians. If x is too large, a partial loss of significance in the result may
occur.

Example of cos


ΓòÉΓòÉΓòÉ <hidden> Example of cos ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example calculates y to be the cosine of x.

                                                                        *
************************************************************************/

#include <math.h>
#include <stdio.h>

int main(void)
{
   double x, y;

   x = 7.2;
   y = cos(x);

   printf("cos( %lf ) = %lf\n", x, y);
}

/*********************  Output should be similar to:  *******************

cos( 7.200000 ) = 0.608351
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o acos  - Calculate Arccosine
o cosh  - Calculate Hyperbolic Cosine
o _facos - Calculate Arccosine
o _fcos - Calculate Cosine
o _fcossin - Calculate Cosine and Sine
o _fsincos - Calculate Sine and Cosine
o sin  - Calculate Sine
o sinh  - Calculate Hyperbolic Sine
o tan  - Calculate Tangent
o tanh  - Calculate Hyperbolic Tangent
o math.h


ΓòÉΓòÉΓòÉ 6.32. cosh  - Calculate Hyperbolic Cosine ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h>

double cosh(double x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The cosh function calculates the hyperbolic cosine of x. The value x is
expressed in radians. If the result is too large, cosh returns the value
HUGE_VAL and sets errno to ERANGE.

Example of cosh


ΓòÉΓòÉΓòÉ <hidden> Example of cosh ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example calculates y to be the hyperbolic cosine of x.

                                                                        *
************************************************************************/

#include <math.h>
#include <stdio.h>

int main(void)
{
   double x,y;

   x = 7.2;
   y = cosh(x);

   printf("cosh( %lf ) = %lf\n", x, y);
}

/*********************  Output should be similar to:  *******************

cosh( 7.200000 ) = 669.715755
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o acos  - Calculate Arccosine
o cos  - Calculate Cosine
o _facos - Calculate Arccosine
o _fcos - Calculate Cosine
o _fcossin - Calculate Cosine and Sine
o _fsincos - Calculate Sine and Cosine
o sin  - Calculate Sine
o sinh  - Calculate Hyperbolic Sine
o tan  - Calculate Tangent
o tanh  - Calculate Hyperbolic Tangent
o math.h


ΓòÉΓòÉΓòÉ 6.33. _cprintf - Print Characters to Screen ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <conio.h>

int _cprintf(char *format-string, argument-list);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _cprintf function formats and sends a series of characters and values
directly to the screen, using the _putch function to send each character.

The format-string has the same form and function as the format-string parameter
for printf. Format specifications in the format-string determine the output
format for any argument-list that follows. See printf for a description of the
format-string.

Note:  Unlike the fprintf, printf, and sprintf functions, _cprintf does not
translate line feed characters into output of a carriage-return followed by a
line-feed.

The _cprintf function returns the number of characters printed.

Example of _cprintf


ΓòÉΓòÉΓòÉ <hidden> Example of _cprintf ΓòÉΓòÉΓòÉ

/************************************************************************
*
The following program uses _cprintf to write strings to the screen.

                                                                        *
************************************************************************/

#include <conio.h>

int main(void)
{
    char buffer[24];

    _cprintf("\nPlease enter a file name:\n");
    _cscanf("%23s", buffer);

    _cprintf("\nThe file name you entered was %23s.", buffer);

    return 0;

/******************  The output should be similar to:  ******************

    Please enter a file name:
                            file.dat
    The file name you entered was                file.dat.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _cscanf - Read Data from Keyboard
o fprintf  - Write Formatted Data
o printf  - Formatted Print
o _putch - Write Character to Screen
o sprintf  - Formatted Print to Buffer
o conio.h


ΓòÉΓòÉΓòÉ 6.34. _cputs - Write String to Screen ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <conio.h>

int _cputs(char *str);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _cputs function writes directly to the screen the string to which str
points. The string str must end with a null character (\0). The _cputs function
does not automatically add a carriage-return followed by a line-feed to the
string after writing.

If successful, _cputs returns 0. Otherwise, it returns a nonzero value.

Example of _cputs


ΓòÉΓòÉΓòÉ <hidden> Example of _cputs ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example puts a prompt out to the screen.

                                                                        *
************************************************************************/

#include <conio.h>

int main(void)
{   char *buffer = "Insert data disk in drive a: \r\n";

    _cputs(buffer);
    return 0;

/***************  The output should be similar to:  *********************

    Insert data disk in drive a:
*/

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _cgets - Read String of Characters from Keyboard
o fputs  - Print Strings
o _putch - Write Character to Screen
o puts  - Write a String
o conio.h


ΓòÉΓòÉΓòÉ 6.35. _creat - Create New File ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <io.h>
#include <sys\stat.h>

int _creat(char *pathname, int pmode);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _creat function either creates a new file or opens and truncates an
existing file. If the file specified by pathname does not exist, _creat creates
a new file with the given permission setting and opens for writing in text
mode. If the file already exists, and the read-only attribute and sharing
permissions allow writing, _creat truncates the file to length 0. This destroys
the previous contents of the file and opens it for writing in text mode. The
_creat function always opens a file in text mode for reading and writing.

The permission setting pmode applies to newly created files only. The new file
receives the specified permission setting after you close it for the first
time. The pmode integer expression contains one or both of the constants
S_IWRITE and S_IREAD, defined in <sys\stat.h>. The values of the pmode argument
and their meanings are:

Value                   Meaning
S_IREAD                 Reading permitted
S_IWRITE                Writing permitted
S_IREAD | S_IWRITE      Reading and writing permitted.

If you do not give permission to write to the file, the file is a read-only
file. On the OS/2 operating system, you cannot give write-only permission.
Thus, the modes S_IWRITE and S_IREAD | S_IWRITE have the same results. The
_creat function applies the current file permission mask to pmode before
setting the permissions. (See _umask - Sets File Mask of Current Process for
more information about file permission masks.)

When writing new code, you should use _open rather than _creat.

Specifying a pmode of S_IREAD is similar to making a file read-only with the
ATTRIB system command.

The _creat function returns a handle for the created file if the call is
successful. A return value of -1 shows an error, and _creat sets errno to one
of the following values:

Value          Meaning
EACCESS        File sharing violated.
EINVAL         The mode specified was not valid.
EMFILE         No more file handles are available.
ENOENT         The path name was not found, or the file name was incorrect.
EOS2ERR        The call to the operating system was not successful.

Example of _creat


ΓòÉΓòÉΓòÉ <hidden> Example of _creat ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example creates the file sample.dat so it can be read from and written to.

                                                                        *
************************************************************************/

#include <sys\stat.h>
#include <io.h>
#include <stdio.h>

int main(void)
{
   int fh;
   fh = _creat("sample.dat", S_IREAD | S_IWRITE);
   if ( -1 == fh)
   {
      perror("Error in creating sample.dat");
      return 1;
   }
   else
      printf("Successfully created sample.dat.\n");

   _close(fh);
   return 0;

/******************  Expected output is:  *******************************

      Successfully created sample.dat.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _chmod - Change File Permission Setting
o _close - Closes File Associated with Handle
o _open - Open File
o _fdopen - Associates Input Or Output With File
o _sopen - Open Shared File
o _umask - Sets File Mask of Current Process
o sys\stat.h
o io.h


ΓòÉΓòÉΓòÉ 6.36. _CRT_init - Initialize DLL Runtime Environment ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

   int _CRT_init(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extended

Before you can call any C/C++ Tools library functions, you must first
initialize the runtime environment. Use the function _CRT_init, which is
provided in the runtime libraries.

If the runtime environment is successfully initialized, _CRT_init returns 0.  A
return code of -1 indicates an error. If an error occurs, an error message is
written to file handle 2, which is the usual destination of stderr.

If your DLL contains C++ code, you must also call __ctordtorInit after
_CRT_init to ensure that static constructors and destructors are initialized
properly.  The prototype for __ctordtorInit is:

   void __ctordtorInit(void);

Note:  If you are providing your own version of the _matherr function to be
used in your DLL, you must call the _exception_dllinit function after the
runtime environment is initialized. Calling this function ensures that the
proper _matherr function will be called during exception handling. The
prototype for this function is:

   void _Optlink _exception_dllinit( int (*)(struct exception *) );

The parameter required is the address of your _matherr function.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _DLL_InitTerm - Initialize and Terminate DLL Environment
o _CRT_term - Terminate DLL Runtime Environment


ΓòÉΓòÉΓòÉ 6.37. _CRT_term - Terminate DLL Runtime Environment ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

   void _CRT_term(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extended

If your DLL is statically linked, you must use the _CRT_term function to
correctly terminate the C runtime environment.  The _CRT_term function is
provided in the C/C++ Tools runtime libraries.

If your DLL contains C++ code, you must also call __ctordtorTerm before you
call _CRT_term to ensure that static constructors and destructors are
terminated correctly. The prototype for __ctordtorTerm is:

   void __ctordtorTerm(void);

Once you have called _CRT_term, you cannot call any other library functions.

If your DLL is dynamically linked, you cannot call library functions in the
termination section of your _DLL_InitTerm function. If your termination routine
requires calling library functions, you must register the termination routine
with DosExitList. Note that all DosExitList routines are called before DLL
termination routines.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _CRT_init - Initialize DLL Runtime Environment
o _DLL_InitTerm - Initialize and Terminate DLL Environment


ΓòÉΓòÉΓòÉ 6.38. _cscanf - Read Data from Keyboard ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <conio.h>

int _cscanf(char *format-string, argument-list);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _cscanf function reads data directly from the keyboard to the locations
given by argument-list, if any are specified. The _cscanf function uses the
_getche function to read characters. Each argument must be a pointer to a
variable with a type that corresponds to a type specifier in the format-string.

The format-string controls the interpretation of the input fields and has the
same form and function as the format-string argument for the scanf function.
See scanf for a description of the format-string.

Note:  Although _cscanf normally echoes the input character, it does not do so
if the last action was a call to _ungetch.

The _cscanf function returns the number of fields that were successfully
converted and assigned. The return value does not include fields that were read
but not assigned.

The return value is EOF for an attempt to read at the end of the file. A return
value of 0 means that no fields were assigned.

Example of _cscanf


ΓòÉΓòÉΓòÉ <hidden> Example of _cscanf ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses _cscanf to read strings from the screen.

                                                                        *
************************************************************************/

#include <conio.h>

int main(void)
{
    char buffer[24];

    _cprintf("\nPlease enter a file name:\n");
    _cscanf("%23s", buffer);

    _cprintf("\nThe file name you entered was %23s.", buffer);

    return 0;

/******************  The output should be similar to:  ******************

    Please enter a file name:
                            file.dat
    The file name you entered was                file.dat.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fscanf  - Read Formatted Data
o _getch - _getche - Read Character from Keyboard
o scanf  - Read Data
o sscanf  - Read Data
o _ungetch - Push Character Back to Keyboard
o conio.h


ΓòÉΓòÉΓòÉ 6.39. ctime  - Convert Time ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <time.h>

char *ctime(const time_t *time);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The ctime function converts the time value pointed to by time to local time in
the form of a character string.  A time value is usually obtained by a call to
the time function.

The string result produced by ctime contains exactly 26 characters and has the
format

   "%.3s %.3s%3d %.2d:%.2d:%.2d %d\n"
for example:

   Mon Jul 16 02:03:55 1987\n\0

The ctime function uses a 24-hour clock format.  The days are abbreviated to:
Sun, Mon, Tue, Wed, Thu, Fri, and Sat.  The months are abbreviated to:  Jan,
Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, and Dec.  All fields have a
constant width. Dates with only one digit are preceded either with a zero or a
blank space, depending on the compiler. The new-line character (\n) and the
null character (\0) occupy the last two positions of the string.

Note:  The asctime, ctime, and other time functions may use a common,
       statically allocated buffer for holding the return string.  Each call to
       one of these functions may destroy the result of the previous call.

The time and date functions begin at 00:00:00 Universal Time, January 1, 1970.

The ctime function returns a pointer to the character string result.  There is
no error return value.  The ctime function is equivalent to:

   asctime(localtime(&anytime))

Example of ctime


ΓòÉΓòÉΓòÉ <hidden> Example of ctime ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example polls the system clock by using the library function time.  It
then prints a message giving the current date and time.

                                                                        *
************************************************************************/

#include <time.h>
#include <stdio.h>

int main(void)
{
   time_t ltime;

   time(<ime);
   printf("the time is %s", ctime(<ime));
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o asctime  - Convert Time
o gmtime  - Convert Time
o localtime  - Convert Time
o mktime  - Convert Local Time
o strftime  - Convert to Formatted Time
o time  - Determine Current Time
o time.h


ΓòÉΓòÉΓòÉ 6.40. _cwait - Wait for Child Process ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <process.h>

int _cwait(int *stat_loc, int process_id, int action_code);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _cwait function delays the completion of a parent process until the child
process specified by process_id ends.

The process_id is the value returned by the _spawn function that started the
child process. If the specified child process ends before _cwait is called,
_cwait returns to the calling process immediately with a value of -1. If the
value of process_id is 0, the parent process waits until all of its child
processes end.

If the variable pointed to by stat_loc is NULL, the _cwait function does not
use it.  If it is not NULL, _cwait places information about the return status
and the return code of the child process in the location to which stat_loc
points.

If the child process ended normally with a call to the OS/2 DosExit API, the
lowest-order byte of the variable pointed to by stat_loc is 0.  The next
highest-order byte contains the lowest-order byte of the argument passed to
DosExit by the child process. The value of this byte depends on how the child
process caused the system to call DosExit.  If the child called exit, _exit, or
return from main, or used a DosExit coded into the program, the byte contains
the lowest-order byte of the argument the child passed to exit, _exit, or
return. The value of the byte is undefined if the child caused a DosExit call
simply by reaching the end of main.

If the child process ended abnormally (without a call to DosExit), the
lowest-order byte of the variable pointed to by stat_loc contains the return
code from the OS/2 DosWaitChild API, and the next higher-order byte is 0. See
the OS/2 online reference for details about the DosWaitChild return codes.

The action_code specifies when the parent process is to start running again.
Values for action_code include:

Action Code Meaning
WAIT_CHILD
          The parent process waits until the specified child process ends.
WAIT_GRANDCHILD
          The parent process waits until the child process and all of the child
          processes of that process end.

The action code values are defined in <process.h>.

Note:  Because the size of an int is only 2 bytes in 16-bit compilers, if you
are migrating a 16-bit program, some parts of your programs may have to be
rewritten if they use this function.

An alternative to this function is the DosWaitChild API call.

At the normal end of the child process, _cwait returns the process identifier
of the child to the parent process. If a child process ends abnormally, _cwait
returns -1 to the parent process and sets errno to EINTR. In the case of an
error, _cwait returns immediately with a value of -1 and sets errno to one of
the following values:

Value     Meaning
EINVAL    Incorrect action code
ECHILD    No child process exists, or the process identifier is incorrect.

Example of _cwait


ΓòÉΓòÉΓòÉ <hidden> Example of _cwait ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example creates a new process called child.exe.  The parent calls _cwait
and waits for the child to end.  The parent then displays the child's return
information in hexadecimal.

                                                                       *
***********************************************************************/

#include <stdio.h>
#include <process.h>
#include <errno.h>

int stat_child;

int main(void)
{
    int i, result;

    /* spawn a child and 'cwait' for it to finish*/
    if ((result = _spawnl(P_NOWAIT,"child","child","1",
          NULL)) != -1)
       {
       if ((i= _cwait(&stat_child,result,WAIT_CHILD)) != result)
          printf("Error ...expected pid from child");
       else {
          if (errno == 0) {
              printf("Child process ended successfully and ...\n");
              printf("program returned to the Parent process.\n");
          }
          else
              printf("Child process had an error\n");
       }
   }
   else
      printf("Error ...could not spawn a child process\n");

   return 0;
}
/**************  If the source code for child.exe is:  ****************

#include <stdio.h>

int main(void)
{
    puts("This line was written by child.exe");
}
*/

***************  then the output should be similar to:  **************

   This line was written by child.exe
   Child process ended successfully and ...
   program returned to the Parent process.
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o exit  - End Program
o _exit - End Process
o _spawnl -_spawnvpe -Start and Run Child Processes
o _wait - Wait for Child Process
o return
o process.h


ΓòÉΓòÉΓòÉ 6.41. _debug_calloc - Reserve and Initialize Storage ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#define __DEBUG_ALLOC__
#include <stdlib.h>  /* also defined in <malloc.h> */

void *_debug_calloc(size_t num, size_t size,
                           const char *pFilename,
                           size_t linenum);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _debug_calloc function is the debug version of calloc, and performs the
same function as calloc. It reserves storage space for an array of num
elements, each of length size bytes, and initializes all bits of each element
to 0.

In addition, _debug_calloc makes an implicit call to the _heap_check function.
It also stores the name of the file pFilename and the line number linenum where
the storage is allocated.  This information can be used later by _heap_check
and the _dump_allocated function.

The _debug_calloc function returns a pointer to the reserved space. If not
enough storage is available, or if num or size is 0, _debug_calloc returns
NULL.

Example of _debug_calloc


ΓòÉΓòÉΓòÉ <hidden> Example of _debug_calloc ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example reserves storage of 124 bytes. It then attempts to write to
storage that was not allocated.  When _debug_calloc is called again,
_heap_check detects the error, generates several messages, and stops the
program.

Note:  Although the function calloc is coded in the example, the
__DEBUG_ALLOC__ macro redefines calloc to _debug_calloc.

                                                                        *
************************************************************************/

#ifndef __DEBUG_ALLOC__      /* this macro could also be defined */
   #define __DEBUG_ALLOC__   /*      from the command line       */
#endif
#include <stdlib.h>
#include <stdio.h>

int main(void)
{
   char *ptr;

   if (( ptr = calloc(2, 62) ) == NULL)
   {
      printf( "Could not allocate memory block.\n" );
      return EXIT_FAILURE;
   }

   *(ptr + 124) = 'a';     /* overwrites storage that was not allocated */

   ptr = calloc(23, 45); /* this call to calloc invokes _heap_check */

   printf("_debug_calloc did not detect
   that a memory block was overwritten.\n");

   return EXIT_FAILURE;

   /* Possible output is:

      Memory was overwritten after the allocated memory block
      that starts at address 0x000B0F10.
      The first eight bytes of the memory block (in hex) are: 0000000000000000.
      This memory block was (re)allocated at line number 11 in TDCALLC.C.       */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o calloc  - Reserve and Initialize Storage
o _debug_free - Release Storage Blocks
o _debug_malloc - Reserve Storage Blocks
o _debug_realloc - Change Reserved Storage Block Size
o _dump_allocated - Get Information about Allocated Storage
o _heap_check - Validate Run-Time Storage Heap
o Using the Debug Memory Management Functions
o malloc.h
o stdlib.h


ΓòÉΓòÉΓòÉ 6.42. _debug_free - Release Storage Blocks ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#define __DEBUG_ALLOC__
#include <stdlib.h>  /* also defined in <malloc.h> */

void _debug_free(void *ptr, const char *pFilename,
                        size_t linenum);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _debug_free function is the debug version of free, and performs the same
function as free. It frees the block of storage pointed to by ptr that has been
allocated by either a normal or a debug version of the memory management
functions.

In addition, _debug_free makes an implicit call to the _heap_check function. It
also stores the file name pFilename and  the line number linenum where the
storage is freed.  This information can be used later by _heap_check and the
_dump_allocated function.

Note:  If the block of storage pointed to by ptr was not allocated using the
       memory management functions or was previously freed, a message appears
       and the program ends.

There is no return value.

Example of _debug_free


ΓòÉΓòÉΓòÉ <hidden> Example of _debug_free ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example reserves two blocks of 62 bytes each.  It then frees the first
block and attempts to overwrite the freed storage.  When _debug_free is called
a second time, _heap_check detects the error, prints out several messages, and
stops the program.

Note:  Although the function free is coded in the example, the __DEBUG_ALLOC__
macro redefines free to _debug_free.

                                                                        *
************************************************************************/

#ifndef __DEBUG_ALLOC__      /* this macro could also be defined */
   #define __DEBUG_ALLOC__   /*      from the command line       */
#endif
#include <stdlib.h>
#include <stdio.h>

int main(void)
{
   char *ptr1;
   char *ptr2;

   if ( (( ptr1 = malloc(62) ) == NULL)
                || (( ptr2 = malloc(62) ) == NULL) )
   {
      printf("Could not allocate memory block.\n");
      return EXIT_FAILURE;
   }

   free(ptr1);

   *(ptr1 - 1) = 'a';   /* overwrites storage that has been freed */

   free(ptr2);         /* this call to free invokes _heap_check */

   printf("_debug_free did not detect that a free memory block
           was overwritten.\n");

   return EXIT_FAILURE;

   /* Possible output is:

      Memory was overwritten before the free memory block that starts
            at address 0x00150010.
      The first eight bytes of the memory block (in hex) are: B5B5A5A500000000.
      This memory block was freed at line number 17 in TDFREE.C.                */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _debug_calloc - Reserve and Initialize Storage
o _debug_malloc - Reserve Storage Blocks
o _debug_realloc - Change Reserved Storage Block Size
o _dump_allocated - Get Information about Allocated Storage
o free  - Release Storage Blocks
o _heap_check - Validate Run-Time Storage Heap
o Using the Debug Memory Management Functions
o malloc.h
o stdlib.h


ΓòÉΓòÉΓòÉ 6.43. _debug_heapmin - Release Unused Memory in the Heap ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#define __DEBUG_ALLOC__
#include <stdlib.h>  /* also defined in <malloc.h> */

int _debug_heapmin(const char *pFilename, size_t linenum);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _debug_heapmin function is the debug version of _heapmin, and performs the
same function as _heapmin. It returns all unused memory from the run-time heap
to the operating system.

In addition, _debug_heapmin makes an implicit call to the _heap_check function.
It also stores the file name pFilename and the line number linenum where the
memory is returned.  This information can be used later by _heap_check and the
_dump_allocated function.

If successful, _debug_heapmin returns 0; otherwise, it returns -1.

Example of _debug_heapmin


ΓòÉΓòÉΓòÉ <hidden> Example of _debug_heapmin ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example allocates 5000 bytes of storage, then changes the storage size to
35 bytes, and uses _debug_heapmin to return the unused memory to the operating
system. The storage is then freed, and the program attempts to overwrite the
freed storage. When _debug_heapmin is called again, _heap_check detects the
error, generates several messages, and stops the program.

Note:  Although the function _heapmin is coded in the example, the
__DEBUG_ALLOC__ macro redefines _heapmin to _debug_heapmin.

                                                                        *
************************************************************************/

#ifndef __DEBUG_ALLOC__       /* this macro could also be defined */
   #define __DEBUG_ALLOC__    /*      from the command line       */
#endif
#include <stdlib.h>
#include <stdio.h>

int main(void)
{
   char *ptr;

   ptr = malloc(5000);

   ptr = realloc(ptr, 35);

   _heapmin();    /* no allocation problems to detect */

   free(ptr);
   *ptr = 'a';     /* overwrites storage that has been freed */

   _heapmin();    /* this call to _heapmin invokes _heap_check */

   printf("_debug_heapmin did not detect
               that a free memory block was accessed\n");
   return 0;

   /* Possible output is:

      The free memory block that starts at address 0x00150010
      has been accessed.
      The first eight bytes of the memory block (in hex) are: 61B5A5A500000000.
      This memory block was freed at line number 17 in THPMIN.C.                  */

   }


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _dump_allocated - Get Information about Allocated Storage
o _heapmin - Release Unused Memory in the Heap
o _heap_check - Validate Run-Time Storage Heap
o Using the Debug Memory Management Functions
o malloc.h
o stdlib.h


ΓòÉΓòÉΓòÉ 6.44. _debug_malloc - Reserve Storage Blocks ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#define __DEBUG_ALLOC__
#include <stdlib.h>  /* also defined in <malloc.h> */

void *_debug_malloc(size_t size, const char *pFilename,
                           size_t linenum);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _debug_malloc function is the debug version of malloc, and performs the
same function as malloc. It reserves a block of storage of size bytes.

In addition, _debug_malloc makes an implicit call to the _heap_check function.
It also stores the file name pFilename and the line number linenum where the
storage is allocated.  This information can later be used by _heap_check and
the _dump_allocated function.

The _debug_malloc function returns a pointer to the reserved space.  If not
enough storage is available or if size is 0, _debug_malloc returns NULL.

Example of _debug_malloc


ΓòÉΓòÉΓòÉ <hidden> Example of _debug_malloc ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example allocates 62 bytes of storage. It then attempts to write to
storage that was not allocated.  When _debug_malloc is called again,
_heap_check detects the error, generates several messages, and stops the
program.

Note:  Although the function malloc is coded in the example, the
__DEBUG_ALLOC__ macro redefines malloc to _debug_malloc.

                                                                        *
************************************************************************/

#ifndef __DEBUG_ALLOC__     /* this macro could also be defined */
   #define __DEBUG_ALLOC__  /*      from the command line       */
#endif
#include <stdlib.h>
#include <stdio.h>

int main(void)
{
   char *ptr;

   if ( (ptr = malloc(62) ) == NULL)
   {
      printf( "Could not allocate memory block.\n" );
      return EXIT_FAILURE;
   }

   *(ptr - 1) = 'a';     /* overwrites storage that was not allocated */

   ptr = malloc(2345);   /* this call to malloc invokes _heap_check */

   printf("_debug_malloc did not detect that a memory block
               was overwritten.\n");

   return EXIT_FAILURE;

   /* Possible output is:

      Memory was overwritten before the allocated memory block
      that starts at address 0x00150010.
      The first eight bytes of the memory block (in hex) are: 0000000000000000.
      This memory block was (re)allocated at line number 11 in TDMALLC.C.        */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _debug_calloc - Reserve and Initialize Storage
o _debug_free - Release Storage Blocks
o _debug_realloc - Change Reserved Storage Block Size
o _dump_allocated - Get Information about Allocated Storage
o _heap_check - Validate Run-Time Storage Heap
o malloc  - Reserve Storage Block
o Using the Debug Memory Management Functions
o malloc.h
o stdlib.h


ΓòÉΓòÉΓòÉ 6.45. _debug_realloc - Change Reserved Storage Block Size ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#define __DEBUG_ALLOC__
#include <stdlib.h>  /* also defined in <malloc.h> */

void *_debug_realloc(void *ptr, size_t size,
                            const char *pFilename,
                            size_t linenum);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _debug_realloc function is the debug version of realloc, and performs the
same function as realloc. It reallocates the block of storage pointed to by ptr
to a new size, specified in bytes. In addition, _debug_realloc makes an
implicit call to the _heap_check function.

It also stores the file name pFilename and the line number linenum where the
storage is reallocated.  This information can be used later by _heap_check and
the _dump_allocated function.

If ptr is NULL, _debug_realloc behaves like _debug_malloc.

Note:  The _debug_realloc function reallocates storage that has been allocated
       by either a normal or a debug version of the memory management
       functions. If the block of storage pointed to by ptr was not allocated
       using the memory management functions or was previously freed, a message
       will appear and the program will end.

The _debug_realloc function returns a pointer to the reallocated storage block.
The ptr argument to _debug_realloc is not necessarily the same as the return
value, because the storage location might be moved by _debug_realloc.

If size is 0, _debug_realloc returns NULL.  If not enough storage space is
available to expand the block to the given size, the original block is
unchanged and NULL is returned.

Example of _debug_realloc


ΓòÉΓòÉΓòÉ <hidden> Example of _debug_realloc ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example uses _debug_realloc to allocate 62 bytes of storage. It then
attempts to write to storage that was not allocated. When _debug_realloc is
called again, _heap_check detects the error, generates several messages, and
stops the program.

Note:  Although the function realloc is coded in the example, the
__DEBUG_ALLOC__ macro redefines realloc to _debug_realloc.

                                                                        *
************************************************************************/

#ifndef __DEBUG_ALLOC__      /* this macro could also be defined */
   #define __DEBUG_ALLOC__   /*      from the command line       */
#endif
#include <stdlib.h>
#include <stdio.h>

int main(void)
{
   char *ptr;

   if (( ptr = realloc(NULL, 62) ) == NULL)
   {
      printf("Could not allocate memory block.\n");
      return EXIT_FAILURE;
   }

   *(ptr - 2) = 'a';           /* overwrites storage that was not allocated */

   ptr = realloc(ptr, 2345); /* this call to realloc invokes _heap_check */

   printf("_debug_realloc did not detect that a memory block
               was overwritten.\n");

   return EXIT_FAILURE;

   /* Possible output is:

      Memory was overwritten before the allocated memory block
      that starts at address 0x00150010.
      The first eight bytes of the memory block (in hex) are: 0000000000000000.
      This memory block was (re)allocated at line number 11 in TDRALLC.C.       */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _debug_calloc - Reserve and Initialize Storage
o _debug_free - Release Storage Blocks
o _debug_malloc - Reserve Storage Blocks
o _dump_allocated - Get Information about Allocated Storage
o _heap_check - Validate Run-Time Storage Heap
o realloc  - Change Reserved Storage Block Size
o Using the Debug Memory Management Functions
o malloc.h
o stdlib.h


ΓòÉΓòÉΓòÉ 6.46. difftime  - Compute Time Difference ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <time.h>

double difftime(time_t time2, time_t time1);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The difftime function computes the difference in seconds between time2 and
time1. The difftime function returns the elapsed time in seconds from time1 to
time2 as a double precision number.  Type time_t is defined in <time.h>.

Example of difftime


ΓòÉΓòÉΓòÉ <hidden> Example of difftime ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example shows a timing application using difftime.  The example calculates
how long, on average, it takes to find the prime numbers from 2 to 10000.

                                                                        *
************************************************************************/

#include <time.h>
#include <stdio.h>

#define RUNS 1000
#define SIZE 10000

int mark[SIZE];

int main(void)
{
   time_t start, finish;
   int i, loop, n, num;

   time(&start);

   /*  This loop finds the prime numbers between 2 and SIZE   */
   for (loop = 0; loop < RUNS; ++loop)
      {
      for (n = 0; n < SIZE; ++n)
         mark [n] = 0;
      /*  This loops marks all the composite numbers with -1  */
      for (num = 0, n = 2; n < SIZE; ++n)
         if ( ! mark[n])
         {
            for (i = 2 * n; i < SIZE; i += n)
                mark[i] = -1;
            ++num;
            }
      }
   time(&finish);
   printf("Program takes an average of %f seconds "
                  "to find %d primes.\n",
                   difftime(finish,start)/RUNS, num);
}

/********************  Output should be similar:  *****************

The program takes an average of 0.106000 seconds to find 1229 primes.
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o asctime  - Convert Time
o ctime  - Convert Time
o gmtime  - Convert Time
o localtime  - Convert Time
o mktime  - Convert Local Time
o strftime  - Convert to Formatted Time
o time  - Determine Current Time
o time.h


ΓòÉΓòÉΓòÉ 6.47. _disable - Disable Interrupts ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <builtin.h>

void _disable( void );


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _disable function disables interrupts by executing the CLI machine
instruction. It disables interrupts until the instruction after a call to
_enable has been executed.

Because it is a built-in function and has no backing code in the library:

o You cannot take the address of _disable.
o You cannot parenthesize a _disable function call, because parentheses specify
  a call to the backing code for the function in the library.

You can run code containing this function only at ring zero. Otherwise, an
invalid instruction exception is generated.

This function has no return value.

Example of _disable


ΓòÉΓòÉΓòÉ <hidden> Example of _disable ΓòÉΓòÉΓòÉ

/************************************************************************
*

In this example, the _disable function disables interrupts by executing a CLI
instruction.

                                                                        *
************************************************************************/

#include <builtin.h>

int main(void)
   {
   /* ------------------------------------------------------ */
   /* The expected assembler instruction looks like this :   */
   /*       CLI                                              */
   /* -------------------------------------------------------*/
   _disable();
   return 0;
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _enable - Enable Interrupts
o _interrupt - Call Interrupt  Procedure


ΓòÉΓòÉΓòÉ 6.48. div  - Calculate Quotient and Remainder ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

div_t div(int numerator, int denominator);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The div function calculates the quotient and remainder of the division of
numerator by denominator.

The div function returns a structure of type div_t, containing both the
quotient int quot and the remainder int rem.  If the return value cannot be
represented, its value is undefined. If denominator is 0, an exception will be
raised.

Example of div


ΓòÉΓòÉΓòÉ <hidden> Example of div ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses the div function to calculate the quotients and remainders
for a set of two dividends and two divisors.

                                                                        *
************************************************************************/

#include <stdlib.h>
#include <stdio.h>

int main(void)
{
   int num[2] = {45,-45};
   int den[2] = {7,-7};
   div_t ans;   /* div_t is a struct type containing two ints:
                   'quot' stores quotient; 'rem' stores remainder */
   short i,j;

   printf("Results of division:\n");
   for (i = 0; i < 2; i++)
      for (j = 0; j < 2; j++)
      {
         ans = div(num[i],den[j]);
         printf("Dividend: %6ld  Divisor: %6ld", num[i], den[j]);
         printf("  Quotient: %6ld  Remainder: %6ld\n", ans.quot, ans.rem);
      }
}

/*****************  Output should be similar to:  *****************

Results of division:
Dividend:  45  Divisor:   7  Quotient:   6  Remainder:   3
Dividend:  45  Divisor:  -7  Quotient:  -6  Remainder:   3
Dividend: -45  Divisor:   7  Quotient:  -6  Remainder:  -3
Dividend: -45  Divisor:  -7  Quotient:   6  Remainder:  -3
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o ldiv  - Long Division
o stdlib.h


ΓòÉΓòÉΓòÉ 6.49. _DLL_InitTerm - Initialize and Terminate DLL Environment ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

unsigned long _System _DLL_InitTerm(unsigned long modhandle,
                                            unsigned long flag);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The initialization and termination entry point for a DLL is the _DLL_InitTerm
function. When each new process gains access to the DLL, this function
initializes the necessary environment for the DLL, including storage,
semaphores, and variables. When each process frees its access to the DLL, the
_DLL_InitTerm function terminates the DLL environment created for that process.

The default _DLL_InitTerm function supplied by the C/C++ Tools compiler
performs the actions required to initialize and terminate the runtime
environment. It is called automatically when you link to the DLL. If your DLL
requires initialization or termination actions in addition to the actions
performed for the runtime environment, you will need to create your own
_DLL_InitTerm function.

If the value of the flag parameter is 0, the DLL environment is initialized. If
the value of the flag parameter is 1, the DLL environment is ended.

The modhandle parameter is the module handle assigned by the operating system
for this DLL. The module handle can be used as a parameter to various OS/2 API
calls.  For example, DosQueryModuleName can be used to return the fully
qualified path name of the DLL, which tells you where the DLL was loaded from.

The return code from _DLL_InitTerm tells the loader if the initialization or
termination was performed successfully. If the call was successful,
_DLL_InitTerm returns a nonzero value. A return code of 0 indicates that the
function failed. If a failure is indicated, the loader will not load the
program that is accessing the DLL.

Because it is called by the operating system loader, the _DLL_InitTerm function
must be compiled using _System linkage.

Note:  A _DLL_InitTerm function for a subsystem DLL has the same prototype, but
the content of the function is different because there is no runtime
environment to initialize or terminate.

Example of _DLL_InitTerm

Example of _DLL_InitTerm for a Subsystem


ΓòÉΓòÉΓòÉ <hidden> Example of _DLL_InitTerm ΓòÉΓòÉΓòÉ

/************************************************************************
*

The following example shows the _DLL_InitTerm function from the SAMPLE03
program that is shipped with the C/C++ Tools product.

                                                                        *
************************************************************************/

#define  INCL_DOSMODULEMGR
#define  INCL_DOSPROCESS
#include <os2.h>
#include <stdlib.h>
#include <stdio.h>
#include <string.h>

/* _CRT_init is the C run-time environment initialization function.         */
/* It will return 0 to indicate success and -1 to indicate failure.         */

int _CRT_init(void);
#ifdef   STATIC_LINK

/* _CRT_term is the C run-time environment termination function.            */
/* It only needs to be called when the C run-time functions are statically  */
/* linked.                                                                  */

void _CRT_term(void);
#else

/* A clean up routine registered with DosExitList must be used if runtime   */
/* calls are required and the runtime is dynamically linked.  This will     */
/* guarantee that this clean up routine is run before the library DLL is    */
/* terminated.                                                              */

static void _System cleanup(ULONG ulReason);
#endif
size_t nSize;
int *pArray;

/* _DLL_InitTerm is the function that gets called by the operating system   */
/* loader when it loads and frees this DLL for each process that accesses   */
/* this DLL.  However, it only gets called the first time the DLL is loaded */
/* and the last time it is freed for a particular process.  The system      */
/* linkage convention MUST be used because the operating system loader is   */
/* calling this function.                                                   */

unsigned long _System _DLL_InitTerm(unsigned long hModule, unsigned long
                                    ulFlag)
{
   size_t i;
   APIRET rc;
   char namebuf[CCHMAXPATH];

   /* If ulFlag is zero then the DLL is being loaded so initialization should*/
   /* be performed.  If ulFlag is 1 then the DLL is being freed so          */
   /* termination should be performed.                                      */

   switch (ulFlag) {
      case 0 :

         /*******************************************************************/
         /* The C run-time environment initialization function must be      */
         /* called before any calls to C run-time functions that are not    */
         /* inlined.                                                        */
         /*******************************************************************/

         if (_CRT_init() == -1)
            return 0UL;
#ifndef  STATIC_LINK

         /*******************************************************************/
         /* A DosExitList routine must be used to clean up if runtime calls */
         /* are required and the runtime is dynamically linked.             */
         /*******************************************************************/

            if (rc = DosExitList(0x0000FF00|EXLST_ADD, cleanup))
            printf("DosExitList returned %lu\n", rc);
#endif
         if (rc = DosQueryModuleName(hModule, CCHMAXPATH, namebuf))
            printf("DosQueryModuleName returned %lu\n", rc);
         else
            printf("The name of this DLL is %s\n", namebuf);
         srand(17);
         nSize = (rand()%128)+32;
         printf("The array size for this process is %u\n", nSize);
         if ((pArray = malloc(nSize *sizeof(int))) == NULL) {
            printf("Could not allocate space for unsorted array.\n");
            return 0UL;
         }
         for (i = 0; i < nSize; ++i)
            pArray[i] = rand();
         break;
      case 1 :
#ifdef   STATIC_LINK
         printf("The array will now be freed.\n");
         free(pArray);
         _CRT_term();
#endif
         break;
      default  :
         printf("ulFlag = %lu\n", ulFlag);
         return 0UL;
   }

   /* A non-zero value must be returned to indicate success.                */

   return 1UL;
}
#ifndef  STATIC_LINK
static void cleanup(ULONG ulReason)
{
   if (!ulReason) {
      printf("The array will now be freed.\n");
      free(pArray);
   }
   DosExitList(EXLST_EXIT, cleanup);
   return ;
}
#endif


ΓòÉΓòÉΓòÉ <hidden> Example of _DLL_InitTerm for a Subsystem ΓòÉΓòÉΓòÉ

/************************************************************************
*

The following example shows the _DLL_InitTerm function from the SAMPLE05
program that is shipped with the C/C++ Tools product.

                                                                        *
************************************************************************/

/* _DLL_InitTerm() - called by the loader for DLL
initialization/termination  */
/* This function must return a non-zero value if successful and a zero value  */
/* if unsuccessful.                                                           */

unsigned long _DLL_InitTerm( unsigned long hModule, unsigned long ulFlag )
   {
   APIRET rc;

   /* If ulFlag is zero then initialization is required:                      */
   /*    If the shared memory pointer is NULL then the DLL is being loaded    */
   /*    for the first time so acquire the named shared storage for the       */
   /*    process control structures.  A linked list of process control        */
   /*    structures will be maintained.  Each time a new process loads this   */
   /*    DLL, a new process control structure is created and it is inserted   */
   /*    at the end of the list by calling DLLREGISTER.                       */
   /*                                                                         */
   /* If ulFlag is 1 then termination is required:                            */
   /*    Call DLLDEREGISTER which will remove the process control structure   */
   /*    and free the shared memory block from its virtual address space.     */

   switch( ulFlag )
      {
      case 0:
         if ( !ulProcessCount )
            {
            /* Create the shared mutex semaphore.                             */

            if ( ( rc = DosCreateMutexSem( SHARED_SEMAPHORE_NAME,
                                           &hmtxSharedSem,
                                           0,
                                           FALSE ) ) != NO_ERROR )
               {
               printf( "DosCreateMutexSem rc = %lu\n", rc );
               return 0;
               }
            }

         /* Register the current process.                                     */

         if ( DLLREGISTER( ) )
            return 0;
         break;

      case 1:
         /* De-register the current process.                                  */

         if ( DLLDEREGISTER( ) )
            return 0;
         break;

      default:
         return 0;
      }

   /* Indicate success.  Non-zero means success!!!             */

   return 1;
   }


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _CRT_init - Initialize DLL Runtime Environment
o _CRT_term - Terminate DLL Runtime Environment


ΓòÉΓòÉΓòÉ 6.50. _dump_allocated - Get Information about Allocated Storage ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#define __DEBUG_ALLOC__
#include <stdlib.h>  /* also defined in <malloc.h> */

void _dump_allocated(int nbytes);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _dump_allocated function prints out information about each memory block
that is currently allocated, if it was allocated by the debug versions of the
memory management functions. The nbytes argument specifies how many bytes of
each memory block are to be printed.

If nbytes is a negative value, all the bytes of each memory block are printed.
If nbytes is 0, no bytes are printed.  If nbytes is a positive value, the
number of bytes printed for each block will be the minimum of the requested
size and the block size.

Note:  You should call the _dump_allocated function at a point in your code
where you would like a report of the currently allocated memory. For example, a
good place to call _dump_allocated is a point where most of the memory is
already freed and you want to find a memory leak, such as the end of a program.

Example of _dump_allocated


ΓòÉΓòÉΓòÉ <hidden> Example of _dump_allocated ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example allocates three memory blocks, and then calls _dump_allocated to
dump information and the first 8 bytes for each memory block.

                                                                        *
************************************************************************/

rules=none.

#ifndef __DEBUG_ALLOC__     /* this macro could also be defined */
   #define __DEBUG_ALLOC__  /*      from the command line       */
#endif
#include <stdlib.h>
#include <string.h>
#include <stdio.h>

#define INIT_STR     "It\0works"
#define INIT_STR_LEN (sizeof(INIT_STR) - 1)

int main(void)
{
   char *pBlock1;
   char *pBlock2;
   char *pBlock3;

   if (( pBlock1 = malloc(35) ) == NULL)    /* allocate first memory block */
   {
      printf( "Could not allocate first memory block.\n" );
      return EXIT_FAILURE;
   }

   memcpy(pBlock1, INIT_STR, INIT_STR_LEN);    /* initialize first memory block */

   if (( pBlock2 = calloc(2, 120) ) == NULL)   /* allocate second memory block */
   {
      printf( "Could not allocate second memory block.\n" );
      return EXIT_FAILURE;
   }

   memcpy(pBlock2, INIT_STR, INIT_STR_LEN);    /* initialize second memory block */

   if (( pBlock3 = realloc(NULL, 2235) ) == NULL) /* allocate third memory block */
   {
      printf( "Could not allocate third memory block.\n" );
      return EXIT_FAILURE;
   }

   memcpy(pBlock3, INIT_STR, INIT_STR_LEN);    /* initialize third memory block */

   if (( pBlock3 = realloc(pBlock3, 300) ) == NULL) /* reallocate third memory */
                                                    /* block to different size */
   {
      printf("Could not reallocate third memory block.\n");
      return EXIT_FAILURE;
   }

   _dump_allocated(8);   /* show first eight bytes of each memory block */

   return 0;

   /* Possible output is:

 ============================================================================
                  START OF DUMP OF ALLOCATED MEMORY BLOCKS
 ============================================================================
 Address: 0x00180010      Size: 0x0000012C (300)
 This memory block was (re)allocated at line number 41 in TDMPAL.C.
 Memory contents:  49740077 6F726B73                      {It.works        }
 ============================================================================
 Address: 0x00170010      Size: 0x000000F0 (240)
 This memory block was (re)allocated at line number 25 in TDMPAL.C.
 Memory contents:  49740077 6F726B73                      {It.works        }
 ============================================================================
 Address: 0x00150010      Size: 0x00000023 (35)
 This memory block was (re)allocated at line number 17 in TDMPAL.C.
 Memory contents:  49740077 6F726B73                      {It.works        }
 ============================================================================
                  END OF DUMP OF ALLOCATED MEMORY BLOCKS
 ============================================================================
                                                                       */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _debug_calloc - Reserve and Initialize Storage
o _debug_free - Release Storage Blocks
o _debug_malloc - Reserve Storage Blocks
o _debug_realloc - Change Reserved Storage Block Size
o _heap_check - Validate Run-Time Storage Heap
o Using the Debug Memory Management Functions
o malloc.h
o stdlib.h


ΓòÉΓòÉΓòÉ 6.51. _dup -Associate Second Handle with Open File ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <io.h>

int _dup(int handle);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _dup function associates a second file handle with a currently open file.
You can carry out operations on the file using either file handle because all
handles associated with a given file use the same file pointer. Creation of a
new handle does not affect the type of access allowed for the file.

For example, given:

   handle2 = _dup(handle1)
handle2 will have the same file access mode (text or binary) as handle1. In
addition, if handle1 was originally opened with the O_APPEND flag (described in
_open - Open File), handle2 will also have that attribute.

Warning: Both handles share a single file pointer. Therefore, if you reposition
a file using handle1, the position in the file returned by handle2 will also
change.

If you duplicate a file handle for an open stream, the resulting file handle
has the same restrictions as the original file handle.

The _dup function returns the next available file handle for the given file.
The _dup function returns a new file handle. It returns -1 if an error occurs
and sets errno to one of the following values:

Value          Meaning
EBADF          The file handle is not valid.
EMFILE         No more file handles are available.
EOS2ERR        The call to the operating system was not successful.

Example of _dup


ΓòÉΓòÉΓòÉ <hidden> Example of _dup ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example makes a second file handle, fh3, refer to the same file as the
file handle fh1 using _dup. The file handle fh2 is then associated with the
file edopen.da2, and finally fh2 is forced to associate with edopen.da1 by the
_dup2 function.

                                                                        *
************************************************************************/

#include <io.h>
#include <stdio.h>
#include <fcntl.h>
#include <sys\stat.h>

int main(void)
{
   int fh1, fh2, fh3;

   if ( -1 == (fh1 = _open("edopen.da1", O_CREAT | O_TRUNC | O_RDWR ,
   S_IREAD | S_IWRITE)))
   {
      perror("Unable to open edopen.da1");
      return 1;
   }

   /* fh3 refers to the sample file as fh1 */
   if (-1 == (fh3 = _dup(fh1))) {
      perror("Unable to dup");
      _close(fh1);
      return 1;
   }
   else
      printf("Successfully performed dup handle.\n");

   if ( -1 == (fh2 = _open("edopen.da2", O_CREAT | O_TRUNC | O_RDWR ,
   S_IREAD | S_IWRITE)))
   {
      perror("Unable to open edopen.da2");
      _close(fh1);
      _close(fh3);
      return 1;
   }

   if (-1 == _dup2(fh1,fh2))  /* Force fh2 to the refer to the same file */
   {                         /* as fh1.                                 */
      perror("Unable to dup2");
   }
   else
      printf("Successfully performed dup2 handle.\n");

   _close(fh1);
   _close(fh2);
   _close(fh3);

   return 0;

/******************  The expected output is:  ***************************

      Successfully performed dup handle.
      Successfully performed dup2 handle.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _close - Closes File Associated with Handle
o _creat - Create New File
o _dup2 -Associate Second Handle with Open File
o _open - Open File
o _sopen - Open Shared File
o io.h


ΓòÉΓòÉΓòÉ 6.52. _dup2 -Associate Second Handle with Open File ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <io.h>

int _dup2(int handle1, int handle2);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _dup2 function associates a second file handle with a currently open file.
You can carry out operations on the file using either file handle because all
handles associated with a given file use the same file pointer.

The handle handle2 will point to the same file as handle1, but will retain the
file access mode (text or binary) that it had before duplication.  In addition,
if handle2 was originally opened with the O_APPEND flag, it will also retain
that attribute.

Warning: Both handles share a single file position. Therefore, if you
reposition a file using handle1, the position in the file returned by handle2
will also change.

If you duplicate a file handle for an open stream (using fileno), the resulting
file handle has the same restrictions as the original file handle.

The _dup2 function forces the given handle, handle2, to refer to the same file
as handle1. If handle2 is associated with an open file at the time of the call,
that file is closed. The _dup2 function returns 0 to indicate success. It
returns -1 if an error occurs and sets errno to one of the following values:

Value          Meaning
EBADF          The file handle is not valid.
EMFILE         No more file handles are available.
EOS2ERR        The call to the operating system was not successful.

Example of _dup2


ΓòÉΓòÉΓòÉ <hidden> Example of _dup2 ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example makes a second file handle, fh3, refer to the same file as the
file handle fh1 using _dup. The file handle fh2 is then associated with the
file edopen.da2, and finally fh2 is forced to associate with edopen.da1 by the
_dup2 function.

                                                                        *
************************************************************************/

#include <io.h>
#include <stdio.h>
#include <fcntl.h>
#include <sys\stat.h>

int main(void)
{
   int fh1, fh2, fh3;

   if ( -1 == (fh1 = _open("edopen.da1", O_CREAT | O_TRUNC | O_RDWR ,
   S_IREAD | S_IWRITE)))
   {
      perror("Unable to open edopen.da1");
      return 1;
   }

   /* fh3 refers to the sample file as fh1 */
   if (-1 == (fh3 = _dup(fh1))) {
      perror("Unable to dup");
      _close(fh1);
      return 1;
   }
   else
      printf("Successfully performed dup handle.\n");

   if ( -1 == (fh2 = _open("edopen.da2", O_CREAT | O_TRUNC | O_RDWR ,
   S_IREAD | S_IWRITE)))
   {
      perror("Unable to open edopen.da2");
      _close(fh1);
      _close(fh3);
      return 1;
   }

   if (-1 == _dup2(fh1,fh2))  /* Force fh2 to the refer to the same file */
   {                         /* as fh1.                                 */
      perror("Unable to dup2");
   }
   else
      printf("Successfully performed dup2 handle.\n");

   _close(fh1);
   _close(fh2);
   _close(fh3);

   return 0;

/******************  The expected output is:  ***************************

      Successfully performed dup handle.
      Successfully performed dup2 handle.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _close - Closes File Associated with Handle
o _creat - Create New File
o _dup -Associate Second Handle with Open File
o _open - Open File
o _sopen - Open Shared File
o io.h


ΓòÉΓòÉΓòÉ 6.53. _ecvt - Convert Floating-Point to Character ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

char *_ecvt(double value, int ndigits, int *decptr, int *signptr);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _ecvt function converts a floating-point number to a character string. The
variable value is the floating-point number to be converted. The _ecvt function
stores ndigits digits of value as a string and adds a null character (\0). If
the number of digits in value exceeds ndigits, the low-order digit is rounded.
If there are fewer than ndigits digits, the string is padded with zeros.

Only digits are stored in the string. You can obtain the position of the
decimal point and the sign of value after the call from decptr and signptr. The
variable decptr points to an integer value that gives the position of the
decimal point with respect to the beginning of the string. A 0 or a negative
integer value indicates that the decimal point lies to the left of the first
digit. The variable signptr points to an integer that indicates the sign of the
converted number. If the integer value is 0, the number is positive. If it is
not 0, the number is negative.

The _ecvt function also converts NaN and infinity values to the strings NAN and
INFINITY, respectively. For more information on NaN and infinity values, see
Infinity and NaN Support.

Warning: For each thread, the _ecvt, _fcvt and _gcvt functions use a single,
dynamically allocated buffer for the conversion. Any subsequent call that the
same thread makes to these functions destroys the result of the previous call.

The _ecvt function returns a pointer to the string of digits. A failure to
allocate memory results in a NULL return value, and errno is set to ENOMEM.
Because of the limited precision of the double type, no more than 16 decimal
digits are significant in any conversion.

Example of _ecvt


ΓòÉΓòÉΓòÉ <hidden> Example of _ecvt ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example reads in two floating-point numbers, calculates their product, and
prints out only the billions digit of its character representation. At most, 16
decimal digits of significance can be expected. The output assumes the user
enters the numbers 1000000 and 3000.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>
#include <math.h>

int main(void)
{
    float x, y;
    double z;
    int w, b, decimal, sign;
    char *buffer;

    printf("Enter two floating-point numbers:\n");
    if ( scanf("%e %e", &x, 0x) != 2 )
    {
        printf("input error...\n");
        exit(-1);
    }

    z = x*y;
    printf("Their product is %g\n", z);

    w = log10( fabs(z) ) + 1.;
    buffer = _ecvt(z, w, &decimal, signed);

    b = decimal - 10;
    if (b < 0)
        printf("Their product does not exceed one billion.\n");
    else if (b > 15)
        printf("The billions digit of their product is insignificant.\n");
    else
        printf("The billions digit of their product is %c.\n", buffer[b]);

    return 0;

/*****  The expected output on input of 1000000 3000 is  **************

         Enter two floating point numbers:
         1000000 3000
         Their product is 3e+09
         the billions digit of their product is 3.

*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _fcvt - Convert Floating-Point to String
o _gcvt - Convert Floating-Point to String
o Infinity and NaN Support
o stdlib.h


ΓòÉΓòÉΓòÉ 6.54. _enable - Enable Interrupts ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <builtin.h>  /* also defined in <stdlib.h> */

void _enable( void );


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _enable function enables interrupts by generating the STI machine
instruction.  Interrupts are enabled after the instruction following STI has
been executed. If interrupts are disabled and you call _enable followed
immediately by a call to _disable, interrupts remain disabled.

Because it is a built-in function and has no backing code in the library:

o You cannot take the address of _enable.
o You cannot parenthesize an _enable function call because parentheses specify
  a call to the backing code for the function in the library.

You can run code containing this function only at ring zero. Otherwise, an
invalid instruction exception will be generated.

There is no return value.

Example of _enable


ΓòÉΓòÉΓòÉ <hidden> Example of _enable ΓòÉΓòÉΓòÉ

/************************************************************************
*

In this example, the _enable function enables interrupts by executing an STI
instruction.

                                                                        *
************************************************************************/

#include <builtin.h>

int main(void)
   {
   /* ------------------------------------------------------ */
   /* The expected assembler instruction looks like this :   */
   /*       STI                                              */
   /* ------------------------------------------------------ */
   _enable();
   return 0;
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _disable - Disable Interrupts
o _interrupt - Call Interrupt  Procedure


ΓòÉΓòÉΓòÉ 6.55. _endthread - Terminate Current Thread ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>    /* also defined in <process.h> */

void _endthread(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _endthread function explicitly ends a thread that you previously created
with _beginthread before the thread has completed its function. For example, if
some condition is not met, _endthread terminates the thread. When the thread
has finished, it automatically ends itself with an implicit call to _endthread.

Note:

 1. When using the _beginthread and _endthread functions, you must specify the
    /Gm+ compiler option to use the multithread libraries.

 2. If you use DosCreateThread, you must explicitly call _endthread to
    terminate the thread.

There is no return value.

Example of _endthread


ΓòÉΓòÉΓòÉ <hidden> Example of _endthread ΓòÉΓòÉΓòÉ

/************************************************************************
*
In this example, the main program creates two threads, bonjour and au_revoir.
The thread bonjour is forcibly terminated by a call to _endthread, while the
au_revoir thread ends itself with an implicit call to _endthread.

Note:  To run this example, you must compile it using the /Gm+ compile-time
option.

                                                                        *
************************************************************************/

#define INCL_DOS
#include <os2.h>
#include <stdio.h>
#include <stdlib.h>
#include <process.h>

void bonjour(void *arg)
{
   int i = 0;
   while ( i++ < 5 )
      printf("Bonjour!\n");

   _endthread();              /* This thread ends itself explicitly */
   puts("thread should terminate before printing this");
}

void au_revoir(void *arg)
{
   int i = 0;
   while ( i++ < 5 )           /* This thread makes an implicit */
      printf("Au revoir!\n");  /* call to _endthread            */
}

int main(void)
{
   unsigned long tid1;
   unsigned long tid2;

   tid1 = _beginthread(bonjour, NULL, 8192, NULL);
   tid2 = _beginthread(au_revoir, NULL, 8192, NULL);

   if ( (tid1 == -1) || (tid2 == -1) )
   {
      printf("Unable to start threads.\n");
      exit(-1);
   }

   DosWaitThread( &tid2, DCWW_WAIT );   /*  wait until threads 1 and 2  */
   DosWaitThread( &tid1, DCWW_WAIT );   /*  have been completed         */

   return 0;

   /* Possible output could be:

      Bonjour!
      Au revoir!
      Bonjour!
      Au revoir!
      Bonjour!
      Au revoir!
      Bonjour!
      Au revoir!
      Bonjour!
      Au revoir!           */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _beginthread - Create New Thread
o /Gm+ option.
o stdlib.h
o process.h


ΓòÉΓòÉΓòÉ 6.56. __eof - Determine End of File ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <io.h>

int __eof (int handle);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The __eof function determines whether the file pointer has reached the
end-of-file for the file associated with handle. You cannot use __eof on a
nonseekable file; it will fail.

The __eof function returns the value 1 if the current position is the end of
the file or 0 if it is not. A return value of -1 shows an error, and the system
sets errno to the following values:

Value          Meaning
EBADF          File handle is not valid.
EOS2ERR        The call to the operating system was not successful.

Example of __eof


ΓòÉΓòÉΓòÉ <hidden> Example of __eof ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example creates the file sample.dat and then checks if the file pointer is
at the end of that file using the __eof function:

                                                                        *
************************************************************************/

#include <sys\stat.h>
#include <io.h>
#include <stdio.h>

int main(void)
{
   int fh, returnValue;

   fh = _creat("sample.dat", S_IREAD | S_IWRITE);

   if ( -1 == fh)
   {
      perror("Error creating sample.dat");
      return 1;
   }

   if ( -1 == (returnValue = __eof(fh)))
   {
      perror("eof function error");
      return 1;
   }
   if (returnValue == 1)
      printf("File pointer is at end-of-file position.\n");
   else
      printf("File pointer is not at end-of-file position.\n");
   _close(fh);
   return 0;

/****************  The expected output is:  *****************************

      File pointer is at end-of-file position.
*/

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _chsize - Alter Length of File
o _creat - Create New File
o _filelength - Determine File Length
o _sopen - Open Shared File
o _open - Open File
o io.h


ΓòÉΓòÉΓòÉ 6.57. erf  - Calculate Error Functions ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h> /* SAA extensions to ANSI */

double erf(double x);

double erfc(double x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: SAA

The erf function calculates the error function. The erfc function returns the
value of 1.0 - erf(x);.  The erfc function is used in place of erf for large
values of x.

Example of erf - erfc


ΓòÉΓòÉΓòÉ <hidden> Example of erf - erfc ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses erf to compute the error function of two numbers.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <math.h>

double smallx, largex, value;

int main(void)
{
   smallx = 0.1;
   largex = 10.0;

   value = erf(smallx);         /* value = 0.112463 */
   printf("Error value for 0.1: %lf\n", value);

   value = erfc(largex);        /* value = 2.088488e-45 */
   printf("Error value for 10.0: %le\n", value);
}

/*****************  Output should be similar to:  *****************

Error value for 0.1: 0.112463
Error value for 10.0: 2.088488e-45
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Bessel Functions
o math.h
o gamma  - Gamma Function


ΓòÉΓòÉΓòÉ 6.58. _execl - _execvp - Load and Run Child Process ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <process.h>

int _execl(char *pathname, char *arg0, char *arg1,..., char *argn, NULL);

int _execle(char *pathname, char *arg0, char *arg1,..., char *argn,
                                                  NULL, char *envp[ ]);

int _execlp(char *pathname, char *arg0, char *arg1,..., char *argn, NULL);

int _execlpe(char *pathname, char *arg0, char *arg1,..., char *argn,
                                                  NULL, char *envp[ ]);

int _execv(char *pathname, char *argv[ ]);

int _execve(char *pathname, char *argv[ ],char *envp[ ]);

int _execvp(char *pathname, char *argv[ ]);

int _execvpe(char *pathname, char *argv[ ], char *envp[ ]);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _exec functions load and run new child processes. The parent process is
ended after the child process has started.  Sufficient storage must be
available for loading and running the child process.

All of the _exec functions are versions of the same routine;  the letters at
the end determine the specific variation:

Letter    Variation
 p        Uses PATH environment variable to find the file to be run
 l        Passes a list of command line arguments separately
 v        Passes to the child process an array of pointers to command-line
          arguments
 e        Passes to the child process an array of pointers to environment
          strings.

The pathname argument specifies the file to run as the child process.  The
pathname can specify a full path from the root, a partial path from the current
working directory, or a file name.  If pathname does not have a file name
extension or does not end with a period, the _exec functions will add the .EXE
extension and search for the file.  If pathname has an extension, the _exec
function uses only that extension. If pathname ends with a period, the _exec
functions search for pathname with no extension.  The _execlp, _execlpe,
_execvp, and _execvpe functions search for the pathname in the directories that
the PATH environment variable specifies.

You pass arguments to the new process by giving one or more pointers to
character strings as arguments in the _exec call.  These character strings form
the argument list for the child process.

The compiler can pass the argument pointers as separate arguments (_execl,
_execle, _execlp, and _execlpe) or as an array of pointers (_execv, _execve,
_execvp, and _execvpe).  You should pass at least one argument, either arg0 or
argv[0], to the child process. If you do not, an argument will be returned that
points to the same file as the path name argument you specified. This argument
may not be exactly identical to the path name argument you specified.  A
different value does not produce an error.

Use the _execl, _execle, _execlp, and _execlpe functions for the cases where
you know the number of arguments in advance. The arg0 argument is usually a
pointer to pathname. The arg1 through argn arguments are pointers to the
character strings forming the new argument list. There must be a NULL pointer
following argn to mark the end of the argument list.

Use the _execv, _execve, _execvp, and _execvpe functions when the number of
arguments to the new process is variable.  Pass pointers to the arguments of
these functions as an array, argv[ ]. The argv[0] argument is usually a pointer
to pathname. The argv[1] through argv[n] arguments are pointers to the
character strings forming the new argument list.  If argv[n] is the last
parameter, then argv[n+1] must be NULL.

Files that are open when you make an _exec call remain open in the new process.
In the _execl, _execlp, _execv, and _execvp calls, the child process receives
the environment of the parent.  The _execle, _execlpe, _execve, and _execvpe
functions let you change the environment for the child process by passing a
list of environment settings through the envp argument.  The envp argument is
an array of character pointers, each element of which points to a string ending
with a null character that defines an environment variable.  Such a string
usually has the following form:

   NAME=value

where NAME is the name of an environment variable, and value is the string
value to which the _exec function sets that variable.

Note:  Do not enclose the value in double quotation marks.

The final element of the envp array should be NULL. When envp itself is NULL,
the child process receives the environment settings of the parent process.

The _exec functions do not preserve signal settings in child processes created
by calls to _exec functions.  Calls to _exec functions reset the signal
settings to the default in the child process.

The _exec functions do not normally return control to the calling process.
They are equivalent to the corresponding _spawn functions with P_OVERLAY as the
value of modeflag.  If an error occurs, the _exec functions return -1 and set
errno to one of the following values:

Value          Meaning
EACCESS        The specified file has a locking or sharing violation.
EMFILE         There are too many open files.  The system must open the
               specified file to tell whether it is an executable file.
ENOENT         The file or pathname was not found or was specified incorrectly.
ENOEXEC        The specified file cannot run or has an incorrect executable
               file format.
ENOMEM         One of the following conditions exists:

   o Not enough storage is available to run the child process.
   o Not enough storage is available for the argument or environment strings.

Example of _execl - execvp


ΓòÉΓòÉΓòÉ <hidden> Example of _execl - execvp ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example calls four of the eight _exec routines.  When invoked without
arguments, the program first runs the code for case PARENT.  It then calls
_execle() to load and run a copy of itself.  The instructions for the child are
blocked to run only if argv[0] and one parameter were passed (case CHILD).  In
its turn, the child runs its own child as a copy of the same program.  This
sequence is continued until four generations of child processes have run.  Each
of the processes prints a message identifying itself.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>
#include <process.h>
#define  PARENT       1
#define  CHILD        2

char *args[3];

int main(int argc, char **argv, char **envp)
{
    switch(argc)
    {
        case PARENT:      /* No argument: run a child */
        {
            printf("Parent process began.\n");
            _execle(argv[0],argv[0],"1",NULL,envp);
            abort();  /* Not executed because parent was overlaid. */
        }
        case CHILD:       /* One argument: run a child's child */
        {
            printf("Child process %s began.\n", argv[1]);
            if('1'==*argv[1])     /* generation one */
            {
                _execl(argv[0],argv[0],"2",NULL);
                abort();  /* Not executed because child was overlaid */
            }
            if('2'==*argv[1])     /* generation two */
            {
                args[0]=argv[0];
                args[1]="3";
                args[2]=NULL;
                _execv(argv[0],args);
                abort();  /* Not executed because child was overlaid */
            }
            if('3'==*argv[1])     /* generation three */
            {
                args[0]=argv[0];
                args[1]="4";
                args[2]=NULL;
                _execve(argv[0],args,_environ);
                abort();    /* Not executed because child was overlaid */
            }

            if('4'==*argv[1]) /* generation four */
                printf("Child process %s", argv[1]);
        }
    }
    printf(" ended.\n");
    _exit(0);


    return 0;


/***************** The output should be similar to:  ********************

   Parent process began.
   Child process 1 began.
   Child process 2 began.
   Child process 3 began.
   Child process 4 began.
   Child process 4 ended.
*/

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o abort  - Stop a Program
o _cwait - Wait for Child Process
o exit  - End Program
o _exit - End Process
o _spawnl -_spawnvpe -Start and Run Child Processes
o system - Invoke the Command Processor
o _wait - Wait for Child Process
o envp Parameter to main
o process.h


ΓòÉΓòÉΓòÉ 6.59. exit  - End Program ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>  /* also defined in <process.h> */

void exit(int status);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA, Extension

The exit function returns control to the host environment from the program. It
first calls all functions registered with the atexit function, in reverse
order;  that is, the last one registered is the first one called. It flushes
all buffers and closes all open files before ending the program.

The argument status can have a value from 0 to 255 inclusive or be one of the
macros EXIT_SUCCESS or EXIT_FAILURE. A status value of EXIT_SUCCESS or 0
indicates a normal exit; otherwise, another status value is returned.

All files opened with tmpfile are deleted. The exit function returns both
control and the value of status to the operating system.

Example of exit


ΓòÉΓòÉΓòÉ <hidden> Example of exit ΓòÉΓòÉΓòÉ

/***********************************************************************
*

This example ends the program after flushing buffers and closing any open files
if it cannot open the file myfile.

                                                                       *
***********************************************************************/

#include <stdio.h>
#include <stdlib.h>

FILE *stream;

int main(void)
{
   .
   .
   .
   if ((stream = fopen("myfile.dat", "r")) == NULL)
   {
      perror("Could not open data file");
      exit(EXIT_FAILURE);
   }
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o abort  - Stop a Program
o atexit  - Record Program Termination Function
o _onexit - Record Termination Function
o _exit - End Process
o signal Install Interrupt Handlers
o stdlib.h
o tmpfile  - Create Temporary File


ΓòÉΓòÉΓòÉ 6.60. _exit - End Process ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>      /* Declared in both   */
#include <process.h>

void _exit(int status);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _exit function ends the calling process without calling functions
registered by _onexit or atexit. It also does not flush stream buffers or
delete temporary files. You supply the status value as a parameter; the value 0
typically means a normal exit.

Although _exit does not return a value, the value is available to the waiting
parent process, if there is one, after the child process ends.  If no parent
process waits for the exiting process, the status value is lost.  The status
value is available through the operating system batch command IF ERRORLEVEL.

Example of _exit


ΓòÉΓòÉΓòÉ <hidden> Example of _exit ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example calls _exit to end the process. Because _exit does not flush the
buffer first, the output from the second printf statement will not appear.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>   /* You can also use <process.h> */

char buf[51];

int main(void)
{
   /* Make sure the standard output stream is line-buffered */
   /* even if the output is redirected to a file.           */

   if (setvbuf( stdout, buf, _IOLBF, 50 ) != 0)
      printf("The buffering was not set correctly.\n");

   printf( "This will print out but ...\n" );

   printf( "this will not!" );

   _exit( 1 );

    return 0;


/******************  The output should be similar to:  ******************

   This will print out but ...
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o abort  - Stop a Program
o atexit  - Record Program Termination Function
o _execl - _execvp - Load and Run Child Process
o exit  - End Program
o _onexit - Record Termination Function
o process.h
o stdlib.h


ΓòÉΓòÉΓòÉ 6.61. exp  - Exponential Function ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h>

double exp(double x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The exp function calculates the exponential function of a floating-point
argument x (e**x, where e equals 2.17128128...).

If an overflow occurs, the function returns HUGE_VAL. If an underflow occurs,
it returns 0. Both overflow and underflow set errno to ERANGE.

Example of exp


ΓòÉΓòÉΓòÉ <hidden> Example of exp ΓòÉΓòÉΓòÉ

/***********************************************************************
*

This example calculates y as the exponential function of x:

                                                                       *
***********************************************************************/

#include <math.h>
#include <stdio.h>

int main(void)
{
   double x, y;

   x = 5.0;
   y = exp(x);

   printf("exp( %lf ) = %lf\n", x, y);
}

/*****************  Output should be similar to:  *****************

exp( 5.000000 ) = 148.413159
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o log  - Calculate Natural Logarithm
o log10  - Calculate Base 10 Logarithm
o math.h


ΓòÉΓòÉΓòÉ 6.62. fabs  - Calculate Floating-Point Absolute Value ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h>

double fabs(double x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The fabs function returns the absolute value of a floating-point argument.

There is no error return value.

Example of fabs


ΓòÉΓòÉΓòÉ <hidden> Example of fabs ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example calculates y as the absolute value of x:

                                                                        *
************************************************************************/

#include <math.h>
#include <stdio.h>

int main(void)
{
   double x, y;

   x = -5.6798;
   y = fabs(x);

   printf("fabs( %lf ) = %lf\n", x, y);
}

/*******************  Output should be similar to:  ***************

fabs( -5.679800 ) = 5.679800
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o abs  - Calculate Integer Absolute Value
o _cabs - Calculate Absolute Value of Complex Number
o labs  - Calculate long Absolute Value
o math.h


ΓòÉΓòÉΓòÉ 6.63. _facos - Calculate Arccosine ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <builtin.h>

double _facos(double x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _facos function calculates the arccosine of x. This function causes the
compiler to emit the appropriate 80387 instructions for the calculation of the
arccosine.

Because it is a built-in function and has no backing code in the library:

o You cannot take the address of _facos.
o You cannot parenthesize a _facos function call, because parentheses specify a
  call to the backing code for the function.

This function returns the arccosine of a variable x.

Example of _facos


ΓòÉΓòÉΓòÉ <hidden> Example of _facos ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example prompts for a value for x. It prints an error message if x is
greater than 1 or less than -1. Otherwise, it assigns the arccosine of x to y.

                                                                        *
************************************************************************/

#include <builtin.h>
#include <stdio.h>
#include <stdlib.h>
#include <math.h>
#define MAX  1.0
#define MIN -1.0

int main(void)
  {
  double x, y;

  printf( "Enter x\n" );
  scanf( "%lf", &x );

  /* Output error if not in range */
  if ( x > MAX )
    printf( "Error: %lf too large for acos\n", x );
  else if ( x < MIN )
    printf( "Error: %lf too small for acos\n", x );
  else
    {
    y = _facos( x );
    printf( "The cossine of %lf is %lf.\n", x, y );
    }
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o acos  - Calculate Arccosine
o cos  - Calculate Cosine
o cosh  - Calculate Hyperbolic Cosine
o _fcos - Calculate Cosine
o _fcossin - Calculate Cosine and Sine
o _fsincos - Calculate Sine and Cosine


ΓòÉΓòÉΓòÉ 6.64. _fasin - Calculate Arcsine ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <builtin.h>

double _fasin(double x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _fasin function calculates the arcsine of x. This function causes the
compiler to emit the appropriate 80387 instructions for the calculation of
arcsine.

Because it is a built-in function and has no backing code in the library:

o You cannot take the address of _fasin.
o You cannot parenthesize a _fasin function call, because parentheses specify a
  call to the backing code for the function.

This function returns the arcsine of a variable x.

Example of _fasin


ΓòÉΓòÉΓòÉ <hidden> Example of _fasin ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example prompts for a value of x. It prints an error message if x is
greater than 1 or less than -1. Otherwise, it assigns the arcsine of x to y.

                                                                        *
************************************************************************/

#include <builtin.h>
#include <stdio.h>
#include <stdlib.h>
#include <math.h>
#define MAX  1.0
#define MIN -1.0

int main(void)
  {
  double x, y;

  printf( "Enter x\n" );
  scanf( "%lf", &x );

  /* Output error if not in range */
  if ( x > MAX )
    printf( "Error: %lf too large for _fasin\n", x );
  else if ( x < MIN )
    printf( "Error: %lf too small for _fasin\n", x );
  else
    {
    y = _fasin( x );
    printf( "The arcsine of %lf is %lf.\n", x, y );
    }
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o asin  - Calculate Arcsine
o _fcossin - Calculate Cosine and Sine
o _fsin - Calculate Sine
o _fsincos - Calculate Sine and Cosine
o sin  - Calculate Sine
o sinh  - Calculate Hyperbolic Sine


ΓòÉΓòÉΓòÉ 6.65. fclose  - Close Stream ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int fclose(FILE *stream);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The fclose function closes a stream pointed to by stream.  This function
flushes all buffers associated with the stream before closing it.  When it
closes the stream, the function releases any buffers that the system reserved.

The fclose function returns 0 if it successfully closes the stream, or EOF if
any errors were detected.

Note:  Once a stream has been closed with fclose, it must be opened again
before it can be used.

Example of fclose


ΓòÉΓòÉΓòÉ <hidden> Example of fclose ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example opens a file myfile for reading as a stream; then it closes this
file.

                                                                        *
************************************************************************/

#include <stdio.h>

int main(void)
{
  FILE *stream;

  stream = fopen("myfile.dat", "r");

  if (fclose(stream))   /* Close the stream. */
      perror("fclose error");
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _close - Closes File Associated with Handle
o _fcloseall - Close All Open Streams
o fflush  - Write Buffer to File
o fopen  - Open Files
o freopen  - Redirect Open Files
o stdio.h


ΓòÉΓòÉΓòÉ 6.66. _fcloseall - Close All Open Streams ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int _fcloseall(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _fcloseall function closes all open streams, except stdin, stdout, and
stderr. It also closes and deletes any temporary files created by tmpfile.

The function flushes all buffers associated with the streams before closing
them. When it closes streams, it releases the buffers that the system reserved,
but does not release user-allocated buffers.

The _fcloseall function returns the total number of streams closed, or EOF if
an error occurs.

Example of _fcloseall


ΓòÉΓòÉΓòÉ <hidden> Example of _fcloseall ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example opens a file john for reading as a data stream, and then closes
the file. It closes all other streams except stdin, stdout, and stderr.

                                                                        *
************************************************************************/

#include <stdio.h>

int main(void)
{
    FILE *stream;
    int numclosed;

    stream = fopen("john", "w");

    numclosed = _fcloseall();
    printf("Number of files closed = %d\n", numclosed);

    return 0;

    /* The expected output is:

       Number of files closed = 1    */
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _close - Closes File Associated with Handle
o fclose  - Close Stream
o fflush  - Write Buffer to File
o fopen  - Open Files
o freopen  - Redirect Open Files
o tmpfile  - Create Temporary File
o stdio.h


ΓòÉΓòÉΓòÉ 6.67. _fcos - Calculate Cosine ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <builtin.h>

double _fcos( double x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _fcos function calculates the cosine of x, where x is expressed in radians.
The value of x must be less than 2**63. This function causes the compiler to
emit the FSINCOS 80387 instruction and return only the cosine.

Because it is a built-in function and has no backing code in the library:

o You cannot take the address of _fcos.
o You cannot parenthesize a _fcos function call, because parentheses specify a
  call to the backing code for the function in the library.

This function returns the cosine of a variable x expressed in radians.

Example of _fcos


ΓòÉΓòÉΓòÉ <hidden> Example of _fcos ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example calculates y to be the cosine of x.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <builtin.h>
#include <math.h>

int main(void)
   {
   double x, y;

   x = 7.2;
   y = _fcos(x);

   printf("The cosine of %lf is %lf.\n", x, y);
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o cos  - Calculate Cosine
o cosh  - Calculate Hyperbolic Cosine
o _facos - Calculate Arccosine
o _fcossin - Calculate Cosine and Sine
o _fsincos - Calculate Sine and Cosine


ΓòÉΓòÉΓòÉ 6.68. _fcossin - Calculate Cosine and Sine ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <builtin.h>

double _fcossin(double x, double *y);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _fcossin function calculates the cosine of x, and stores the sine of x in
*y. This is faster than separately calculating the sine and cosine. Use this
function instead of _fsincos when you will be using the cosine first, and then
the sine. This function causes the compiler to emit the FSINCOS 80387
instruction.

Because it is a built-in function and has no backing code in the library:

o You cannot take the address of _fcossin.
o You cannot parenthesize a _fcossin function call, because parentheses specify
  a call to the backing code for the function in the library.

This function returns the cosine of a variable x.

Example of _fcossin


ΓòÉΓòÉΓòÉ <hidden> Example of _fcossin ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example calculates the cosine of x and stores the sine of x in y.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>
#include <builtin.h>
#define MAX  1.0
#define MIN -1.0

int main(void)
  {
  double x,y;

  printf( "Enter x\n" );
  scanf( "%lf", &x );

  /* Output error if not in range */
  if ( x > MAX )
    printf( "Error: %lf too large for _facos\n", x );
  else if ( x < MIN )
    printf( "Error: %lf too small for _facos\n", x );
  else
    {
    z = _fcossin( x, *y);
    printf("The cosine of %d is %lf\n", x, z);
    printf("The sine of %d is %lf\n", x, *y);
    }
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o acos  - Calculate Arccosine
o asin  - Calculate Arcsine
o cos  - Calculate Cosine
o cosh  - Calculate Hyperbolic Cosine
o _facos - Calculate Arccosine
o _fasin - Calculate Arcsine
o _fcos - Calculate Cosine
o sin  - Calculate Sine
o sinh  - Calculate Hyperbolic Sine
o _fsin - Calculate Sine
o _fsincos - Calculate Sine and Cosine


ΓòÉΓòÉΓòÉ 6.69. _fcvt - Convert Floating-Point to String ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

char *_fcvt(double value, int ndec, int *decptr, int *signptr);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _fcvt function converts a floating-point number to a character string. The
variable value is the floating-point number to be converted. The _fcvt function
stores the digits of value as a string and adds a null character (\0). The ndec
variable specifies the number of digits to be stored after the decimal point.

If the number of digits after the decimal point in value exceeds ndec, _fcvt
rounds the correct digit according to the FORTRAN F format.  If there are fewer
than ndec digits of precision, _fcvt pads the string with zeros.

A FORTRAN F number has the following format:

       ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ    ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
 ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇdigitΓöÇΓö┤ΓöÇΓöÇΓöÇ.ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
   Γö£ΓöÇΓöÇ+ΓöÇΓöÇΓöñ          ΓööΓöÇdigitΓöÇΓöÿ
   ΓööΓöÇΓöÇ-ΓöÇΓöÇΓöÿ

The _fcvt function stores only digits in the string. You can obtain the
position of the decimal point and the sign of value after the call from decptr
and signptr. The decptr variable points to an integer value giving the position
of the decimal point with respect to the beginning of the string.  A 0 or
negative integer value shows that the decimal point lies to the left of the
first digit. The signptr variable points to an integer showing the sign of
value. The _fcvt function sets the integer to 0 if value is positive and to a
nonzero number if value is negative.

The _fcvt function also converts NaN and infinity values to the strings NAN and
INFINITY, respectively. For more information on NaN and infinity values, see
Infinity and NaN Support.

Warning: For each thread, the _ecvt, _fcvt, and _gcvt functions use a single,
dynamically allocated buffer for the conversion. Any subsequent call that the
same thread makes to these functions destroys the result of the previous call.

The _fcvt function returns a pointer to the string of digits. A failure to
allocate memory results in a NULL return value and sets errno to ENOMEM.
Because of the limited precision of the double type, no more than 16 decimal
digits are significant in any conversion.

Example of _fcvt


ΓòÉΓòÉΓòÉ <hidden> Example of _fcvt ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example reads in two floating-point numbers, computes their product, and
prints out only the billions digit of its character representation.  At most,
16 decimal digits of significance can be expected. The output given assumes the
user enters the values 2000000 and 3000.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>
#include <math.h>

int main(void)
{
    float x, y;
    double z
    int w, b, decimal, sign;
    char *buffer;

    printf("Enter two floating-point numbers:\n");
    if ( scanf("%e %e", &x, 0x) != 2 )
    {
        printf("input error...\n");
        exit(-1);
    }

    z = x*y;
    printf("Their product is %g\n", z);

    w = log10( fabs(z) ) + 1.;
    buffer = _fcvt(z, w, &decimal, signed);

    b = decimal - 10;
    if (b < 0)
        printf("Their product does not exceed one billion.\n");
    else if (b > 15)
        printf("The billions digit of their product is insignificant.\");
    else
        printf("The billions digit of their product is %c.\n", buffer[b]);

    return 0;

/*****  The expected output on input of 2000000 3000 is  **************

         Enter two floating point numbers:
         2000000 3000
         Their product is 6e+09
         the billions digit of their product is 6.

*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _ecvt - Convert Floating-Point to Character
o _gcvt - Convert Floating-Point to String
o Infinity and NaN Support
o stdlib.h


ΓòÉΓòÉΓòÉ 6.70. _fdopen - Associates Input Or Output With File ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

FILE *_fdopen(int handle, char *type);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _fdopen function associates an input or output stream with the file
identified by handle. The type variable is a character string specifying the
type of access requested for the stream.

Mode Description
r
     Create a stream to read a text file. The file pointer is set to the
     beginning of the file.
w
     Create a stream to write to a text file. The file pointer is set to the
     beginning of the file.
a
     Create a stream to write, in append mode, at the end of the text file. The
     file pointer is set to the end of the file.
r+
     Create a stream for reading and writing a text file. The file pointer is
     set to the beginning of the file.
w+
     Create a stream for reading and writing a text file. The file pointer is
     set to the beginning of the file.
a+
     Create a stream for reading or writing, in append mode, at the end of the
     text file. The file pointer is set to the end of the file.
rb
     Create a stream to read a binary file. The file pointer is set to the
     beginning of the file.
wb
     Create a stream to write to a binary file. The file pointer is set to the
     beginning of the file.
ab
     Create a stream to write to a binary file in append mode. The file pointer
     is set to the end of the file.
r+b or rb+
     Create a stream for reading and writing a binary file. The file pointer is
     set to the beginning of the file.
w+b or wb+
     As in previous mode.
a+b or ab+
     Create a stream for reading and writing to a binary file in append mode.
     The file pointer is set to the end of the file.

Warning: Use the w, w+, wb, wb+, and w+b modes with care; they can destroy
existing files.

The specified type must be compatible with the access mode you used to open the
file.

If the file was opened with the O_APPEND FLAG, the stream mode must be r, a,
a+, rb, ab, a+b, or ab+.

When you open a file with a, a+, ab, a+b, or ab+ as the value of type, all
write operations take place at the end of the file. Although you can reposition
the file pointer using fseek or rewind, the file pointer always moves back to
the end of the file before the system carries out any write operation. This
action prevents you from writing over existing data.

When you specify any of the types containing +, you can read from and write to
the file, and the file is said to be open for update. However, when switching
from reading to writing or from writing to reading, you must include an
intervening fseek, fsetpos, or rewind operation. You can specify the current
file position with fseek.

In accessing text files, carriage-return line-feed (CR-LF) combinations are
translated into a single line feed (LF) on input; LF characters are translated
to CR-LF combinations on output. Accesses to binary files suppress all of these
translations. (See the Programming Guide for differences between text and
binary streams.)

If _fdopen returns NULL, use the _close function to close the file. If _fdopen
is successful, you must use fclose to close the stream and file. The _fdopen
function returns a pointer to a file structure that can be used to access the
open file. A NULL pointer return value indicates an error.

Example of _fdopen


ΓòÉΓòÉΓòÉ <hidden> Example of _fdopen ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example opens the file sample.dat and associates a stream with the file
using _fdopen. It then reads from the stream into the buffer.

                                                                        *
************************************************************************/

#include <io.h>
#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>
#include <string.h>

int main(void)
{
   long length;
   int  fh;
   char buffer[20];
   FILE *fp;

   memset(buffer,'\0',20); /* Initialize buffer */

   printf("\nCreating sample.dat.\n");
   system("echo Sample Program > sample.dat");

   if (-1 == (fh = _open("sample.dat",O_RDWR | O_APPEND)))
   {
      perror("Unable to open sample.dat");
      return 1;
      }
   if (NULL == (fp = _fdopen(fh,"r")))
   {
      perror("fdopen failed");
      _close(fh);
      return 1;
      }

   if ( 7 != fread(buffer,1,7,fp))
   {
      perror("fread failed");
      fclose(fp);
      return 1;
   }

   printf("Successfully read from the stream
            the following:\n%s\n ",buffer);

   fclose(fp);

   return 0;


/*******************  The expected output is:  **************************

      Creating sample.dat.
      Successfully read from the stream the following:
      Sample
*/

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _close - Closes File Associated with Handle
o _creat - Create New File
o fclose  - Close Stream
o fopen  - Open Files
o fseek  - Reposition File Position
o fsetpos  - Set File Position
o _open - Open File
o rewind  - Adjust Current File Position
o _sopen - Open Shared File
o stdio.h


ΓòÉΓòÉΓòÉ 6.71. feof  - Test End-of-File Indicator ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int feof(FILE *stream);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The feof function indicates whether the end-of-file flag is set for the given
stream.  The end-of-file flag is set by several functions to indicate the end
of the file.  The end-of-file flag is cleared by calling rewind, fsetpos,
fseek, or clearerr for this stream.

The feof function returns a nonzero value if and only if the EOF flag is set;
otherwise, 0 is returned.

Example of feof


ΓòÉΓòÉΓòÉ <hidden> Example of feof ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example scans the input stream until it reads an end-of-file character.

                                                                        *
************************************************************************/

#include <stdio.h>

int main(void)
{
   char string[100];
   FILE *stream;
   stream = fopen("myfile.dat", "r");
   .
   .
   .
   /* scan an input stream until an end-of-file character is read */
   while (!feof(stream))
      if (fscanf(stream, "%s", string))
         /* process the string */;
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o clearerr  - Reset Error Indicators
o ferror  - Test for Read/Write Errors
o fseek  - Reposition File Position
o fsetpos  - Set File Position
o perror  - Print Error Message
o rewind  - Adjust Current File Position
o stdio.h


ΓòÉΓòÉΓòÉ 6.72. ferror  - Test for Read/Write Errors ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int ferror(FILE *stream);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The ferror function tests for an error in reading from or writing to the given
stream.  If an error occurs, the error indicator for the stream remains set
until you close stream, call rewind, or call clearerr.

The ferror function returns a nonzero value to indicate an error on the given
stream.  A return value of 0 means no error has occurred.

Note:  Some compilers are able to continue reading past EOF. Others require a
call to another function such as clearerr to read beyond EOF. See the
Programming Guide for more information.

Example of ferror


ΓòÉΓòÉΓòÉ <hidden> Example of ferror ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example puts data out to a stream and then checks that a write error has
not occurred.

                                                                        *
************************************************************************/

#include <stdio.h>

int main(void)
{
   FILE *stream;
   char *string = "Important information";

   stream = fopen("myfile.dat","w");

   fprintf(stream, "%s\n", string);
   if (ferror(stream))
   {
      printf("write error\n");
      clearerr(stream);
   }
   if (fclose(stream))
      perror("fclose error");
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o clearerr  - Reset Error Indicators
o feof  - Test End-of-File Indicator
o fopen  - Open Files
o perror  - Print Error Message
o stdio.h
o strerror  - Set Pointer to Runtime Error Message
o _strerror - Set Pointer to System Error String


ΓòÉΓòÉΓòÉ 6.73. fflush  - Write Buffer to File ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int fflush(FILE *stream);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The fflush function causes the system to empty the buffer associated with the
specified output stream, if possible. If the stream is open for input, fflush
undoes the effect of any ungetc function. The stream remains open after the
call.

If stream is NULL, the system flushes all open streams.

The fflush function returns the value 0 if it successfully flushes the buffer.
The fflush function returns EOF if an error occurs.

Note:  The system automatically flushes buffers when you close the stream, or
       when a program ends normally without closing the stream.

Example of fflush


ΓòÉΓòÉΓòÉ <hidden> Example of fflush ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example flushes a stream buffer.

                                                                        *
************************************************************************/

#include <stdio.h>

int main(void)
{
   FILE *stream;
   stream = fopen("myfile.dat", "w");
   .
   .
   .
   fflush(stream);
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fclose  - Close Stream
o _flushall - Write Buffers to Files
o setbuf  - Control Buffering
o ungetc  - Push Character onto Input Stream
o stdio.h


ΓòÉΓòÉΓòÉ 6.74. fgetc  - Read a Character ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int fgetc(FILE *stream);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The fgetc function reads a single unsigned character from the input stream at
the current position and increases the associated file pointer, if any, so that
it points to the next character.

The fgetc function returns the character read as an integer. An EOF return
value indicates an error or an end-of-file condition.  Use feof or ferror to
determine whether the EOF value indicates an error or the end of the file.

The fgetc function is identical to getc but is guaranteed to be a function.

Example of fgetc


ΓòÉΓòÉΓòÉ <hidden> Example of fgetc ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example gathers a line of input from a stream.

                                                                        *
************************************************************************/

#include <stdio.h>

#define  MAX_LEN  80

int main(void)
{
   FILE *stream;
   char buffer[MAX_LEN + 1];
   int i, ch;

   stream = fopen("myfile.dat","r");

   for (i = 0; (i < (sizeof(buffer)-1) &&
         ((ch = fgetc(stream)) != EOF) && (ch != '\n')); i++)
      buffer[i] = ch;

   buffer[i] = '\0';

   if (fclose(stream))
      perror("fclose error");
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _fgetchar - Read Single Character from stdin
o feof  - Test End-of-File Indicator
o ferror  - Test for Read/Write Errors
o fputc  - Write a Character
o getc  - Read a Character
o _getch - _getche - Read Character from Keyboard
o stdio.h


ΓòÉΓòÉΓòÉ 6.75. _fgetchar - Read Single Character from stdin ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int _fgetchar(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _fgetchar function reads a single character from the stdin stream. It is
equivalent to a call to the SAA function fgetc:

   fgetc(c, stdin);

For portability, replace _fgetchar with its SAA equivalent.

The _fgetchar function returns the character read.  A return value of EOF
indicates an error or end-of-file position. Use feof or ferror to tell whether
the return value indicates an error or an end-of-file position.

Example of _fgetchar


ΓòÉΓòÉΓòÉ <hidden> Example of _fgetchar ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example gathers a line of input from stdin using _fgetchar:

                                                                        *
************************************************************************/

#include <stdio.h>

int main(void)
{
    char buffer[81];
    int i, ch;

    printf("Please input a line of characters...\n");

    for (i=0; (i<80) && ((ch = _fgetchar()) != EOF) && (ch!='\n'); i++)
        buffer[i] = ch;
    buffer[i] = '\0';

    printf("The input line was : %s\n", buffer);

    return 0;

/***********  If the input was "A line of characters.", then  *********
**************    the output should be similar to:  *******************

   Please input a line of characters...
   A line of characters.
   The input line was : A line of characters.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o feof  - Test End-of-File Indicator
o ferror  - Test for Read/Write Errors
o fgetc  - Read a Character
o _fputchar - Write Character
o getc  - Read a Character
o _getch - _getche - Read Character from Keyboard
o stdio.h


ΓòÉΓòÉΓòÉ 6.76. fgetpos  - Get File Position ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int fgetpos(FILE *stream, fpos_t *pos);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The fgetpos function stores the current position of the file pointer associated
with stream into the object pointed to by pos.  The value pointed to by pos can
be used later in a call to fsetpos to reposition the stream.

If successful, the fgetpos function returns 0.  On error, fgetpos returns
nonzero and sets errno to a nonzero value.

Example of fgetpos


ΓòÉΓòÉΓòÉ <hidden> Example of fgetpos ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example opens the file myfile for reading.  The current file pointer
position is stored into the variable pos.

                                                                        *
************************************************************************/

#include <stdio.h>

FILE *stream;

int main(void)
{
   int retcode;
   fpos_t pos;

   stream = fopen("myfile.dat", "rb");

   /* The value returned by fgetpos can be used by fsetpos */
   /* to set the file pointer if 'retcode' is 0            */

   if ((retcode = fgetpos(stream, &pos)) == 0)
      printf("Current position of file pointer found\n");
   fclose(stream);
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fseek  - Reposition File Position
o fsetpos  - Set File Position
o ftell  - Get Current Position
o stdio.h


ΓòÉΓòÉΓòÉ 6.77. fgets  - Read a String ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

char *fgets (char *string, int n, FILE *stream);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The fgets function reads characters from the current stream position up to and
including the first new-line character (\n), up to the end of the stream, or
until the number of characters read is equal to n-1, whichever comes first.
The fgets function stores the result in string and adds a null character (\0)
to the end of the string.  The string includes the new-line character, if read.
If n is equal to 1, the string is empty.

The fgets function returns a pointer to the string buffer if successful.  A
NULL return value indicates an error or an end-of-file condition.  Use feof or
ferror to determine whether the NULL value indicates an error or the end of the
file. In either case, the value of the string is unchanged.

Example of fgets


ΓòÉΓòÉΓòÉ <hidden> Example of fgets ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example gets a line of input from a data stream.  The example reads no
more than MAX_LEN - 1 characters, or up to a new-line character, from the
stream.

                                                                        *
************************************************************************/

#include <stdio.h>

#define  MAX_LEN  100

int main(void)
{
   FILE *stream;
   char line[MAX_LEN], *result;

   stream = fopen("myfile.dat","rb");

   if ((result = fgets(line,MAX_LEN,stream)) != NULL)
       printf("The string is %s\n", result);

   if (fclose(stream))
       perror("fclose error");
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o feof  - Test End-of-File Indicator
o ferror  - Test for Read/Write Errors
o fputs  - Print Strings
o gets  - Read a Line
o puts  - Write a String
o stdio.h


ΓòÉΓòÉΓòÉ 6.78. _filelength - Determine File Length ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <io.h>

long _filelength(int handle);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _filelength function returns the length, in bytes, of the file associated
with handle. The length of the file will be correct even if you have the handle
opened and have appended data to the file.

A return value of -1L indicates an error, and errno is set to one of the
following values:

Value          Meaning
EBADF          The file handle is incorrect or the mode specified does not
               match the mode you opened the file with.
EOS2ERR        The call to the operating system was not successful.

Example of _filelength


ΓòÉΓòÉΓòÉ <hidden> Example of _filelength ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example opens a file and tries to determine the current length of the file
using _filelength.

                                                                        *
************************************************************************/

#include <io.h>
#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>

int main(void)
{
   long length;
   int  fh;

   printf("\nCreating sample.dat.\n");
   system("echo Sample Program > sample.dat");

   if (-1 == (fh = _open("sample.dat",O_RDWR | O_APPEND)))
   {
      printf("Unable to open sample.dat.\n");
      return 1;
   }

   if (-1 == (length = _filelength(fh)))
   {
      printf("Unable to determine length of sample.dat.\n");
      return 1;
   }

   printf("Current length of sample.dat is %d.\n",length);

   _close(fh);
   return 0;

/****************  The expected output is:  *****************************

      Creating sample.dat.
      Current length of sample.dat is 17.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _chsize - Alter Length of File
o __eof - Determine End of File
o io.h


ΓòÉΓòÉΓòÉ 6.79. _fileno - Determine File Handle ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int _fileno(FILE *stream);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _fileno function determines the file handle currently associated with
stream.

The _fileno function returns the file handle. If the function fails, the return
value is -1 and the errno variable may be set to one of the following values:

Value          Meaning
ENULLFCB       The input stream is NULL.
EBADTYPE       The input stream file is not a stream file.

The result is undefined if stream does not specify an open file.

Example of _fileno


ΓòÉΓòÉΓòÉ <hidden> Example of _fileno ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example determines the file handle of the stderr data stream:

                                                                        *
************************************************************************/

#include <stdio.h>

int main(void)
{
    int result;

    result = 0xFFFF & _fileno(stderr);

    printf("The file handle associated with stderr is %d.\n", result);

    return 0;


/*******************  The output should be similar to:  *****************

   The file handle associated with stderr is 2.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _dup -Associate Second Handle with Open File
o _dup2 -Associate Second Handle with Open File
o fopen  - Open Files
o freopen  - Redirect Open Files
o _isatty - Test Handle for Character Device
o _open - Open File
o stdio.h


ΓòÉΓòÉΓòÉ 6.80. floor - Integer <= Argument ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h>

double floor(double x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The floor function calculates the largest integer that is less than or equal to
x. The floor function returns the floating-point result as a double value.

The result of the floor function cannot have a range error.

Example of floor


ΓòÉΓòÉΓòÉ <hidden> Example of floor ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example assigns y value of the largest integer less than or equal to 2.8
and z the value of the largest integer less than or equal to -2.8.

                                                                        *
************************************************************************/

#include <math.h>
#include <stdio.h>

int main(void)
{
   double y, z;

   y = floor(2.8);
   z = floor(-2.8);

   printf("floor(  2.8 ) = %lf\n", y);
   printf("floor( -2.8 ) = %lf\n", z);
}

/*******************  Output should be similar to:  ***************

floor(  2.8 ) = 2.000000
floor( -2.8 ) = -3.000000
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o ceil - Integer >= Argument
o fmod  - Floating-Point Remainder
o math.h


ΓòÉΓòÉΓòÉ 6.81. _flushall - Write Buffers to Files ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int _flushall(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _flushall function causes the system to write to file the contents of all
buffers associated with open output streams (including stdin, stdout, and
stderr). It clears all buffers associated with open input streams of their
current contents. The next read operation, if there is one, reads new data from
the input files into the buffers.  All streams remain open after the call.

For portability, use the SAA function fflush instead of _flushall.

The _flushall function returns the number of open streams of input and output.
If an error occurs, _flushall returns EOF.

Example of _flushall


ΓòÉΓòÉΓòÉ <hidden> Example of _flushall ΓòÉΓòÉΓòÉ

/************************************************************************
*
In this example, _flushall completes any pending input or output on all streams
by flushing all buffers:

                                                                        *
************************************************************************/

#include <stdio.h>

int main(void)
{
    int i,numflushed;

    char buffer1[5] = {1,2,3,4};
    char buffer2[5] = {5,6,7,8};

    char *file1 = "file1.dat";
    char *file2 = "file2.dat";
    FILE *stream1, *stream2;

    stream1 = fopen(file1,"a+");
    stream2 = fopen(file2,"a+");

    for(i = 0; i <= sizeof(buffer1); i++)
    {
         fputc(buffer1[i], stream1);
         fputc(buffer2[i], stream2);
    };

    numflushed = _flushall();       /*  all streams flushed  */
    printf("Number of files flushed = %d\n", numflushed);

    fclose(stream1);
    fclose(stream2);

    return 0;

/*******************  The output should be similar to:  *****************

   Number of files flushed = 5
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _close - Closes File Associated with Handle
o fclose  - Close Stream
o fflush  - Write Buffer to File
o stdio.h


ΓòÉΓòÉΓòÉ 6.82. fmod  - Floating-Point Remainder ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h>

double fmod(double x, double y);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The fmod function calculates the floating-point remainder of x/y. The absolute
value of the result is always less than the absolute value of y. The result
will have the same sign as x. If y is zero or if x/y causes an overflow, the
function returns 0.

Example of fmod


ΓòÉΓòÉΓòÉ <hidden> Example of fmod ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example computes z as the remainder of x/y; here x/y is -3 with a
remainder of -1:

                                                                        *
************************************************************************/

#include <math.h>

int main(void)
{
   double x, y, z;

   x = -10.0;
   y = 3.0;
   z = fmod(x,y);      /* z = -1.0 */

   printf("fmod( %lf, %lf) = %lf\n", x, y, z);
}

/*******************  Output should be similar to:  ***************

fmod( -10.000000, 3.000000) = -1.000000
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o ceil - Integer >= Argument
o fabs  - Calculate Floating-Point Absolute Value
o floor - Integer <= Argument
o math.h


ΓòÉΓòÉΓòÉ 6.83. fopen  - Open Files ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

FILE *fopen(const char *filename, const char *mode);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The fopen function opens the file specified by filename.  The mode variable is
a character string specifying the type of access requested for the file.  The
mode variable contains one positional parameter followed by optional keyword
parameters.

The possible values for the positional parameters are:

Mode Description
r
  Open a text file for reading.  The file must exist.
w
  Create a text file for writing.  If the given file exists, its contents are
  destroyed.
a
  Open a text file in append mode for writing at the end of the file.  fopen
  creates the file if it does not exist.
r+
  Open a text file for both reading and writing.  The file must exist.
w+
  Create a text file for both reading and writing.  If the given file exists,
  its contents are destroyed.
a+
  Open a text file in append mode for reading or updating at the end of the
  file.  fopen creates the file if it does not exist.
rb
  Open a binary file for reading.  The file must exist.
wb
  Create an empty binary file for writing.  If the file exists, its contents
  are destroyed.
ab
  Open a binary file in append mode for writing at the end of the file. fopen
  creates the file if it does not exist.
r+b or rb+
  Open a binary file for both reading and writing.  The file must exist.
w+b or wb+
  Create an empty binary file for both reading and writing.  If the file
  exists, its contents will be destroyed.
a+b or ab+
  Open a binary file in append mode for writing at the end of the file.  fopen
  creates the file if it does not exist.

Warning: Use the w, w+, wb, w+b, and wb+ parameters with care;  data in
existing files of the same name will be lost.

Text files contain printable characters and control characters organized into
lines.  Each line ends with a new-line character, except for the last line,
which does not require one. The system may insert or convert control characters
in an output text stream.

Note:  Data output to a text stream may not compare as equal to the same data
on input.

Binary files contain a series of characters.  For binary files, the system does
not translate control characters on input or output.

When you open a file with a, a+, ab, a+b or ab+ mode, all write operations take
place at the end of the file.  Although you can reposition the file pointer
using fseek or rewind, the write functions move the file pointer back to the
end of the file before they carry out any operation. This action prevents you
from overwriting existing data.

When you specify the update mode (using + in the second or third position), you
can both read from and write to the file.  However, when switching between
reading and writing, you must include an intervening positioning function such
as fseek, fsetpos, rewind, or fflush.  Output may immediately follow input if
the end-of-file was detected.

The keyword parameters are:

blksize=value
  Specifies the maximum length, in bytes, of a physical block of records. For
  fixed-length records, the maximum size is 32760 bytes.  For variable-length
  records, the maximum is 32756. The default buffer size is 4096 bytes.
lrecl=value
  Specifies the length, in bytes, for fixed-length records and the maximum
  length for variable-length records. For fixed-length records, the maximum
  length is 32760 bytes.  For variable-length records, the maximum is 32756. If
  the value of LRECL is larger than the value of BLKSIZE, the LRECL value is
  ignored
recfm=value
  value can be:

   F    fixed-length, unblocked records
   V    variable-length, unblocked records The default for the C/C++ Tools
  compiler is fixed-length record format.
type=value
  value can be:

  memory  This parameter identifies this file as a memory file that is
  accessible only from C programs. This is the default. If you want to use a
  memory file, you must compile with the /Sv option.

The C/C++ Tools compiler does not support record I/O.

The fopen function generally fails if parameters are mismatched.

The file attributes can be altered only if the open mode specified with the
fopen function is one of the write modes (w, w+, wb, or wb+). The system
deletes the existing file and creates a new file with the attributes specified
in fopen.

The fopen function returns a pointer to a file structure that can be used to
access the open file.  A NULL pointer return value indicates an error.

Example of fopen


ΓòÉΓòÉΓòÉ <hidden> Example of fopen ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example attempts to open a file for reading:

                                                                        *
************************************************************************/

#include <stdio.h>

int main(void)
{
   FILE *stream;

   if ((stream = fopen("myfile.dat", "r")) == NULL)
      printf("Could not open data file\n");

   /* The following call opens a fixed record length file */
   /* for reading and writing.                            */

   stream = fopen("myfile.dat", "rb+, lrecl=80,  \
               blksize=240, recfm=f");
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _creat - Create New File
o fclose  - Close Stream
o fflush  - Write Buffer to File
o fread  - Read Items
o freopen  - Redirect Open Files
o _open - Open File
o _sopen - Open Shared File
o fseek  - Reposition File Position
o fsetpos  - Set File Position
o fwrite  - Write Items
o rewind  - Adjust Current File Position
o stdio.h


ΓòÉΓòÉΓòÉ 6.84. _fpatan - Calculate Arctangent ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <builtin.h>

double _fpatan(double x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _fpatan function calculates the arctangent of x, which is a value in
radians between -у/2 and у/2. This function causes the compiler to emit the
appropriate 80387 instruction for the calculation of arctangent.

Because it is a built-in function and has no backing code in the library:

o You cannot take the address of _fpatan.
o You cannot parenthesize a _fpatan function call, because parentheses specify
  a call to the backing code for the function.

This function returns the arctangent of x.

Example of _fpatan


ΓòÉΓòÉΓòÉ <hidden> Example of _fpatan ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example calculates the arctangent of x.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <builtin.h>
#include <math.h>

int main(void)
    {
    double a,c;
    c = 0.45;

    a = _fpatan(c);

    printf("The arctangent of %lf is %lf.\n", c, a);
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o atan - atan2  - Calculate Arctangent
o _fptan - Calculate Tangent
o tan  - Calculate Tangent
o tanh  - Calculate Hyperbolic Tangent


ΓòÉΓòÉΓòÉ 6.85. _fpreset - Reset Floating-Point Unit ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <float.h>

void _fpreset(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _fpreset function resets the floating-point unit to the default state that
the math library requires to function correctly. This function is often used
within signal handlers. For more information on signal handlers, see the
Programming Guide.

If a program traps floating-point error signals (SIGFPE) with signal, the
program can safely recover from floating-point errors by calling longjmp.

The _fpreset function resets the floating-point unit of the current thread
only.  It does not affect any other threads that may be processing.

There is no return value.

Example of _fpreset


ΓòÉΓòÉΓòÉ <hidden> Example of _fpreset ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example establishes the function fphandler as a floating-point error
handler. The main program produces a floating-point error, which causes control
to be passed to fphandler. The fphandler function calls _fpreset to reset the
floating-point unit, and then returns to main.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <signal.h>
#include <setjmp.h>
#include <float.h>

jmp_buf mark;

void fphandler(int sig)
{
    printf("Floating point signal = %d\n", sig);
    _fpreset();     /* Reinitialize floating-point package */
    longjmp(mark, -1);
}

int main(void)
{
    double a = 1.0, b = 0.0, c;

    if (signal(SIGFPE, fphandler) == SIG_ERR)
        exit(-1);

    if (setjmp(mark) == 0)
    {
        c = a / b;             /* generate floating-point error */
        printf("Should never get here\n");
    }
    printf("Recovered from floating-point error\n");

    return 0;

    /* The expected output is:

       Floating point signal = 3
       Recovered from floating-point error  */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _clear87 - Clear Floating-Point Status Word
o _control87 - Set Floating-Point Status Word
o longjmp  - Restore Stack Environment
o signal Install Interrupt Handlers
o _status87 - Get Floating-Point Status Word
o float.h


ΓòÉΓòÉΓòÉ 6.86. fprintf  - Write Formatted Data ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int fprintf(FILE *stream, const char *format-string, argument-list);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA, Extension

The fprintf function formats and writes a series of characters and values to
the output stream.  The fprintf function converts each entry in argument-list,
if any, and writes to the stream according to the corresponding format
specification in the format-string.

The format-string has the same form and function as the format-string argument
for the printf function.

In extended mode, fprintf also converts floating-point values of NaN and
infinity to the strings "NAN" or "nan" and "INFINITY" or "infinity". The case
and sign of the string is determined by the format specifiers.  See Infinity
and NaN Support for more information on infinity and NaN values.

The fprintf function returns the number of characters printed or a negative
value if an output error occurs.

Example of fprintf


ΓòÉΓòÉΓòÉ <hidden> Example of fprintf ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example sends a line of asterisks for each integer in the array count to
the file myfile.  The number of asterisks printed on each line corresponds to
an integer in the array.

                                                                        *
************************************************************************/

#include <stdio.h>

int count [10] = {1, 5, 8, 3, 0, 3, 5, 6, 8, 10};

int main(void)
{
   int i,j;
   FILE *stream;

   stream = fopen("myfile.dat", "w");
                  /* Open the stream for writing */
   for (i=0; i < sizeof(count) / sizeof(count[0]); i++)
   {
      for (j = 0; j < count[i]; j++)
         fprintf(stream,"*");
                  /* Print asterisk              */
         fprintf(stream,"\n");
                  /* Move to the next line       */
   }
   fclose (stream);
}

/*******************  Output should be similar to:  ***************

*
*****
********
***

***
*****
******
********
**********
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _cprintf - Print Characters to Screen
o fscanf  - Read Formatted Data
o printf  - Formatted Print
o sprintf  - Formatted Print to Buffer
o vfprintf  - Print Argument Data
o vprintf  - Print Argument Data
o vsprintf  - Print Argument Data
o Infinity and NaN Support
o stdio.h


ΓòÉΓòÉΓòÉ 6.87. _fptan - Calculate Tangent ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <builtin.h>

double _fptan(double x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _fptan function calculates the tangent of x, where x is expressed in
radians. The value of x must be less than 2**63. This function causes the
compiler to emit the appropriate 80387 instruction for the calculation of
tangent.

Because it is a built-in function and has no backing code in the library:

o You cannot take the address of _fptan.
o You cannot parenthesize a _fptan function call, because parentheses specify a
  call to the backing code for the function in the library.

This function returns the tangent of a variable x expressed in radians.

Example of _fptan


ΓòÉΓòÉΓòÉ <hidden> Example of _fptan ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example calculates the tangent of pi/4.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <math.h>
#include <builtin.h>

int main(void)
   {
   double pi, x;

   pi = 3.1415926;
   x = _fptan(pi/4.0);

   printf("The tangent of %lf is %lf\n", pi/4, x);
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o atan - atan2  - Calculate Arctangent
o _fpatan - Calculate Arctangent
o tan  - Calculate Tangent
o tanh  - Calculate Hyperbolic Tangent


ΓòÉΓòÉΓòÉ 6.88. fputc  - Write a Character ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int fputc(int c, FILE *stream);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The fputc function converts c to an unsigned char and then writes c to the
output stream at the current position and advances the file position
appropriately. If the stream is opened with one of the append modes, the
character is appended to the end of the stream.

The fputc function returns the character written.  A return value of EOF
indicates an error.

The fputc function is identical to putc but is guaranteed to be a function.

Example of fputc


ΓòÉΓòÉΓòÉ <hidden> Example of fputc ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example writes the contents of buffer to a file called myfile.

Note:  Because the output occurs as a side effect within the second expression
of the for statement, the statement body is null.

                                                                        *
************************************************************************/

#include <stdio.h>

#define NUM_ALPHA  26

int main(void)
{
  FILE * stream;
  int i;
  int ch;

  char buffer[NUM_ALPHA + 1] = "abcdefghijklmnopqrstuvwxyz";

  if (( stream = fopen("myfile.dat", "w"))!= NULL )
  {
    /* Put buffer into file */
    for ( i = 0; ( i < sizeof(buffer) ) &&
           ((ch = fputc( buffer[i], stream)) != EOF ); ++i );
    fclose( stream );
  }
  else
    perror( "Error opening myfile" );

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fgetc  - Read a Character
o _fputchar - Write Character
o putc - putchar  - Write a Character
o _putch - Write Character to Screen
o stdio.h


ΓòÉΓòÉΓòÉ 6.89. _fputchar - Write Character ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int _fputchar(int c);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _fputchar function writes the single character c to the stdout stream at
the current position. It is equivalent to a call to the SAA function fputc:

   fputc(c, stdout);

For portability, replace _fputchar with the SAA equivalent.

The function returns the character written.  A return value of EOF indicates
that a write error has occurred. Use ferror and feof to tell whether this is an
error condition or the end of the file.

Example of _fputchar


ΓòÉΓòÉΓòÉ <hidden> Example of _fputchar ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example writes the contents of buffer to stdout:

                                                                        *
************************************************************************/

#include <stdio.h>

int main(void)
{
    char buffer[80];
    int i, ch = 1;

    for (i=0; i<80; i++)
        buffer[i] = 'c';

    for (i=0; (i<80) && (ch!=EOF); i++)
        ch = _fputchar(buffer[i]);

    printf("\n");

    return 0;

/************************  The output should be similar to:  *************

  ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _fgetchar - Read Single Character from stdin
o fputc  - Write a Character
o putc - putchar  - Write a Character
o _putch - Write Character to Screen
o stdio.h


ΓòÉΓòÉΓòÉ 6.90. fputs  - Print Strings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int fputs(const char *string, FILE *stream);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The fputs function copies string to the output stream at the current position.
It does not copy the null character (\0) at the end of the string.

If an error occurs, the fputs function returns EOF;  otherwise, it returns a
non-negative value.

Example of fputs


ΓòÉΓòÉΓòÉ <hidden> Example of fputs ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example writes a string to a stream.

                                                                        *
************************************************************************/

#include <stdio.h>

#define NUM_ALPHA  26

int main(void)
{
  FILE * stream;
  int num;

  /* Do not forget that the '\0' char occupies one character */
  static char buffer[NUM_ALPHA + 1] = "abcdefghijklmnopqrstuvwxyz";

  if ((stream = fopen("myfile.dat", "w")) != NULL )
  {
     /* Put buffer into file */
     if ( (num = fputs( buffer, stream )) != EOF )
     {
       /* Note that fputs() does not copy the \0 character */
       printf( "Total number of characters written to file = %i\n", num );
       fclose( stream );
     }
     else   /* fputs failed */
       perror( "fputs failed" );
  }
  else
     perror( "Error opening myfile" );
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _cputs - Write String to Screen
o fgets  - Read a String
o gets  - Read a Line
o puts  - Write a String
o stdio.h


ΓòÉΓòÉΓòÉ 6.91. fread  - Read Items ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

size_t fread(void *buffer, size_t size, size_t count,
                FILE *stream);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The fread function reads up to count items of size length from the input stream
and stores them in the given buffer.  The position in the file increases by the
number of bytes read.

The fread function returns the number of full items successfully read, which
can be less than count if an error occurs or if the end-of-file is met before
reaching count.  If size or count is 0, fread returns zero and the contents of
the array and the state of the stream remain unchanged.

The ferror and feof functions are used to distinguish between a read error and
an end-of-file.

Example of fread


ΓòÉΓòÉΓòÉ <hidden> Example of fread ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example attempts to read NUM_ALPHA characters from the file myfile. If
there are any errors with either fread or fopen, a message is printed.

                                                                        *
************************************************************************/

#include <stdio.h>

#define NUM_ALPHA  26

int main(void)
{
  FILE * stream;
  int num;       /* number of characters read from stream */

  /* Do not forget that the '\0' char occupies one character too! */
  char buffer[NUM_ALPHA + 1];

  if (( stream = fopen("myfile.dat", "r"))!= NULL )
  {
    num = fread( buffer, sizeof( char ), NUM_ALPHA, stream );
    if ( num ) {  /* fread success */
      printf( "Number of characters has been read = %i\n", num );
      printf( "buffer = %s\n", buffer );
      fclose( stream );
    }
    else {  /* fread failed */
      if ( ferror(stream) )    /* possibility 1 */
        perror( "Error reading myfile" );
      else if ( feof(stream))  /* possibility 2 */
        perror( "EOF found" );
    }
  }
  else
    perror( "Error opening myfile" );

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o feof  - Test End-of-File Indicator
o ferror  - Test for Read/Write Errors
o fopen  - Open Files
o fwrite  - Write Items
o _read - Read Into Buffer
o stdio.h


ΓòÉΓòÉΓòÉ 6.92. free  - Release Storage Blocks ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>  /* also defined in <malloc.h> */

void free(void *ptr);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA, Extension

The free function frees a block of storage.  The ptr variable points to a block
previously reserved with a call to calloc, malloc, or realloc.  The number of
bytes freed is the number of bytes specified when you reserved (or reallocated,
in the case of realloc) the block of storage.  If ptr is NULL, free simply
returns.

There is no return value.

Note:  Attempting to free a block of storage not allocated with calloc, malloc,
       or realloc (or previously freed storage) can affect the subsequent
       reserving of storage and lead to undefined results.

Example of free


ΓòÉΓòÉΓòÉ <hidden> Example of free ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses calloc to allocate storage for x array elements and then
calls free to free them.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
  long * array;    /* start of the array */
  long * index;    /* index variable     */
  int    i;        /* index variable     */
  int  num;        /* number of entries of the array */

  printf( "Enter the size of the array\n" );
  scanf( "%i", &num );

  /* allocate num entries */
  if ( (index = array = calloc( num, sizeof( long ))) != NULL )
  {
    .
    .  /*  do something with the array  */
    .
    free( array );                        /* deallocates array  */
  }
  else
  { /* Out of storage */
    perror( "Error: out of storage" );
    abort();
  }
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _alloca - Temporarily Reserve Storage Block
o calloc  - Reserve and Initialize Storage
o _debug_free - Release Storage Blocks
o malloc  - Reserve Storage Block
o realloc  - Change Reserved Storage Block Size
o malloc.h
o _tfree - Free Tiled Storage Block
o stdlib.h


ΓòÉΓòÉΓòÉ 6.93. _freemod - Free User DLL ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

int _freemod(unsigned long module_handle);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _freemod function frees all references to a user-created dynamic-link
library (DLL) for the calling process. It is the counterpart of the _loadmod
function, which loads a DLL for the process. The module_handle is the module
handle of the DLL, which was returned by _loadmod.

If successful, the _freemod function returns 0. If not, _freemod returns -1 and
sets errno to EOS2ERR.

Example of _freemod


ΓòÉΓòÉΓòÉ <hidden> Example of _freemod ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example loads the DLL mark with _loadmod, and uses the OS/2 function
DosQueryProcAddr to get the address of the function dor from within the DLL. It
then calls that function, which multiplies two integers passed to it. When the
function and DLL are no longer needed, the program frees the DLL module. The
macro INCL_DOS and the types PFN and APIRET are required for the OS/2 call, and
are defined by including the <os2.h> header file.

Note:  To run this program, you must first create mark.dll. Copy the code for
       the PLUS function into a file called mark.c, and the code for the .DEF
       file into mark.def.  Eliminate the comments from these two files.
       Compile with the command:

                 icc /Ge- mark.c mark.def
       You can then run the example:

                                                                        *
************************************************************************/

#define INCL_DOS
#include <os2.h>
#include <stdio.h>
#include <stdlib.h>

/* This is the code for MARK.DEF

LIBRARY MARK

PROTMODE

EXPORTS PLUS                       */

/* This is the code for PLUS function in the DLL

   #pragma linkage( PLUS, system )
   int PLUS( int a, int b )
   {
      return a + b;
   }                                               */

int main(void)
{
   int x = 4, y = 7;

   unsigned long handle;
   char * modname = "MARK" ;     /* DLL name              */
   char * fname = "PLUS"  ;      /* function name         */

   PFN faddr;                    /* pointer to function   */
   APIRET rc;                    /* return code           */
                                 /* from DosQueryProcAddr */

   /*  dynamically load the 'mark' DLL  */
   if (_loadmod(modname, &handle) )
   {
      printf("Error loading module %s\n", modname );
      exit (-1);
   }

   /*  get function address from DLL  */
   rc = DosQueryProcAddr( handle, 0, fname, &faddr );

   if (rc == 0)
      printf("Calling the function from the %s DLL to add %d
               and %d\n", modname,x,y);
      printf("The result of the function call is %d\n",
              faddr(x,y));
   else
   {
      printf("Error locating address of function %s\n",
               fname);
      _freemod( handle );
      exit(-1);
   }

   if( _freemod( handle ))
   {
      printf("Error in freeing the %s DLL module\n",
               modname);
      exit(-1);
   }

   printf("Reference to the %s DLL module has been freed\n",
            modname);

   return 0;

/**************  The expected output is  ********************

      Calling the function from the DLL to add 4 and 7
      The result of the function call is 11
      Reference to the MARK DLL module has been freed

*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _loadmod - Load User DLL
o stdlib.h


ΓòÉΓòÉΓòÉ 6.94. freopen  - Redirect Open Files ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

FILE *freopen(const char *filename, const char *mode, FILE *stream);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The freopen function closes the file currently associated with stream and
reassigns stream to the file specified by filename. The freopen function opens
the new file associated with stream with the given mode, which is a character
string specifying the type of access requested for the file. You can also use
the freopen function to redirect the standard stream files stdin, stdout, and
stderr to files that you specify.

If filename is an empty string, freopen closes and reopens the stream to the
new open mode, rather than reassigning it to a new file or device. You can use
freopen with no file name specified to change the mode of a standard stream
from text to binary without redirecting the stream, for example:

   fp = freopen("", "rb", stdin);
You can use the same method to change the mode from binary back to text.

Note:  This method is included in the SAA C definition, but not in the ANSI C
standard.

See fopen. for a description of the mode parameter.

The freopen function returns the value of stream to the newly opened file. If
an error occurs, freopen closes the original file and returns a NULL pointer
value.

Example of freopen


ΓòÉΓòÉΓòÉ <hidden> Example of freopen ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example closes the stream1 data stream and reassigns its stream pointer:

                                                                        *
************************************************************************/

#include <stdio.h>

int main(void)
{
   FILE *stream, *stream1, *stream2;

   stream = fopen("myfile.dat","r");
   stream1 = stream;
   stream2 = freopen("", "w+", stream1);
}

/************************************************************************
*
Note that stream1 and stream2 will have the same value, but they will not
necessarily have the same value as stream.

                                                                        *
************************************************************************/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _close - Closes File Associated with Handle
o fclose  - Close Stream
o _fcloseall - Close All Open Streams
o fopen  - Open Files
o _open - Open File
o _sopen - Open Shared File
o stdio.h


ΓòÉΓòÉΓòÉ 6.95. frexp  - Separate Floating-Point Value ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h>

double frexp(double x, int *expptr);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The frexp function breaks down the floating-point value x into a term m for the
mantissa and another term n for the exponent, such that the absolute value of m
is greater than or equal to 0.5 and less than 1.0 or equal to 0, and x = m *
(2**n). The frexp function stores the integer exponent n at the location to
which expptr points.

The frexp function returns the mantissa term m.  If x is 0, the function
returns 0 for both the mantissa and exponent.  The mantissa has the same sign
as the argument x.  The result of the frexp function cannot have a range error.

Example of frexp


ΓòÉΓòÉΓòÉ <hidden> Example of frexp ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example decomposes the floating-point value of x, 16.4, into its mantissa
0.5125, and its exponent 5.  It stores the mantissa in y and the exponent in n.

                                                                        *
************************************************************************/

#include <math.h>
#include <stdio.h>

int main(void)
{
   double x, m;
   int n;

   x = 16.4;
   m = frexp(x, &n);

   printf("The mantissa is %lf and the exponent is %d\n", m, n);
}

/*******************  Output should be similar to:  ***************

The mantissa is 0.512500 and the exponent is 5
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o ldexp  - Multiply by a Power of Two
o modf  - Separate Floating-Point Value
o math.h


ΓòÉΓòÉΓòÉ 6.96. fscanf  - Read Formatted Data ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int fscanf (FILE *stream, const char *format-string, argument-list);


ΓòÉΓòÉΓòÉ <hidden> Desciption ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA, Extension

The fscanf function reads data from the current position of the specified
stream into the locations given by the entries in argument-list, if any.  Each
entry in argument-list must be a pointer to a variable with a type that
corresponds to a type specifier in format-string.

The format-string controls the interpretation of the input fields and has the
same form and function as the format-string argument for the scanf function.
See scanf for a description of format-string.

In extended mode, the fscanf function also reads in the strings "INFINITY",
"INF", and "NAN" (in upper or lowercase) and converts them to the corresponding
floating-point value.  The sign of the value is determined by the format
specification. See Infinity and NaN Support for more information on infinity
and NaN values.

The fscanf function returns the number of fields that it successfully converted
and assigned.  The return value does not include fields that fscanf read but
did not assign.

The return value is EOF if an input failure occurs before any conversion, or
the number of input items assigned if successful.

Example of fscanf


ΓòÉΓòÉΓòÉ <hidden> Example of fscanf ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example opens the file myfile for reading and then scans this file for a
string, a long integer value, a character, and a floating-point value.

                                                                        *
************************************************************************/

#include <stdio.h>

#define  MAX_LEN  80

int main(void)
{
   FILE *stream;
   long l;
   float fp;
   char s[MAX_LEN + 1];
   char c;

   stream = fopen("myfile.dat", "r");

   /* Put in various data. */

   fscanf(stream, "%s", &s[0]);
   fscanf(stream, "%ld", &l);
   fscanf(stream, "%c", &c);
   fscanf(stream, "%f", &fp);

   printf("string = %s\n", s);
   printf("long double = %ld\n", l);
   printf("char = %c\n", c);
   printf("float = %f\n", fp);
}

/***************  If myfile contains  ************************
****************abcdefghijklmnopqrstuvwxyz 343.2,  ***********
**********************  expected output is:  *********************

string = abcdefghijklmnopqrstuvwxyz
long double = 343
char = .
float = 2.000000
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _cscanf - Read Data from Keyboard
o fprintf  - Write Formatted Data
o scanf  - Read Data
o sscanf  - Read Data
o Infinity and NaN Support
o stdio.h


ΓòÉΓòÉΓòÉ 6.97. fseek  - Reposition File Position ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int fseek(FILE *stream, long int offset, int origin);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The fseek function changes the current file position associated with stream to
a new location within the file. The next operation on the stream takes place at
the new location.  On a stream open for update, the next operation can be
either a reading or a writing operation.

The origin must be one of the following constants defined in <stdio.h>:

Origin            Definition
SEEK_SET          Beginning of file
SEEK_CUR          Current position of file pointer
SEEK_END          End of file

For a binary stream, you can also change the position beyond the end of the
file.  An attempt to position before the beginning of the file causes an error.
If successful, the fseek function clears the end-of-file indicator, even when
origin is SEEK_END, and undoes the effect of any preceding ungetc function on
the same stream.

The fseek function returns the value 0 if it successfully moves the pointer.  A
nonzero return value indicates an error.  On devices that cannot seek, such as
terminals and printers, the return value is nonzero.

Note:  For streams opened in text mode, fseek has limited use because some
       system translations (such as those between carriage return/line feed and
       new line) can produce unexpected results.  The only fseek operations
       that can be relied upon to work on streams opened in text mode are
       seeking with an offset of zero relative to any of the origin values or
       seeking from the beginning of the file with an offset value returned
       from a call to ftell. See the Programming Guide for more information.

Example of fseek


ΓòÉΓòÉΓòÉ <hidden> Example of fseek ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example opens a file myfile for reading.  After performing input
operations (not shown), it moves the file pointer to the beginning of the file.

                                                                        *
************************************************************************/

#include <stdio.h>

int main(void)
{
   FILE *stream;
   int result;

   stream = fopen("myfile.dat", "r");
   .
   .
   .
   result = fseek(stream, 0L, SEEK_SET);  /* moves the pointer to the */
                                          /* beginning of the file    */
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fgetpos  - Get File Position
o fsetpos  - Set File Position
o ftell  - Get Current Position
o rewind  - Adjust Current File Position
o ungetc  - Push Character onto Input Stream
o stdio.h


ΓòÉΓòÉΓòÉ 6.98. fsetpos  - Set File Position ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int fsetpos(FILE *stream, const fpos_t *pos);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The fsetpos function moves any file position associated with stream to a new
location within the file according to the value pointed to by pos.  The value
of pos was obtained by a previous call to the fgetpos library function.

If fsetpos successfully changes the current position of the file, it returns
the value 0. If successful, the fsetpos function clears the end-of-file
indicator, and undoes the effect of any previous ungetc function on the same
stream.  A nonzero return value indicates an error.

After the fsetpos call, the next operation on a stream in update mode may be
input or output.

Example of fsetpos


ΓòÉΓòÉΓòÉ <hidden> Example of fsetpos ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example opens a file myfile for reading.  After performing input
operations (not shown), it moves the file pointer to the beginning of the file
and rereads the first byte.

                                                                         *
*************************************************************************/

#include <stdio.h>

FILE *stream;

int main(void)
{
   int retcode;
   fpos_t pos, pos1, pos2, pos3;
   char ptr[20];  /* existing file 'myfile.dat' has 20 byte records */

   /* Open file, get position of file pointer, and read first record */

   stream = fopen("myfile.dat", "rb");
   fgetpos(stream,&pos);
   pos1 = pos;
   if (!fread(ptr,sizeof(ptr),1,stream))
       perror("fread error");

   /* Perform a number of read operations
       - the value of 'pos' changes       */
   .
   .
   .
   /* Re-set pointer to start of file and re-read first record */

   fsetpos(stream,&pos1);
   if (!fread(ptr,sizeof(ptr),1,stream))
       perror("fread error");

   fclose(stream);
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fgetpos  - Get File Position
o fseek  - Reposition File Position
o ftell  - Get Current Position
o rewind  - Adjust Current File Position
o ungetc  - Push Character onto Input Stream
o stdio.h


ΓòÉΓòÉΓòÉ 6.99. _fsin - Calculate Sine ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <builtin.h>

double _fsin( double x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _fsin function calculates the sine of x, where x is expressed in radians.
The value of x must be less than 2**63. This function causes the compiler to
emit the appropriate 80387 instruction for the calculation of sine.

Because it is a built-in function and has no backing code in the library:

o You cannot take the address of _fsin.
o You cannot parenthesize a _fsin function call, because parentheses specify a
  call to the backing code for the function in the library.

This function returns the sine of a variable x expressed in radians.

Example of _fsin


ΓòÉΓòÉΓòÉ <hidden> Example of _fsin ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example calculates y as the sine of у/2.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <math.h>
#include <builtin.h>

int main(void)
   {
   double pi, x, y;

   pi = 3.1415926535;
   x = pi/2;
   y = _fsin(x);

   printf("The sine of %lf is %lf\n", x, y);
)


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _fasin - Calculate Arcsine
o _fcossin - Calculate Cosine and Sine
o _fsincos - Calculate Sine and Cosine
o sin  - Calculate Sine
o sinh  - Calculate Hyperbolic Sine


ΓòÉΓòÉΓòÉ 6.100. _fsincos - Calculate Sine and Cosine ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <builtin.h>

double _fsincos(double x, double *y);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _fsincos function calculates the sine of x, and stores the cosine in *y.
This operation is faster than separately calculating the sine and cosine. Use
_fsincos instead of _fcossin when you will be using the sine first, and then
the cosine.

Because it is a built-in function and has no backing code in the library:

o You cannot take the address of _fsincos.
o You cannot parenthesize a _fsincos function call because parentheses specify
  a call to the backing code for the function.

This function returns the sine of x.

Example of _fsincos


ΓòÉΓòÉΓòÉ <hidden> Example of _fsincos ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example calculates the sine of x and stores the cosine of x in y.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>
#include <builtin.h>
#define MAX  1.0
#define MIN -1.0

int main(void)
  {
  double x,y;

  printf( "Enter x\n" );
  scanf( "%lf", &x );

  /* Output error if not in range */
  if ( x > MAX )
    printf( "Error: %lf too large for sine\n", x );
  else if ( x < MIN )
    printf( "Error: %lf too small for sine\n", x );
  else
    {
    z = _fsincos( x, *y);
    printf("The sine of %d is %lf\n", x, z);
    printf("The cosine of %d is %lf\n", x, *y);
    }
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o acos  - Calculate Arccosine
o asin  - Calculate Arcsine
o cos  - Calculate Cosine
o cosh  - Calculate Hyperbolic Cosine
o _facos - Calculate Arccosine
o _fasin - Calculate Arcsine
o _fcos - Calculate Cosine
o _fcossin - Calculate Cosine and Sine
o _fsin - Calculate Sine
o sin  - Calculate Sine
o sinh  - Calculate Hyperbolic Sine


ΓòÉΓòÉΓòÉ 6.101. _fsqrt -  Calculate Square Root ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h>

double _fsqrt(double x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _fsqrt function computes the square root of x using the FSQRT 80387
instruction. Note that this function does not set errno as the sqrt function
does. If you pass a negative value to this function, an exception is generated.

This function returns the value of the square root of x.

Example of _fsqrt


ΓòÉΓòÉΓòÉ <hidden> Example of _fsqrt ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example calculates the square root of 4.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <math.h>

int main(void)
   {
    double x, y;
    x = 4;

    y = _fsqrt( x );

    printf("The square root of %d is %d.\n", x, y);
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o sqrt  - Calculate Square Root


ΓòÉΓòÉΓòÉ 6.102. _fstat - Information about Open File ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <sys\stat.h>
#include <sys\types.h>

int _fstat(int handle, struct stat *buffer);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _fstat function obtains information about the open file associated with the
given handle and stores it in the structure to which buffer points.  The
<sys\stat.h> include file defines the stat structure.  The stat structure
contains the following fields:

Field       Value
st_mode     Bit mask for file mode information. The _fstat function sets the
            S_IFCHR bit if handle refers to a device. The S_IFDIR bit is set if
            pathname specifies a directory. It sets the S_IFREG bit if handle
            refers to an ordinary file.  It sets user read/write bits according
            to the permission mode of the file.  The other bits have undefined
            values.

                                  F E D C B A 9 8 7 6 5 4 3 2 1 0
                                  Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöé
                                  ΓööΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓöÿ

                            S_IFREGΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Γöé Γöé     Γöé Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇexecute/search permission,
                        (regular file)     Γöé Γöé     Γöé Γöé     owner (S_IEXEC)
                            S_IFDIRΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Γöé     Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇwrite permission, owner
                            S_IFCHRΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ     ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇread permission, owner

st_dev      Drive number of the disk containing the file.
st_rdev     Drive number of the disk containing the file (same as st_dev).
st_nlink    Always 1.
st_size     Size of the file in bytes.
st_atime    Time of last modification of file.
st_mtime    Same as st_atime if not provided by the file system.
st_ctime    Same as st_atime if not provided by the file system.

There are three additional fields in the fstat structure for portability to
other operating systems; they have no meaning under the OS/2 operating system.

Note:  If the given handle refers to a device, the size and time fields in the
fstat structure are not meaningful.

The _fstat function returns the value 0 if it obtains the file status
information.  A return value of -1 indicates an error;  in this case, _fstat
sets errno to EBADF, showing an incorrect file handle.

Example of _fstat


ΓòÉΓòÉΓòÉ <hidden> Example of _fstat ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example uses _fstat to report the size of a file named data.

                                                                        *
************************************************************************/

#include <time.h>
#include <sys\types.h>
#include <sys\stat.h>
#include <stdio.h>

int main(void)
{
    struct stat buf;
    FILE *fp;
    int fh, result;
    char *buffer = "A line to output";

    fp = fopen("data", "w+");
    fprintf(fp, "%s", buffer);
    fflush(fp);
    fclose(fp);

    fp = fopen("data", "r");
    if (_fstat(_fileno(fp), &buf) == 0)
    {
        printf("file size is %ld\n", buf.st_size);
        printf("time modified is %s\n", ctime(&buf.st_atime));
    }
    else
        printf("Bad file handle\n");

    fclose(fp);

    return 0;


/**************  The output should be similar to:  **********************

   file size is 16
   time modified is Tue March 30 16:08:14 1993
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _stat - Get Information about File or Directory
o sys\stat.h
o sys\types.h


ΓòÉΓòÉΓòÉ 6.103. ftell  - Get Current Position ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

long int ftell(FILE *stream);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The ftell function returns a value indicating the current position of the file
associated with stream. For a fixed-length binary file, the value returned by
ftell is an offset relative to the beginning of the stream.

On error, ftell returns -1L and sets errno to a nonzero value.

Example of ftell


ΓòÉΓòÉΓòÉ <hidden> Example of ftell ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example opens the file myfile for reading. It reads enough characters to
fill half of the buffer and prints out the position in the stream and the
buffer.

                                                                        *
************************************************************************/

#include <stdio.h>

#define NUM_ALPHA  26
#define NUM_CHAR    6

int main(void)
{
  FILE * stream;
  int i;
  char ch;

  char buffer[NUM_ALPHA];
  long position;

  if (( stream = fopen("myfile.dat", "r")) != NULL )
  {
    /* read into buffer */
    for ( i = 0; ( i < NUM_ALPHA/2 ) &&
           ((buffer[i] = fgetc(stream)) != EOF ); ++i )
        if (i==NUM_CHAR-1)  /* We want to be able to position the   */
                            /* file pointer to the character in     */
                            /* position NUM_CHAR                    */
           position = ftell(stream);

    buffer[i] = '\0';

    fseek (stream, position, SEEK_SET);
    ch = fgetc (stream);  /* get the character at position NUM_CHAR    */

    fclose( stream );
  }
  else
    perror( "Error opening myfile" );

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fseek  - Reposition File Position
o fgetpos  - Get File Position
o fopen  - Open Files
o fsetpos  - Set File Position
o stdio.h


ΓòÉΓòÉΓòÉ 6.104. _ftime - Store Current Time ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <sys\timeb.h>
#include <sys\types.h>

void _ftime(struct timeb *timeptr);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _ftime function gets the current time and stores it in the structure to
which timeptr points.  The <sys\timeb.h> include file contains the definition
of the timeb structure.  It contains four fields:  time, millitm, timezone, and
dstflag.

The time field gives the time in seconds since 00:00:00 Coordinated Universal
Time, January 1, 1970.  The millitm field gives the fraction of a second, in
milliseconds. The timezone field gives the difference in minutes between
Coordinated Universal Time and local time, going from east to west.  The _ftime
function sets the value of timezone from the value of the global variable
_timezone. The dstflag is nonzero if daylight saving time is currently in
effect for the local time zone.  For an explanation of how daylight saving time
is determined, see _tzset - Assign Values to Locale Information.

There is no return value.

Example of _ftime


ΓòÉΓòÉΓòÉ <hidden> Example of _ftime ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example polls the system clock, converts the current time to a character
string, prints the string, and saves the time data in the structure timebuffer:

                                                                        *
************************************************************************/

#include <sys\types.h>
#include <sys\timeb.h>
#include <stdio.h>
#include <time.h>

int main(void)
{
    struct timeb timebuffer;

    _ftime(&timebuffer);
    printf("the time is %s\n", ctime(&(timebuffer.time)));

    return 0;

/**************  The output should be similar to:  **********************

   the time is Tue March 30 16:08:17 1993
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o asctime  - Convert Time
o ctime  - Convert Time
o gmtime  - Convert Time
o localtime  - Convert Time
o mktime  - Convert Local Time
o time  - Determine Current Time
o _tzset - Assign Values to Locale Information
o sys\timeb.h
o sys\types.h


ΓòÉΓòÉΓòÉ 6.105. _fullpath - Get Full Path Name of Partial Path ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

char *_fullpath(char *pathbuf, char *partialpath, size_t n);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _fullpath function gets the full path name of the given partial path name
partialpath, and stores it in pathbuf. The integer argument n specifies the
maximum length for the path name.  An error occurs if the length of the path
name, including the terminating null character, exceeds n characters.

If the pathbuf argument is NULL, _fullpath uses malloc to allocate a buffer of
size _MAX_PATH bytes to store the path name.

The _fullpath function returns a pointer to pathbuf.  If an error occurs,
_fullpath returns NULL and sets errno to one of the following values:

Value          Meaning
ENOMEM         Unable to allocate storage for the buffer.
ERANGE         The path name is longer than n characters.
EOS2ERR        A system error occurred.  Check _doserrno for the specific OS/2
               error code.

Example of _fullpath


ΓòÉΓòÉΓòÉ <hidden> Example of _fullpath ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example uses _fullpath to get and store the full path name of the current
directory.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>
#include <errno.h>

int main(void)
{
    char *retBuffer;

    retBuffer = _fullpath(NULL, ".", 0);
    if ( retBuffer == NULL )
       printf("An error has occurred, errno is set to %d.\n", errno);
    else
       printf("Full path name of current directory is %s.\n", retBuffer);

    return 0;

    /* If path of current directory is D:\BIN, the expected output is:

       Full path name of current directory is D:\BIN.                  */
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _getcwd - Get Path Name of Current Directory
o _getdcwd - Get Full Path Name of Current Directory
o _makepath - Create Path
o malloc  - Reserve Storage Block
o _splitpath - Decompose Path Name
o stdlib.h


ΓòÉΓòÉΓòÉ 6.106. fwrite  - Write Items ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

size_t fwrite(const void *buffer, size_t size, size_t count,
                 FILE *stream);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The fwrite function writes up to count items of size length from buffer to the
output stream.

The fwrite function returns the number of full items successfully written,
which can be less than count if an error occurs.

Example of fwrite


ΓòÉΓòÉΓòÉ <hidden> Example of fwrite ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example writes NUM long integers to a stream in binary format.

                                                                        *
************************************************************************/

#include <stdio.h>

#define  NUM  100

int main(void)
{
   FILE *stream;
   long list[NUM];
   int numwritten;

   stream = fopen("myfile.dat", "w+b");
      .
      .  /* assign values to list[] */
      .
   numwritten = fwrite(list, sizeof(long), NUM, stream);
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fopen  - Open Files
o fread  - Read Items
o _read - Read Into Buffer
o stdio.h
o _write - Writes from Buffer to File


ΓòÉΓòÉΓòÉ 6.107. _fyl2x - Calculate y * log2(x) ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <builtin.h>

double _fyl2x(double x, double y);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _fyl2x function computes the base-2 logarithm of x and multiplies it by y
(y * log2(x)). The variable x cannot be negative. This instruction is designed
with a built-in multiplication to optimize the calculation of logarithms with
arbitrary positive base: log b (x) = (log2(b)**-1) * log2(x)

Because it is a built-in function and has no backing code in the library:

o You cannot take the address of _fyl2x.
o You cannot parenthesize a _fyl2x function call, because parentheses specify a
  call to the backing code for the function in the library.

This function returns the result of the formula y * log2(x)

Example of _fyl2x


ΓòÉΓòÉΓòÉ <hidden> Example of _fyl2x ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example calculates (y * log2(x)), after prompting the user for values of x
and y.

                                                                        *
************************************************************************/

#include<stdio.h>
#include<math.h>
#include<builtin.h>

int main(void)
    {
    double x,y,z;

    printf("Enter a value for x, then a value for y: \n",);
    scanf("%d, %d", &x, 0x);

    z = _fyl2x(x,y);

    printf("%d * log2(%d) is %d.\n", x,y,z);
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _fyl2xp1 -  Calculate y * log2(x + 1)
o _f2xm1 -  Calculate (2**x) - 1
o builtin.h


ΓòÉΓòÉΓòÉ 6.108. _fyl2xp1 -  Calculate y * log2(x + 1) ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <builtin.h>

double _fyl2xp1(double x, double y);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _fyl2x function computes the base-2 logarithm of x+1 and multiplies it by y
(y * log2(x+1)). The variable x must be in the range -(1-(sqrt(2)/2)) to
(sqrt(2) - 1). This function provides improved accuracy over the _fyl2x
function when computing logarithms of numbers very close to 1. When x is small,
you can retain more significant digits by providing x to the _fyl2xp1 function
than by providing x+1 as an argument to the _fyl2x function.

Because it is a built-in function and has no backing code in the library:

o You cannot take the address of _fyl2xp1.
o You cannot parenthesize a _fyl2xp1 function call, because parentheses specify
  a call to the backing code for the function in the library.

This function returns the result of the formula y * log2(x+1).

Example of _fyl2xp1


ΓòÉΓòÉΓòÉ <hidden> Example of _fyl2xp1 ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example calculates (y * log2(x + 1)), after prompting the user for values
of x and y.

                                                                        *
************************************************************************/

#include<stdio.h>
#include<math.h>
#include<builtin.h>

int main(void)
    {
    double x,y,z;

    printf("Enter a value for x, then a value for y: \n",);
    scanf("%d, %d", &x, 0x);

    z = _fyl2xp1(x,y);

    printf("%d * log2(%d + 1) is %d.\n", x,y,z);
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _fyl2x - Calculate y * log2(x)
o _f2xm1 -  Calculate (2**x) - 1
o builtin.h


ΓòÉΓòÉΓòÉ 6.109. _f2xm1 -  Calculate (2**x) - 1 ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <builtin.h>

double _f2xm1(double x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _f2xm1 function calculates 2 raised to the power of x, minus 1 ((2**x)-1).
The variable x must be in the range -1 to 1. This instruction is designed to
produce very accurate results when x is close to 0. Large errors may occur for
operands with magnitudes close to 1. You can exponentiate values other than 2
by using the formula x**y = 2**(y * log2(x)).

Because it is a built-in function and has no backing code in the library:

o You cannot take the address of _f2xm1.
o You cannot parenthesize a _f2xm1 function call, because parentheses specify a
  call to the backing code for the function in the library.

This function returns the value of the formula (2**x)-1.

Example of _f2xm1


ΓòÉΓòÉΓòÉ <hidden> Example of _f2xm1 ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example calculates (2**x)-1 after prompting the user for a value for x.

                                                                        *
************************************************************************/

#include<stdio.h>
#include<math.h>
#include<builtin.h>

int main(void)
    {
    double x,y;

    printf("Enter a value for x: \n",);
    scanf("%d", &x);

    y = _f2xm1(x);

    printf("2**x - 1 is %d.\n", y);
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _fyl2x - Calculate y * log2(x)
o _fyl2xp1 -  Calculate y * log2(x + 1)
o builtin.h


ΓòÉΓòÉΓòÉ 6.110. gamma  - Gamma Function ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h> /* SAA extension to ANSI */

double gamma(double x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: SAA

The gamma function computes ln( |G(x)| ). The argument x must be a positive
real value. If x is a negative value, errno is set to EDOM.  If the result
causes an overflow, the function returns HUGE_VAL and sets errno to ERANGE.

The C/C++ Tools compiler allows x to be a negative integer.

Example of gamma


ΓòÉΓòÉΓòÉ <hidden> Example of gamma ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses gamma to calculate ln(|G(x)|), where x = 42.

                                                                        *
************************************************************************/

#include <math.h>
#include <stdio.h>

int main(void)
{
   double x=42, g_at_x;

   g_at_x = exp(gamma(x));       /* g_at_x = 3.345253e+49 */
   printf ("The value of G(%4.2lf) is %7.2e\n", x, g_at_x);
}

/************************  Output should be similar to:  **********

The value of G(42.00) is 3.35e+49
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Bessel Functions
o erf  - Calculate Error Functions
o math.h


ΓòÉΓòÉΓòÉ 6.111. _gcvt - Convert Floating-Point to String ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

char *_gcvt(double value, int ndec, char *buffer);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _gcvt function converts a floating-point value to a character string
pointed to by buffer. The buffer should be large enough to hold the converted
value and a null character (\0), that _gcvt automatically adds to the end of
the string. There is no provision for overflow.

The _gcvt function tries to produce ndec significant digits in FORTRAN F
format. Failing that, it produces ndec significant digits in FORTRAN E format.
Trailing zeros might be suppressed in the conversion if they are significant.

A FORTRAN F number has the following format:

       ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ    ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
 ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇdigitΓöÇΓö┤ΓöÇΓöÇΓöÇ.ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
   Γö£ΓöÇΓöÇ+ΓöÇΓöÇΓöñ          ΓööΓöÇdigitΓöÇΓöÿ
   ΓööΓöÇΓöÇ-ΓöÇΓöÇΓöÿ

A FORTRAN E number has the following format:

            ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ          ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
 ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇdigitsΓöÇΓöÇ.ΓöÇΓöÇdigitsΓöÇΓö┤ΓöÇEΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇdigitsΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γö┤ΓöÇ
  Γö£ΓöÇΓöÇ+ΓöÇΓöÇΓöñ             Γö£ΓöÇΓöÇ+ΓöÇΓöÇΓöñ     ΓööΓöÇdigitsΓöÇΓöÿ
  ΓööΓöÇΓöÇ-ΓöÇΓöÇΓöÿ             ΓööΓöÇΓöÇ-ΓöÇΓöÇΓöÿ

The _gcvt function also converts NaN and infinity values to the strings NAN and
INFINITY, respectively. For more information on NaN and infinity values, see
Infinity and NaN Support.

Warning: For each thread, the _ecvt, _fcvt and _gcvt functions use a single,
dynamically allocated buffer for the conversion. Any subsequent call that the
same thread makes to these functions destroys the result of the previous call.

The _gcvt function returns a pointer to the string of digits. A failure to
allocate memory returns an empty string and sets errno to ENOMEM.

Example of _gcvt


ΓòÉΓòÉΓòÉ <hidden> Example of _gcvt ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example converts the value -3.1415e3 to a character string and places it
in the character array buffer1. It then converts the macro value _INF to a
character string and places it in buffer2.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>
#include <float.h>    /* for the definition of _INF */

int main(void)
{
    char buffer1[10], buffer2[10];

    _gcvt(-3.1415e3, 7, buffer1);
    printf("The first result is %s \n", buffer1);

    _gcvt(_INF, 5, buffer2);
    printf("The second result is %s \n", buffer2);

    return 0;

    /* The expected output is:

       The first result is -3141.5
       The second result is INFINITY */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _ecvt - Convert Floating-Point to Character
o _fcvt - Convert Floating-Point to String
o Infinity and NaN Support
o stdlib.h


ΓòÉΓòÉΓòÉ 6.112. getc  - Read a Character ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int getc(FILE *stream);

int getchar(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The getc function reads a single character from the current stream position and
advances the stream position to the next character.  The getchar function is
identical to getc(stdin).

The difference between the getc and the fgetc functions is that the getc
function can be implemented so that its arguments can be evaluated multiple
times.  The stream argument to getc should not be an expression with side
effects.

The getc and getchar functions return the character read.  A return value of
EOF indicates an error or end-of-file condition.  Use ferror or feof to
determine whether an error or an end-of-file condition occurred.

Example of getc - getchar


ΓòÉΓòÉΓòÉ <hidden> Example of getc - getchar ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example gets a line of input from the stdin stream.  You can also use
getc(stdin) instead of getchar() in the for statement to get a line of input
from stdin.

                                                                        *
************************************************************************/

#include <stdio.h>

#define LINE 80

int main(void)
{
  char buffer[LINE+1];
  int i;
  int ch;

  printf( "Please enter string\n" );

  /* Keep reading until either:
     1. the length of LINE is exceeded  or
     2. the input character is EOF  or
     3. the input character is a new-line character
   */

  for ( i = 0; ( i < LINE ) && (( ch = getchar()) != EOF) &&
               ( ch !='\n' ); ++i )
    buffer[i] = ch;

  buffer[i] = '\0';  /* a string should always end with '\0' ! */

  printf( "The string is %s\n", buffer );
}

/************************  Output should be similar to:  **********

Please enter string
hello world
The string is hello world
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fgetc  - Read a Character
o _fgetchar - Read Single Character from stdin
o _getch - _getche - Read Character from Keyboard
o putc - putchar  - Write a Character
o ungetc  - Push Character onto Input Stream
o gets  - Read a Line
o stdio.h


ΓòÉΓòÉΓòÉ 6.113. _getch - _getche - Read Character from Keyboard ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <conio.h>

int _getch(void);

int _getche(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _getch function reads a single character from the keyboard, without
echoing.  The _getche function reads a single character from the keyboard and
displays the character read. Neither function can be used to read Ctrl-Break.

When a program is reading a function key or cursor-moving key, the _getch and
_getche functions must be called twice.  The first call returns 0 or E0H, and
the second call returns the particular extended key code.

Example of _getch - _getche


ΓòÉΓòÉΓòÉ <hidden> Example of _getch - _getche ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example gets characters from the keyboard until it finds the character
'x'.

                                                                        *
************************************************************************/

#include <conio.h>
#include <stdio.h>

int main(void)
{
   int ch;

   _cprintf("\nType in some letters.");
   printf("\n");
   _cprintf("If you type in an 'x', the program ends.\n");
   printf("\n");

   for(;;)
   {
      ch = _getch();

      if (ch == 'x')
      {
         _ungetch(ch);
         break;
      }
      _putch(ch);
   }

   ch=_getch();

   printf("\n");
   _cprintf("\nThe last character was '%c'.", ch);

   return 0;

/**************  The output should be similar to:  **********************

   Type in some letters.
   If you type in an 'x', the program ends.

   One Two Three Four Five Si

   The last character was 'x'.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _cgets - Read String of Characters from Keyboard
o fgetc  - Read a Character
o getc  - Read a Character
o _putch - Write Character to Screen
o _ungetch - Push Character Back to Keyboard
o conio.h


ΓòÉΓòÉΓòÉ 6.114. _getcwd - Get Path Name of Current Directory ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <direct.h>

char *_getcwd(char *pathbuf, int n);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _getcwd function gets the full path name of the current working directory
and stores it in the buffer pointed to by pathbuf.  The integer argument n
specifies the maximum length for the path name.  An error occurs if the length
of the path name, including the terminating null character, exceeds n
characters.

If the pathbuf argument is NULL, _getcwd uses malloc to reserve a buffer of at
least n bytes to store the path name.  If the current working directory string
is more than n bytes, a large enough buffer will be allocated to contain the
string.  You can later free this buffer using the _getcwd return value as the
argument to free.

The _getcwd function returns pathbuf.  If an error occurs, _getcwd returns NULL
and sets errno to one of the following values:

Value       Meaning
ENOMEM      Not enough storage space available to reserve n bytes (when pathbuf
            argument is NULL).
ERANGE      The path name is longer than n characters.
EOS2ERR     An OS/2 call failed. Use _doserrno to obtain more information about
            the return code.

Example of _getcwd


ΓòÉΓòÉΓòÉ <hidden> Example of _getcwd ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example stores the name of the current working directory (up to _MAX_PATH
characters) in a buffer.  The value of _MAX_PATH is defined in <stdlib.h>.

                                                                        *
************************************************************************/

#include <direct.h>
#include <stdio.h>
#include <stdlib.h>

int main(void)
{
    char buffer[_MAX_PATH];

    if (_getcwd(buffer, _MAX_PATH) == NULL)
       perror("getcwd error");

    printf("The current directory is %s\n", buffer);

    return 0;

/****************  The output should be similar to:  ********************

   The current directory is E:\C_OS2\MIG_XMPS
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _chdir - Change Current Working Directory
o _fullpath - Get Full Path Name of Partial Path
o _getdcwd - Get Full Path Name of Current Directory
o _getdrive - Get Current Working Drive
o malloc  - Reserve Storage Block
o direct.h


ΓòÉΓòÉΓòÉ 6.115. _getdcwd - Get Full Path Name of Current Directory ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <direct.h>

char *_getdcwd(int drive, char *pathbuf, int n);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _getdcwd function gets the full path name for the current directory of the
specified drive, and stores it in the location pointed to by pathbuf. The drive
argument is an integer value representing the drive (A: is 1, B: is 2, and so
on).

The integer argument n specifies the maximum length for the path name. An error
occurs if the length of the path name, including the terminating null
character, exceeds n characters.

If the pathbuf argument is NULL, _getdcwd uses malloc to reserve a buffer of at
least n bytes to store the path name.  If the current working directory string
is more than n bytes, a large enough buffer will be allocated to contain the
string. You can later free this buffer using the _getdcwd return value as the
argument to free.

An alternative to this function is the DosQueryCurrentDir and
DosQueryCurrentDisk API calls.

The _getdcwd function returns pathbuf.  If an error occurs, _getdcwd returns
NULL and sets errno to one of the following values:

Value          Meaning
ENOMEM         Not enough storage space available to reserve n bytes (when
               pathbuf argument is NULL).
ERANGE         The path name is longer than n characters.
EOS2ERR        An OS/2 call failed. Use _doserrno to obtain more information
               about the return code.

Example of _getcwd


ΓòÉΓòÉΓòÉ <hidden> Example of _getcwd ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example uses _getdcwd to obtain the current working directory of drive C.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <direct.h>
#include <errno.h>

int main(void)
{
    char *retBuffer;

    retBuffer = _getdcwd(3,NULL,0);
    if ( retBuffer == NULL )
       printf("An error has occurred, errno is set to %d.\n",
               errno);
    else
       printf("Current working directory of drive C is %s.\n",
               retBuffer);

    return 0;


/***************  The output should be similar to:  *********************

    Current working directory of drive C is C:\.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _chdir - Change Current Working Directory
o _chdrive - Change Current Working Drive
o _fullpath - Get Full Path Name of Partial Path
o _getcwd - Get Path Name of Current Directory
o _getdrive - Get Current Working Drive
o malloc  - Reserve Storage Block
o direct.h


ΓòÉΓòÉΓòÉ 6.116. _getdrive - Get Current Working Drive ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <direct.h>

int _getdrive(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

Gets the drive number for the current working drive.

The _getdrive function returns an integer corresponding to alphabetical
position of the letter representing the current working drive. For example, A:
is 1, B: is 2, J: is 10, and so on.

An alternative to this function is the DosQueryCurrentDisk API call.

Example of _getdrive


ΓòÉΓòÉΓòÉ <hidden> Example of _getdrive ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example gets and prints the current working drive number.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <direct.h>

int main(void)
{
   printf("Current working drive is %d.\n", _getdrive() );

    return 0;

/********  If the current working drive is E:, then  **************
***************  the output should be similar to:  **********************

   Current working drive is 5.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _chdir - Change Current Working Directory
o _chdrive - Change Current Working Drive
o _getcwd - Get Path Name of Current Directory
o _getdcwd - Get Full Path Name of Current Directory
o direct.h


ΓòÉΓòÉΓòÉ 6.117. getenv  - Search for Environment Variables ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

char *getenv(const char *varname);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The getenv function searches the list of environment variables for an entry
corresponding to varname.

The getenv function returns a pointer to the environment table entry containing
the current string value of varname.  The return value is NULL if the given
variable is not currently defined or if the system does not support environment
variables.

You should copy the string that is returned because it may be written over by a
subsequent call to getenv.

Example of getenv


ΓòÉΓòÉΓòÉ <hidden> Example of getenv ΓòÉΓòÉΓòÉ

/************************************************************************
*

In this example, pathvar points to the value of the PATH environment variable:

                                                                        *
************************************************************************/

#include <stdlib.h>

int main(void)
{
   char *pathvar;

   pathvar = getenv("PATH");
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _putenv - Modify Environment Variables
o envp Parameter to main
o stdlib.h


ΓòÉΓòÉΓòÉ 6.118. _getpid - Get Process Identifier ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <process.h>

int _getpid(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _getpid function gets the process identifier that uniquely identifies the
calling process.

The _getpid function returns the process identifier as an integer value.  There
is no error return value.

Example of _getpid


ΓòÉΓòÉΓòÉ <hidden> Example of _getpid ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example prints the process identifier:

                                                                        *
************************************************************************/

#include <process.h>
#include <string.h>
#include <stdio.h>
#include <stdlib.h>

int main(void)
{
    printf("Process identifier is %d\n", _getpid());

    return 0;

/****************  The output should be similar to:  ********************

   Process identifier is 242
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _cwait - Wait for Child Process
o _execl - _execvp - Load and Run Child Process
o _spawnl -_spawnvpe -Start and Run Child Processes
o _wait - Wait for Child Process
o process.h


ΓòÉΓòÉΓòÉ 6.119. gets  - Read a Line ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

char *gets(char *buffer);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The gets function reads a line from the standard input stream stdin and stores
it in buffer.  The line consists of all characters up to and including the
first new-line character (\n) or EOF. The gets function then replaces the
new-line character, if read, with a null character (\0), before returning the
line.

If successful, the gets function returns its argument.  A NULL pointer return
value indicates an error or an end-of-file condition with no characters read.
Use ferror or feof to determine which of these conditions occurred. If there is
an error, the value stored in buffer is undefined.  If an end-of-file condition
occurs, buffer is not changed.

Example of gets


ΓòÉΓòÉΓòÉ <hidden> Example of gets ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example gets a line of input from stdin.

                                                                        *
************************************************************************/

#include <stdio.h>

#define MAX_LINE 100

int main(void)
{
   char line[MAX_LINE];
   char *result;

   if ((result = gets(line)) != NULL)
   {
      if (ferror(stdin))
        perror("Error");
   }
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _cgets - Read String of Characters from Keyboard
o fgets  - Read a String
o feof  - Test End-of-File Indicator
o ferror  - Test for Read/Write Errors
o fputs  - Print Strings
o getc  - Read a Character
o puts  - Write a String
o stdio.h


ΓòÉΓòÉΓòÉ 6.120. _getTIBvalue - Get TIB Value ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <builtin.h>

unsigned long _getTIBvalue(const unsigned int offset);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _getTIBvalue function retrieves an unsigned long value from the thread
information block (TIB) at the offset specified. The selector value for the TIB
belonging to the current thread of execution is stored in the FS segment
register. You should use the offsetof macro to calculate offset.

Because it is a built-in function and has no backing code in the library:

o You cannot take the address of _getTIBvalue.
o You cannot parenthesize a _getTIBvalue function call, because parentheses
  specify a call to the backing code for the function.

This function returns an unsigned long value.  There is no error return value
and this function does not set errno.  If offset is too large, it will cause an
access violation when running the program.

Example of _getTIBvalue


ΓòÉΓòÉΓòÉ <hidden> Example of _getTIBvalue ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example prints out all the values in the TIB structure.

                                                                        *
************************************************************************/

#define INCL_DOSPROCESS
#include <os2.h>
#include <stdio.h>
#include <builtin.h>

int main( void )
{
   printf( "Values in Thread Information Block are:\n\n" );

   printf( "Exception chain pointer: %lx\n",
           _getTIBvalue( offsetof( TIB, tib_pexchain ) ) );
   printf( "Base stack address: %lx\n",
           _getTIBvalue( offsetof( TIB, tib_pstack ) ) );
   printf( "End of stack address: %lx\n",
           _getTIBvalue( offsetof( TIB, tib_pstacklimit ) ) );
   printf( "System specific TIB pointer: %p\n",
           _getTIBvalue( offsetof( TIB, tib_ptib2 ) ) );
   printf( "Version number: %lu\n",
           _getTIBvalue( offsetof( TIB, tib_version ) ) );
   printf( "Ordinal number: %lu\n",
           _getTIBvalue( offsetof( TIB, tib_ordinal ) ) );

   return 0;
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _threadstore - Access Thread-Specific Storage

o builtin.h


ΓòÉΓòÉΓòÉ 6.121. gmtime  - Convert Time ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <time.h>

struct tm *gmtime(const time_t *time);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The gmtime function converts a time value to a struct tm.  The value time is
usually obtained from a call to time.

The gmtime function breaks down the time value and stores it in a tm structure,
defined in time.h.  The structure pointed to by the return value reflects
Coordinated Universal Time, not local time.

The fields of the tm structure include:

Field            Value Stored
tm_sec           Seconds (0-61)
tm_min           Minutes (0-59)
tm_hour          Hours (0-23)
tm_mday          Day of month (1-31)
tm_mon           Month (0-11;  January = 0)
tm_year          Year (current year minus 1900)
tm_wday          Day of week (0-6;  Sunday = 0)
tm_yday          Day of year (0-365;  January 1 = 0)
tm_isdst         Zero if Daylight Saving Time is not in effect;  positive if
                 Daylight Saving Time is in effect;  negative if the
                 information is not available.

The gmtime function returns a pointer to the structure result.  The gmtime
function returns NULL if Coordinated Universal Time is not available.

Note:

 1. The range (0-61) for tm_sec allows for as many as two leap seconds.

 2. The gmtime and localtime functions may use a common, statically allocated
    buffer for the conversion. Each call to one of these functions may alter
    the result of the previous call.

 3. The time and date functions begin at 00:00:00 Coordinated Universal Time,
    January 1, 1970.

Example of gmtime


ΓòÉΓòÉΓòÉ <hidden> Example of gmtime ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses the gmtime function to adjust a time_t representation to a
Coordinated Universal Time character string and then converts it to a printable
string using asctime.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <time.h>

int main(void)
{
   time_t ltime;

   time(<ime);
   printf ("Coordinated Universal Time is %s\n",
            asctime(gmtime(<ime)));
}

/************************  Output should be similar to:  **********

Coordinated Universal Time is Wed Aug 18 21:01:44 1993
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o asctime  - Convert Time
o ctime  - Convert Time
o localtime  - Convert Time
o mktime  - Convert Local Time
o time  - Determine Current Time
o time.h


ΓòÉΓòÉΓòÉ 6.122. _heap_check - Validate Run-Time Storage Heap ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#define __DEBUG_ALLOC__
#include <stdlib.h>  /* also defined in <malloc.h> */

void *_heap_check(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

The _heap_check function checks all memory blocks allocated or freed by the
debug memory management functions to make sure that overwriting has not
occurred outside the bounds of allocated blocks and that free memory blocks
have not been overwritten.

The _heap_check function is automatically called whenever a debug function is
called.  You can also explicitly call _heap_check.

Note:  You should place calls to the _heap_check function throughout your code,
especially in areas that may cause memory problems.

There is no return value.

For an explanation of how to interpret the output from _heap_check, see Sample
_heap_check Output.

Example of _heap_check


ΓòÉΓòÉΓòÉ <hidden> Example of _heap_check ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example allocates 5000 bytes of storage, and then attempts to write to
storage that was not allocated. The call to _heap_check detects the error,
generates several messages, and stops the program.

                                                                        *
************************************************************************/

#ifndef __DEBUG_ALLOC__      /* this macro could also be defined */
   #define __DEBUG_ALLOC__   /*      from the command line       */
#endif
#include <stdlib.h>
#include <stdio.h>

int main(void)
{
   char *ptr;

   if (( ptr = malloc(5000) ) == NULL)
   {
      printf("Could not allocate memory block.\n");
      return EXIT_FAILURE;
   }

   *(ptr - 1) = 'a';    /* overwrites storage that was not allocated */
   _heap_check();

   printf("_heap_check did not detect that a memory block was overwritten.\n");

   return EXIT_FAILURE;

   /* Possible output is:

      Memory was overwritten before the allocated memory block that starts
            at address 0x00150010.
      The first eight bytes of the memory block (in hex) are: 0000000000000000.
      This memory block was (re)allocated at line number 11 in THPCHK.C.        */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _debug_calloc - Reserve and Initialize Storage
o _debug_free - Release Storage Blocks
o _debug_heapmin - Release Unused Memory in the Heap
o _debug_malloc - Reserve Storage Blocks
o _debug_realloc - Change Reserved Storage Block Size
o _dump_allocated - Get Information about Allocated Storage
o Using the Debug Memory Management Functions
o malloc.h
o stdlib.h


ΓòÉΓòÉΓòÉ 6.123. _heapmin - Release Unused Memory in the Heap ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>  /* also defined in <malloc.h> */

int _heapmin(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _heapmin function returns all unused memory from the runtime heap to the
operating system.

If successful, _heapmin returns 0; if not, it returns -1.

Example of _heapmin


ΓòÉΓòÉΓòÉ <hidden> Example of _heapmin ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example shows how to use the _heapmin function.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
   if ( _heapmin() )
      printf("_heapmin failed.\n");
   else
      printf("_heapmin was successful.\n");

   return 0;

   /* The expected output is:

      _heapmin was successful. */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _debug_heapmin - Release Unused Memory in the Heap
o malloc.h
o stdlib.h


ΓòÉΓòÉΓòÉ 6.124. hypot  - Calculate Hypotenuse ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h> /* SAA extension to ANSI */

double hypot(double side1, double side2);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: SAA

The hypot function calculates the length of the hypotenuse of a right-angled
triangle based on the lengths of two sides side1 and side2.  A call to hypot is
equal to:

   sqrt(side1 * side1 + side2 * side2);

The hypot function returns the length of the hypotenuse.  If an overflow
results, the function sets errno to ERANGE and returns the value HUGE_VAL.

Example of hypot


ΓòÉΓòÉΓòÉ <hidden> Example of hypot ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example calculates the hypotenuse of a right-angled triangle with sides of
3.0 and 4.0.

                                                                        *
************************************************************************/

#include <math.h>

int main(void)
{
   double x, y, z;

   x = 3.0;
   y = 4.0;
   z = hypot(x,y);

   printf("The hypotenuse of the triangle with sides %lf and %lf"
          " is %lf\n", x, y, z);
}

/********************  Output should be similar to:  **************

The hypotenuse of the triangle with sides 3.000000 and 4.000000 is 5.000000
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _fsqrt -  Calculate Square Root
o sqrt  - Calculate Square Root
o math.h


ΓòÉΓòÉΓòÉ 6.125. _inp - Read Byte from Input Port ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <conio.h>              /*  Declared in both  */
#include <builtin.h>

int _inp(const unsigned int port);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _inp function reads a byte from the specified input port. The port number
must be an unsigned int value in the range 0 to 65 535 inclusive.

Because it is a built-in function and has no backing code in the library:

o You cannot take the address of _inp.
o You cannot parenthesize an _inp function call, because parentheses specify a
  call to the backing code for the function.

You can run code containing this function only at ring zero. Otherwise, an
invalid instruction exception is generated.

The _inp function returns the byte value as an integer that was read from the
specified port. There is no error return value and this function does not set
errno.

Example of _inp


ΓòÉΓòÉΓòÉ <hidden> Example of _inp ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses the _inp function to read a byte from a specified input port
and return the data read.

                                                                        *
************************************************************************/

#include <builtin.h>
#define LOWER 0
#define UPPER 65535

int Add1(int j);
int g;
enum fruit {apples=10, bananas, cantalopes};
int arr[]={cantalopes, bananas, apples};

struct
   {
   int i;
   char ch;
   } st;

int main(void)
   {
   int i;
   volatile const int c = 0;

   i = _inp(0);

   g = _inp(LOWER + 1);    /* put the data read in a global variable  */

   i = _inp(apples);          /* passing enumerated type as the       */
                              /* port number                          */
                              /* ===================================  */
                              /* Types of port number passed :        */
                              /* -----------------------------------  */
   i = _inp(c);               /* - constant                           */
   i = _inp(arr[c]);          /* - element of array                   */
   st.i = Add1(c);            /*                                      */
   i = _inp(st.i);            /* - element of structure               */
   i = _inp(Add1(LOWER));     /* - return value from a function call  */
   i = _inp(UPPER);           /* - #define constant                   */
   i = _inp(256);             /* - the exact port number              */
                              /* -----------------------------------  */
   return 0;
}

int Add1(int j)
   {
   j += 1;
   return j;
   }


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _inpw - Read Unsigned Short from Input Port
o _inpd - Read Double Word from Input Port
o _outp - Write Byte to Output Port
o _outpw - Write Word to Output Port
o _outpd - Write Double Word to Output Port


ΓòÉΓòÉΓòÉ 6.126. _inpd - Read Double Word from Input Port ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <conio.h>            /*  Declared in both  */
#include <builtin.h>

unsigned long _inpd(const unsigned int port);

Language Level: Extension


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

The _inpd function reads a 4-byte (double word) unsigned value from the
specified input port. The port number must be an unsigned short value within
the range 0 to 65 535 inclusive.

Because it is a built-in function and has no backing code in the library:

o You cannot take the address of _inpd.
o You cannot parenthesize an _inpd function call, because parentheses specify a
  call to the backing code for the function.

You can run code containing this function only at ring zero. Otherwise, an
invalid instruction exception is generated.

The _inpd function returns the unsigned long value that was read from the
specified port. There is no error return value and this function does not set
errno.

Example of _inpd


ΓòÉΓòÉΓòÉ <hidden> Example of _inpdx ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses the _inpd function to read a double-word value from the
specified input port and return the data read.

                                                                        *
************************************************************************/

#include <builtin.h>
#define LOWER 0
#define UPPER 65535

int Add1(int j);
static long g;
enum fruit {apples=10, bananas, cantalopes};
int arr[]={cantalopes, bananas, apples};
union
   {
   int i;
   char ch;
   } un;

int main(void)
   {
   unsigned long l;
   volatile const int c = 0;
   un.i = 65534;
   g = _inpd(255);         /* put the data read in a global variable  */

                                       /* =========================== */
                                       /* Types of port number passed:*/
                                       /* --------------------------- */
   l = _inpd(c);                       /* - constant                  */
   l = _inpd(un.i);                    /* - element of union          */
   l = _inpd(Add1(cantalopes));        /* - return value from a       */
                                       /*   function call             */
   l = _inpd(_inp(arr[Add1(LOWER)]));  /* - return value from a       */
                                       /*   builtin function call     */
                                       /* --------------------------- */
   return 0;
}

int Add1(int j)
   {
   j += 1;
   return j;
   }


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _inp - Read Byte from Input Port
o _inpw - Read Unsigned Short from Input Port
o _outp - Write Byte to Output Port
o _outpw - Write Word to Output Port
o _outpd - Write Double Word to Output Port


ΓòÉΓòÉΓòÉ 6.127. _inpw - Read Unsigned Short from Input Port ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <conio.h>              /*  Declared in both  */
#include <builtin.h>

unsigned short _inpw(const unsigned int port);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _inpw function reads an unsigned short value from the specified input port.
The port number must be an unsigned short value within the range 0 to 65 535
inclusive.

Because it is a built-in function and has no backing code in the library:

o You cannot take the address of _inpw.
o You cannot parenthesize an _inpw function call, because parentheses specify a
  call to the backing code for the function.

You can run code containing this function only at ring zero. Otherwise, an
invalid instruction exception is generated.

This function returns the unsigned short value that was read from the specified
port. There is no error return value and this function does not set errno.

Example of _inpw


ΓòÉΓòÉΓòÉ <hidden> Example of _inpw ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses the _inpw to read an unsigned short value from the specified
input port and return the data read.

                                                                        *
************************************************************************/

#include <builtin.h>
#define LOWER 0
#define UPPER 65535

int Add1(int j);
volatile short g;

int main(void)
   {
   volatile unsigned short s;
   volatile const int c = 0;
   int i = 65534;
   enum fruit {apples, bananas, cantalopes};
   int arr[] ={cantalopes, bananas, apples};

   g = _inpw(LOWER);       /* put the data read in a global variable  */

   s = _inpw(bananas);                 /* passing enumerated type     */
                                       /* as the port number          */

                                       /* =========================== */
                                       /* Types of port number passed:*/
                                       /* --------------------------- */
   s = _inpw(c);                       /* - constant                  */
   s = _inpw(i+1);                     /* - integer                   */
   s = _inpw(arr[bananas]);            /* - element of array          */
   s = _inpw(_outp(UPPER,cantalopes)); /* - return value from a       */
                                       /*   builtin function call     */
                                       /* --------------------------- */
   return 0;
}

int Add1(int j)
   {
   j += 1;
   return j;
   }


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _inp - Read Byte from Input Port
o _inpd - Read Double Word from Input Port
o _outp - Write Byte to Output Port
o _outpw - Write Word to Output Port
o _outpd - Write Double Word to Output Port
o builtin.h
o conio.h


ΓòÉΓòÉΓòÉ 6.128. _interrupt - Call Interrupt  Procedure ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <builtin.h>

void _interrupt(const unsigned int intnum);

Language Level: Extension


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

The _interrupt function calls the interrupt procedure specified by intnum using
the INT machine instruction. The integer intnum must have a value within the
range 0 to 255 inclusive.

Because it is a built-in function and has no backing code in the library:

o You cannot take the address of _interrupt.
o You cannot parenthesize an _interrupt function call, because parentheses
  specify a call to the backing code for the function.

This function has no return value and it does not set errno.

Example of _interrupt


ΓòÉΓòÉΓòÉ <hidden> Example of _interrupt ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example shows how to call interrupt 3, which is a breakpoint.

                                                                        *
************************************************************************/

#include <builtin.h>

int main( void )
{
   /* A breakpoint will occur when running this program */
   /* within a debugger.                                */
   _interrupt(3);

   return 0;
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _disable - Disable Interrupts
o _enable - Enable Interrupts


ΓòÉΓòÉΓòÉ 6.129. isalnum to isxdigit  - Test Integer Value ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <ctype.h>

int isalnum(int c);
         /* Test for upper- or lowercase letters, or decimal digit */
int isalpha(int c);
         /* Test for alphabetic character */
int iscntrl(int c);
         /* Test for any control character */
int isdigit(int c);
         /* Test for decimal digit */
int isgraph(int c);
         /* Test for printable character excluding space */
int islower(int c);
         /* Test for lowercase */
int isprint(int c);
         /* Test for printable character including space */
int ispunct(int c);
         /* Test for any nonalphanumeric printable character */
                                          /* excluding space */
int isspace(int c);
         /* Test for whitespace character */
int isupper(int c);
         /* Test for uppercase */
int isxdigit(int c);
         /* Test for hexadecimal digit */


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The <ctype.h> functions listed test a given integer value. They return a
nonzero value if the integer satisfies the test condition, or a zero value if
it does not.

c must be representable as an unsigned char.

Note:  EOF is a valid input value.

Example of isalnum to isxdigit


ΓòÉΓòÉΓòÉ <hidden> Example of isalnum to isxdigit ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example analyzes all characters between code 0x0 and code UPPER_LIMIT,
printing A for alphabetic characters, AN for alphanumerics, U for uppercase, L
for lowercase, D for digits, X for hexadecimal digits, S for spaces, PU for
punctuation, PR for printable characters, G for graphics characters, and C for
control characters.  This example prints the code if printable.

The output of this example is a 256-line table showing the characters from 0 to
255 that possess the attributes tested.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <ctype.h>

#define UPPER_LIMIT   0xFF

int main(void)
{
   int ch;

   for ( ch = 0; ch <= UPPER_LIMIT; ++ch )
   {
      printf("%3d ", ch);
      printf("%#04x ", ch);
      printf("%3s ", isalnum(ch)  ? "AN" : " ");
      printf("%2s ", isalpha(ch)  ? "A"  : " ");
      printf("%2s",  iscntrl(ch)  ? "C"  : " ");
      printf("%2s",  isdigit(ch)  ? "D"  : " ");
      printf("%2s",  isgraph(ch)  ? "G"  : " ");
      printf("%2s",  islower(ch)  ? "L"  : " ");
      printf(" %c",  isprint(ch)  ? ch   : ' ');
      printf("%3s",  ispunct(ch)  ? "PU" : " ");
      printf("%2s",  isspace(ch)  ? "S"  : " ");
      printf("%3s",  isprint(ch)  ? "PR" : " ");
      printf("%2s",  isupper(ch)  ? "U"  : " ");
      printf("%2s",  isxdigit(ch) ? "X"  : " ");

      putchar('\n');
   }
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _isascii - Test Integer Values
o _iscsym - _iscsymf - Test Integer
o tolower - toupper  - Convert Character Case
o _toascii - _tolower - _toupper - Convert Character
o ctype.h


ΓòÉΓòÉΓòÉ 6.130. _isascii - Test Integer Values ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <ctype.h>

int _isascii(int c);

Language Level: Extension


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

The _isascii macro tests if an integer is within the ASCII range.  This macro
assumes that the system uses the ASCII character set.

The _isascii macro returns a nonzero value if the integer is within the ASCII
set, and 0 if it is not.

Language Level: Extension

Example of _isascii


ΓòÉΓòÉΓòÉ <hidden> Example of _isascii ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example tests the integers from 0x7c to 0x82, and prints the corresponding
ASCII character if the integer is within the ASCII range.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <ctype.h>

int main(void)
{
    int ch;

    for (ch = 0x7c; ch <= 0x82; ch++)
    {
        printf("%#04x    ", ch);
        if (isascii(ch))
            printf("The ASCII character is %c\n", ch);
        else
            printf("Not an ASCII character\n");
    }

    return 0;


/****************  The output should be similar to:  ********************

   0x7c    The ASCII character is |
   0x7d    The ASCII character is }
   0x7e    The ASCII character is ~
   0x7f    The ASCII character is 
   0x80    Not an ASCII character
   0x81    Not an ASCII character
   0x82    Not an ASCII character
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o isalnum to isxdigit  - Test Integer Value
o _iscsym - _iscsymf - Test Integer
o _toascii - _tolower - _toupper - Convert Character
o tolower - toupper  - Convert Character Case
o ctype.h


ΓòÉΓòÉΓòÉ 6.131. _isatty - Test Handle for Character Device ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <io.h>

int _isatty(int handle);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _isatty function determines whether the given handle is associated with a
character device (a keyboard, display, printer or serial port).

The _isatty function returns a nonzero value if the device is a character
device. Otherwise, the return value is 0.

Example of _isatty


ΓòÉΓòÉΓòÉ <hidden> Example of _isatty ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example opens the console and tries to determine if it is a character
device:

                                                                        *
************************************************************************/

#include <io.h>
#include <stdio.h>
#include <fcntl.h>
#include <sys\stat.h>

int main(void)
{
   int  fh, result;

   if (-1 == (fh = _open("CON", O_RDWR,(S_IREAD | S_IWRITE))))
   {
      perror("Error opening console\n");
      return 1;
   }

   result = _isatty(fh)    ;

   if (0 != result)
      printf("CON is a character device.\n");
   else
      printf("CON is not a character device.\n");

   _close (fh);
   return 0;

/********************  The expected output is:  *************************

      CON is a character device.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _inp - Read Byte from Input Port
o _inpd - Read Double Word from Input Port
o _inpw - Read Unsigned Short from Input Port
o _outp - Write Byte to Output Port
o _outpd - Write Double Word to Output Port
o _outpw - Write Word to Output Port
o io.h


ΓòÉΓòÉΓòÉ 6.132. _iscsym - _iscsymf - Test Integer ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <ctype.h>

int _iscsym(int c);

int _iscsymf(int c);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

These macros test if an integer is within a particular ASCII set. The macros
assume that the system uses the ASCII character set.

The _iscsymf macro tests if a character is alphabetic or an underscore (_). The
_iscsym macro tests if a character is alphabetic, a digit, or an underscore.

The _iscsym and _iscsymf macros return a nonzero value if the integer is within
the ASCII set for which it tests, and 0 otherwise.

Example of _iscsym - _iscsymf


ΓòÉΓòÉΓòÉ <hidden> Example of _iscsym - _iscsymf ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example uses _iscsym and _iscsymf to test the characters a, _, and 1. If
the character falls within the ASCII set tested for, the macro returns TRUE.
Otherwise, it returns FALSE.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <ctype.h>

int main(void)
{
    int ch[3] = {'a', '_', '1'};
    int i;

    for (i = 0; i < 3; i++)
    {
        printf("_iscsym('%c') returns %s\n",
                     ch[i], _iscsym(ch[i]) ? "TRUE" : "FALSE");

        printf("_iscsymf('%c') returns %s\n\n",
                     ch[i], _iscsymf(ch[i]) ? "TRUE" : "FALSE");
    }

    return 0;

/******************  The output should be similar to:  ******************

   _iscsym('a') returns TRUE
   _iscsymf('a') returns TRUE

   _iscsym('_') returns TRUE
   _iscsymf('_') returns TRUE

   _iscsym('1') returns TRUE
   _iscsymf('1') returns FALSE
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o isalnum to isxdigit  - Test Integer Value
o _isascii - Test Integer Values
o tolower - toupper  - Convert Character Case
o _toascii - _tolower - _toupper - Convert Character
o ctype.h


ΓòÉΓòÉΓòÉ 6.133. _itoa - Convert Integer to String ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

char *_itoa(int value, char * string, int radix);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _itoa function converts the digits of the given value to a character string
that ends with a null character and stores the result in string. The radix
argument specifies the base of value; it must be in the range 2 to 36. If radix
equals 10 and value is negative, the first character of the stored string is
the minus sign (-).

Note:  The space reserved for string must be large enough to hold the returned
string. The function can return up to 33 bytes including the null character
(\0).

The _itoa function returns a pointer to string. There is no error return value.

Example of _itoa


ΓòÉΓòÉΓòÉ <hidden> Example of _itoa ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example converts the integer value -255 to a decimal, a binary, and a hex
number, storing its character representation in the array buffer.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
    char buffer[35];
    char *p;

    p = _itoa(-255, buffer, 10);
    printf("The result of _itoa(-255) with radix of 10
             is %s\n", p);

    p = _itoa(-255, buffer, 2);
    printf("The result of _itoa(-255) with radix of 2\n
             is %s\n", p);

    p = _itoa(-255, buffer, 16);
    printf("The result of _itoa(-255) with radix of 16
             is %s\n", p);

    return 0;

    /* The expected output is:

       The result of _itoa(-255) with radix of 10 is -255
       The result of _itoa(-255) with radix of 2
           is 11111111111111111111111100000001
       The result of _itoa(-255) with radix of 16 is ffffff01
                                                                          */
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _ecvt - Convert Floating-Point to Character
o _fcvt - Convert Floating-Point to String
o _gcvt - Convert Floating-Point to String
o _ltoa - Convert Long Integer to String
o _ultoa - Convert Unsigned Long Integer to String
o stdlib.h


ΓòÉΓòÉΓòÉ 6.134. _kbhit - Test for Keystroke ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

include <conio.h>

int _kbhit(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _kbhit function tests if a key has been pressed on the keyboard.  If the
result is nonzero, a keystroke is waiting in the buffer.  You can get the
keystroke using the _getch or _getche function.  If you call _getch or _getche
without first calling _kbhit, the program waits for a key to be pressed.

The _kbhit function returns a nonzero value if a key has been pressed.
Otherwise, it returns 0.

Example of _kbhit


ΓòÉΓòÉΓòÉ <hidden> Example of _kbhit ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses _kbhit to test for the pressing of a key on the keyboard and
to print a statement with the result of the test.

                                                                        *
************************************************************************/

 #include <conio.h>
 #include <stdio.h>

 int main(void)
    {
    int ch;

    printf("Type in some letters.\n");
    printf("If you type in an 'x', the program ends.\n");

    for (;;)
       {
       while (_kbhit() == 0)
          {
          /* Processing without waiting for a key to be pressed */
          }

       ch = _getch();

       printf("You have pressed the '%c' key.\n",ch);

       if (ch == 'x')
          break;

       }
    return 0;

/*******************  Possible output:  ********************************

    Type in some letters.
    If you type in an 'x', the program ends.
    You have pressed the 'f' key.
    You have pressed the 'e' key.
    You have pressed the 'l' key.
    You have pressed the 'i' key.
    You have pressed the 'x' key.

***********************  Program ends  ********************************/
    }


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _getch - _getche - Read Character from Keyboard
o conio.h


ΓòÉΓòÉΓòÉ 6.135. labs  - Calculate long Absolute Value ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

long int labs(long int n);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The labs function produces the absolute value of its long integer argument n.

The result may be undefined when the argument is equal to LONG_MIN, the
smallest available long integer (-2 147 483 647). The value LONG_MIN is defined
in the <limits.h> include file. There is no return value.

Example of labs


ΓòÉΓòÉΓòÉ <hidden> Example of labs ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example computes y as the absolute value of the long integer -41567.

                                                                        *
************************************************************************/

#include <stdlib.h>
#include <stdio.h>

int main(void)
{
   long x, y;

   x = -41567L;
   y = labs(x);

   printf("The absolute value of %ld is %ld\n", x, y);
}

/********************  Output should be similar to:  **************

The absolute value of -41567 is 41567
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o abs  - Calculate Integer Absolute Value
o _cabs - Calculate Absolute Value of Complex Number
o fabs  - Calculate Floating-Point Absolute Value
o limits.h


ΓòÉΓòÉΓòÉ 6.136. ldexp  - Multiply by a Power of Two ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h>

double ldexp(double x, int exp);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The ldexp function calculates the value of x * (2**exp). If an overflow
results, the function returns +HUGE_VAL for a large result or -HUGE_VAL for a
small result, and sets errno to ERANGE.

Example of ldexp


ΓòÉΓòÉΓòÉ <hidden> Example of ldexp ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example computes y as 1.5 times 2 to the fifth power (1.5 * (2**5)):

                                                                        *
************************************************************************/

#include <math.h>

int main(void)
{
   double x, y;
   int p;

   x = 1.5;
   p = 5;
   y = ldexp(x,p);

   printf("%lf times 2 to the power of %d is %lf\n", x, p, y);
}

/********************  Output should be similar to:  **************

1.500000 times 2 to the power of 5 is 48.000000
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o frexp  - Separate Floating-Point Value
o modf  - Separate Floating-Point Value
o math.h


ΓòÉΓòÉΓòÉ 6.137. ldiv  - Long Division ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

ldiv_t ldiv(long int numerator, long int denominator);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The ldiv function calculates the quotient and remainder of the division of
numerator by denominator.

The ldiv function returns a structure of type ldiv_t, containing both the
quotient long int quot and the remainder long int rem.  If the value cannot be
represented, the return value is undefined. If denominator is 0, an exception
is raised.

Example of ldiv


ΓòÉΓòÉΓòÉ <hidden> Example of ldiv ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses the ldiv function to calculate the quotients and remainders
for a set of two dividends and two divisors.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
   long int num[2] = {45,-45};
   long int den[2] = {7,-7};
   ldiv_t ans;   /* ldiv_t is a struct type containing two long ints:
                    'quot' stores quotient; 'rem' stores remainder */
   short i,j;

   printf("Results of long division:\n");
   for (i = 0; i < 2; i++)
      for (j = 0; j < 2; j++)
      {
         ans = ldiv(num[i], den[j]);
         printf("Dividend: %6ld  Divisor: %6ld", num[i], den[j]);
         printf("  Quotient: %6ld  Remainder: %6ld\n", ans.quot, ans.rem);
      }
}

/********************  Expected output:  **************************

Results of long division:
Dividend:  45  Divisor:   7  Quotient:   6  Remainder:   3
Dividend:  45  Divisor:  -7  Quotient:  -6  Remainder:   3
Dividend: -45  Divisor:   7  Quotient:  -6  Remainder:  -3
Dividend: -45  Divisor:  -7  Quotient:   6  Remainder:  -3
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o div  - Calculate Quotient and Remainder
o stdlib.h


ΓòÉΓòÉΓòÉ 6.138. _lfind - _lsearch - Find Key in Array ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <search.h>

char *_lfind(char *search_key, char *base, unsigned int *num,
                 unsigned int *width, int (*)(const void *key,
                 const void *compare));

char *_lsearch(char *search_key, char *base, unsigned int *num,
                 unsigned int *width, int (*)(const void *key,
                 const void *compare));


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _lfind and _lsearch functions perform a linear search for the value
search_key in an array of num elements, each of width bytes in size.  Unlike
bsearch, _lsearch and _lfind do not require that you sort the array first.  The
argument base points to the base of the array to be searched.

If _lsearch does not find the search_key, it adds the search_key to the end of
the array and increments num by one.  If _lfind does not find the search_key,
it does not add the search_key to the array.

The argument compare is a pointer to a function that you supply.  This function
compares the specified key with an array element and returns a value specifying
their relationship.  Both _lsearch and _lfind call the compare function one or
more times during the search, passing pointers to two array elements on each
call.

The compare argument is returned as one of the following values:

Value          Meaning
Nonzero        key and element are different.
0              key and element are identical.

If the search_key is found, both _lsearch and _lfind return a pointer to that
element of the array to which base points. If the search_key is not found,
_lsearch returns a pointer to a newly added item at the end of the array, while
_lfind returns NULL.

Example of _lfind


ΓòÉΓòÉΓòÉ <hidden> Example of _lfind ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example uses the _lfind function to search for the keyword PATH in the
command-line arguments.

                                                                        *
************************************************************************/

#include <search.h>
#include <string.h>
#include <stdio.h>

#define CNT 2

/* Must declare 'compare' as a function  */
int compare(const void *, const void *);

int main(void)
{
   char **result;
   char *key = "PATH";

   unsigned int num = CNT;

   char *string[CNT] =
            {
             "PATH = d:\\david\\heather\\ed\\simon",
             "LIB = PATH\\abc"
            };

   /* The following statement finds the argument
            that starts with "PATH" */
   if ((result = (char **)_lfind((char *)&key,
                                (char *)string, &num,
                                sizeof(char *), compare)) != NULL)
       printf("%s found\n", *result);
   else
       printf("PATH not found \n");

   return 0;
}

/* The following is a sample 'compare' function */

int compare(const void *arg1, const void *arg2)
{
    return(strncmp(*(char **)arg1, *(char **)arg2,
            strlen(*(char **)arg1)));
}

/*****************  The output should be similar to:  *******************

    PATH = d:\david\heather\ed\simon found
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o bsearch  - Search Arrays
o qsort  - Sort Array
o search.h


ΓòÉΓòÉΓòÉ 6.139. _loadmod - Load User DLL ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

int _loadmod(char *module_name, unsigned long *module_handle);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _loadmod function loads a user-created dynamic link library (DLL) for the
calling process. The module_name is the name of the DLL to be loaded, and the
module_handle is the file handle associated with the DLL.

If the operation is successful, _loadmod returns the handle of the loaded DLL
to the calling process.  The process can use this handle with the OS/2 API
DosQueryProcAddr to get the address of the required function from within the
DLL.  Once the reference is established, the calling process can then call the
specific function.

The return value of _loadmod is 0 if the DLL was successfully loaded.  If
unsuccessful, _loadmod returns -1, and sets errno to one of the following
values:

Value             Meaning
EMODNAME          The specified module_name is not valid.
EOS2ERR           A system error occurred.  Check _doserrno for the specific
                  OS/2 error code.

Example of _loadmod


ΓòÉΓòÉΓòÉ <hidden> Example of _loadmod ΓòÉΓòÉΓòÉ

/************************************************************************
*
In this example, _loadmod loads the DLL mark and gets the address of the
function PLUS within the DLL.  It then calls that function, which adds two
integers passed to it. The types PFN and APIRET, are required to use the OS/2
DosQueryProcAddr API, and are defined by including the <os2.h> header file.

Note:  To run this program, you must first create mark.dll. Copy the code for
the PLUS function into a file called mark.c, and the code for the .DEF file
into mark.def.  Eliminate the comments from these two files. Compile with the
command:

   icc /Ge- mark.c mark.def
You can then run the example:

                                                                        *
************************************************************************/

#define INCL_DOS
#include <os2.h>
#include <stdio.h>
#include <stdlib.h>

/* This is the code for MARK.DEF

LIBRARY MARK

PROTMODE

EXPORTS PLUS                       */

/* This is the code for PLUS function in the DLL

   #pragma linkage( PLUS, system )
   int PLUS( int a, int b )
   {
      return a + b;
   }                                               */

int main(void)
{
   int x = 4, y = 7;

   unsigned long handle;
   char * modname = "MARK" ;     /* DLL name              */
   char * fname = "PLUS"  ;      /* function name         */

   PFN faddr;                    /* pointer to function   */
   APIRET rc;                    /* return code           */
                                 /* from DosQueryProcAddr */

   /*  dynamically load the 'mark' DLL  */
   if (_loadmod(modname, &handle) )
   {
      printf("Error loading module %s\n", modname );
      exit (-1);
   }

   /*  get function address from DLL  */
   rc = DosQueryProcAddr( handle, 0, fname, &faddr );

   if (rc == 0)
      printf("Calling the function from the %s DLL to add %d
               and %d\n", modname,x,y);
      printf("The result of the function call is %d\n",
              faddr(x,y));
   else
   {
      printf("Error locating address of function %s\n",
               fname);
      _freemod( handle );
      exit(-1);
   }

   if( _freemod( handle ))
   {
      printf("Error in freeing the %s DLL module\n",
               modname);
      exit(-1);
   }

   printf("Reference to the %s DLL module has been freed\n",
            modname);

   return 0;

/**************  The expected output is  ********************

      Calling the function from the DLL to add 4 and 7
      The result of the function call is 11
      Reference to the MARK DLL module has been freed

*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _freemod - Free User DLL
o stdlib.h


ΓòÉΓòÉΓòÉ 6.140. localeconv  - Query Locale Conventions ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <locale.h>

struct lconv *localeconv(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The localeconv function sets the components of a structure having type struct
lconv to values appropriate for the current locale.  The structure may be
overwritten by another call to localeconv or by calling setlocale and passing
LC_ALL, LC_MONETARY, or LC_NUMERIC.

The structure contains the following elements (defaults shown are for the C
locale):

ELEMENT          PURPOSE OF ELEMENT             DEFAULT
"char *decimal_point"   Decimal-point character used to format   "."
             nonmonetary quantities.
"char *thousands_sep"   Character used to separate groups of    ""
             digits to the left of the decimal-point
             character in formatted nonmonetary quan-
             tities.
"char *grouping"     String indicating the size of each group  ""
             of digits in formatted nonmonetary quan-
             tities.  The value of each character in
             the string determines the number of
             digits in a group.  A value of
             "CHAR_MAX" indicates that there are no
             further groupings.  "0" indicates that
             the previous element is to be used for
             the remainder of the digits.
"char           International currency symbol for the    ""
*int_curr_symbol"     current locale.  The first three charac-
             ters contain the alphabetic interna-
             tional currency symbol.  The fourth
             character (usually a space) is the char-
             acter used to separate the international
             currency symbol from the monetary quan-
             tity.
"char           Local currency symbol of the current    ""
*currency_symbol"     locale.
"char           Separator for digits in formatted mone-   ""
*mon_thousands_sep"    tary quantities.
"char *mon_grouping"   String indicating the size of each group  ""
             of digits in formatted monetary quanti-
             ties.  The value of each character in
             the string determines the number of
             digits in a group.  A value of
             "CHAR_MAX" indicates that there are no
             further groupings.  "0" indicates that
             the previous element is to be used for
             the remainder of the digits.
"char *positive_sign"   String indicating the positive sign used  ""
             in monetary quantities.
"char *negative_sign"   String indicating the negative sign used  ""
             in monetary quantities.
"char int_frac_digits"  The number of displayed digits to the    "UCHAR_MAX"
             right of the decimal place for interna-
             tionally formatted monetary quantities.
"char frac_digits"    Number of digits to the right of the    "UCHAR_MAX"
             decimal place in monetary quantities.
"char p_cs_precedes"   1 if the "currency_symbol" precedes the   "UCHAR_MAX"
             value for a nonnegative formatted mone-
             tary quantity; "0" if it does not.
"char p_sep_by_space"   1 if the "currency_symbol" is separated   "UCHAR_MAX"
             by a space from the value of a nonnega-
             tive formatted monetary quantity;  "0"
             if it does not.
"char n_cs_precedes"   1 if the "currency_symbol" precedes the   "UCHAR_MAX"
             value for a negative formatted monetary
             quantity; "0" if it does not.
"char n_sep_by_space"   1 if the "currency_symbol" is separated   "UCHAR_MAX"
             by a space from the value of a negative
             formatted monetary quantity;  "0" if it
             does not.
"char p_sign_posn"    Value indicating the position of the    "UCHAR_MAX"
             "positive_sign" for a nonnegative for-
             matted monetary quantity.
"char n_sign_posn"    Value indicating the position of the    "UCHAR_MAX"
             "negative_sign" for a negative formatted
             monetary quantity.

The n_sign_posn and p_sign_posn elements can have the following values:

Value Meaning
 0   The quantity and currency_symbol are enclosed in parentheses.
 1   The sign precedes the quantity and currency_symbol.
 2   The sign follows the quantity and currency_symbol.
 3   The sign precedes the currency_symbol.
 4   The sign follows the currency_symbol.

The localeconv function returns a pointer to the structure.

Example of localeconv


ΓòÉΓòÉΓòÉ <hidden> Example of localeconv ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example prints out the default decimal point for your locale and then the
decimal point for the LC_C_FRANCE locale.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <locale.h>

int main(void)
{
  char * string;
  struct lconv * mylocale;

  mylocale = localeconv();
  /* Default decimal point */
  printf( "Default decimal point is a %s\n",
            mylocale->decimal_point );

  string = setlocale(LC_ALL, LC_C_FRANCE );
  mylocale = localeconv();
  /* A comma is set to be the decimal point
        when the locale is LC_C_FRANCE */
  printf( "France's decimal point is a %s\n",
            mylocale->decimal_point );
}

/********************  Output should be similar to:  **************

Default decimal point is a .
France's decimal point is a ,
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o setlocale  - Set Locale
o locale.h


ΓòÉΓòÉΓòÉ 6.141. localtime  - Convert Time ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <time.h>

struct tm *localtime(const time_t *timeval);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The localtime function converts a time value stored as a time_t value to a
structure.  The time value is usually obtained by a call to the time function.

The localtime function breaks down the timeval value, corrects for the local
time zone and Daylight Saving Time, if appropriate, and stores the corrected
time in a structure of type tm.  See gmtime for a description of the fields in
a tm structure.

The localtime function returns a pointer to the structure result.  There is no
error return value.

Note:

 1. The gmtime and localtime functions may use a common, statically allocated
    buffer for the conversion.  Each call to one of these functions may alter
    the result of the previous call.

 2. The time and date functions begin at 00:00:00 Coordinated Universal Time,
    January 1, 1970.

Example of localtime


ΓòÉΓòÉΓòÉ <hidden> Example of localtime ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example queries the system clock and displays the local time.

                                                                        *
************************************************************************/

#include <time.h>
#include <stdio.h>

int main(void)
{
   struct tm *newtime;
   time_t ltime;

   time(<ime);
   newtime = localtime(<ime);
   printf("The date and time is %s", asctime(newtime));
}

/**************  If the local time is 3:00 p.m. May 31, 1993,  **********
*************************  output should be:  *********************

The date and time is Mon May 31 15:00:00 1993
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o asctime  - Convert Time
o ctime  - Convert Time
o gmtime  - Convert Time
o mktime  - Convert Local Time
o time  - Determine Current Time
o time.h


ΓòÉΓòÉΓòÉ 6.142. log  - Calculate Natural Logarithm ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h>

double log(double x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The log function calculates the natural logarithm (base e) of x.

The log function returns the computed value.  If x is negative, it will set
errno to EDOM and may return the value -HUGE_VAL. If x is zero, log returns the
value -HUGE_VAL, and may set errno to ERANGE.

Example of log


ΓòÉΓòÉΓòÉ <hidden> Example of log ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example calculates the natural logarithm of 1000.0.

                                                                        *
************************************************************************/

#include <math.h>
#include <stdio.h>

int main(void)
{
   double x = 1000.0, y;

   y = log(x);

   printf("The natural logarithm of %lf is %lf\n", x, y);
}

/********************  Output should be similar to:  **************

The natural logarithm of 1000.000000 is 6.907755
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o exp  - Exponential Function
o log10  - Calculate Base 10 Logarithm
o pow  - Compute Power
o math.h


ΓòÉΓòÉΓòÉ 6.143. log10  - Calculate Base 10 Logarithm ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h>

double log10(double x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The log10 function calculates the base 10 logarithm of x.

The log10 function returns the computed value.  If x is negative, it will set
errno to EDOM and may return the value -HUGE_VAL. If x is zero, log10 returns
the value -HUGE_VAL, and may set errno to ERANGE.

Example of log10


ΓòÉΓòÉΓòÉ <hidden> Example of log10 ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example calculates the base 10 logarithm of 1000.0.

                                                                        *
************************************************************************/

#include <math.h>
#include <stdio.h>

int main(void)
{
   double x = 1000.0, y;

   y = log10(x);

   printf("The base 10 logarithm of %lf is %lf\n", x, y);
}

/********************  Output should be similar to:  **************

The base 10 logarithm of 1000.000000 is 3.000000
*/


ΓòÉΓòÉΓòÉ <hidden> Relative Information ΓòÉΓòÉΓòÉ

o exp  - Exponential Function
o log  - Calculate Natural Logarithm
o pow  - Compute Power
o math.h


ΓòÉΓòÉΓòÉ 6.144. longjmp  - Restore Stack Environment ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <setjmp.h>

void longjmp(jmp_buf env, int value);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The longjmp function restores a stack environment previously saved in env by
setjmp.  The setjmp macro and longjmp function provide a way to perform a
nonlocal goto. They are often used in signal handlers.

A call to setjmp causes the current stack environment to be saved in env.  A
subsequent call to longjmp restores the saved environment and returns control
to a point in the program corresponding to the setjmp call.  Execution resumes
as if the setjmp call had just returned the given value.  All variables (except
register variables) that are accessible to the function that receives control
contain the values they had when longjmp was called.  The values of register
variables are unpredictable.  Nonvolatile auto variables that are changed
between calls to setjmp and longjmp are also unpredictable.

Note:  Ensure that the function that calls setjmp does not return before you
       call the corresponding longjmp function. Calling longjmp after the
       function calling setjmp returns causes unpredictable program behavior.

The value argument passed to longjmp must be nonzero.  If you give a zero
argument for value, longjmp substitutes a 1 in its place.

The longjmp function does not use the normal function call and return
mechanisms;  it has no return value.

Example of longjmp


ΓòÉΓòÉΓòÉ <hidden> Example of longjmp ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example provides for saving the stack environment at the statement:

  if(setjmp(mark) != 0) ...

When the system first performs the if statement, it saves the environment in
mark and sets the condition to FALSE because setjmp returns a 0 when it saves
the environment.  The program prints the message:

  setjmp has been called

The subsequent call to function p tests for a local error condition, which can
cause it to perform the longjmp function.  Then, control returns to the
original setjmp function using the environment saved in mark.  This time the
condition is TRUE because -1 is the return value from the longjmp function. The
example then performs the statements in the block and prints:

  longjmp has been called

It then performs the recover function and leaves the program.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <setjmp.h>

jmp_buf mark;

void p(void);
void recover(void);

int main(void)
{
   if (setjmp(mark) != 0)
   {
      printf("longjmp has been called\n");
      recover();
      exit(1);
      }
   printf("setjmp has been called\n");
   .
   .
   .
   p();
   .
   .
   .
}

void p(void)
{
   int error = 0;
   .
   .
   .
   error = 9;
   .
   .
   .
   if (error != 0)
      longjmp(mark, -1);
   .
   .
   .
}

void recover(void)
{
   .
   .
   .
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o setjmp  - Preserve Environment
o goto
o volatile and const Qualifiers
o auto Storage Class Specifier
o setjmp.h


ΓòÉΓòÉΓòÉ 6.145. _lrotl - _lrotr - Rotate Bits ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

unsigned long _lrotl(unsigned long value, int shift);

unsigned long _lrotr(unsigned long value, int shift);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

These functions rotate value by shift bits. The _lrotl function rotates to the
left, and _lrotr to the right.

Both functions return the rotated value.  There is no error return value.

Example of _lrotl - _lrotr


ΓòÉΓòÉΓòÉ <hidden> Example of _lrotl - _lrotr ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example uses _lrotl and _lrotr with different shift values to rotate the
long integer value 0x01234567:

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
    unsigned long val = 0X01234567;

    printf("The value of 0x%8.8lx rotated 4 bits to the left is
             0x%8.8lx\n", val,  _lrotl(val, 4));

    printf("The value of 0x%8.8lx rotated 16 bits to the right is
             0x%8.8lx\n", val,  _lrotr(val, 16));


    return 0;

/*************  The output should be similar to:  ***********************

   The value of 0x01234567 rotated 4 bits to the left is 0x12345670
   The value of 0x01234567 rotated 16 bits to the right is 0x45670123
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _rotl - _rotr - Bit Rotation
o stdlib.h


ΓòÉΓòÉΓòÉ 6.146. _lseek - Move File Pointer ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <io.h>
#include <stdio.h>

long _lseek(int handle, long offset, int origin);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _lseek function moves any file pointer associated with handle to a new
location that is offset bytes from the origin. The next operation on the file
takes place at the new location. Origin must be one of the following constants,
defined in <stdio.h>:

Origin         Definition
SEEK_SET       Beginning of file
SEEK_CUR       Current position of file pointer
SEEK_END       End of file.

The _lseek function can reposition the pointer anywhere in a file. The pointer
can also be positioned beyond the end of the file; the data between the eof and
the new file position is undefined. (See _chsize - Alter Length of File for
more information on extending the length of the file.) However, an attempt to
position the pointer before the beginning of the file causes an error.

The _lseek function returns the offset, in bytes, of the new position from the
beginning of the file. A return value of -1L indicates an error, and errno is
set to one of the following values:

Value          Meaning
EBADF          The file handle is incorrect.
EINVAL         The value for origin is incorrect, or the position specified by
               offset is before the beginning of the file.
EOS2ERR        The call to the operating system was not successful.

On devices incapable of seeking (such as keyboards and printers), the return
value is -1, and errno is set to EOS2ERR.

Example of _lseek


ΓòÉΓòÉΓòÉ <hidden> Example of _lseek ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example opens the file sample.dat and if successful, moves the file
pointer to the eighth position in the file. The example then attempts to read
bytes from the file, starting at the new pointer position, and reads them into
the buffer.

                                                                        *
************************************************************************/

#include <io.h>
#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>
#include <string.h>

int main(void)
   {
   long length;
   int  fh;
   char buffer[20];

   memset(buffer,'\0',20);  /* Initialize the buffer */

   printf("\nCreating sample.dat.\n");
   system("echo Sample Program > sample.dat");


   if (-1 == (fh = _open("sample.dat",O_RDWR | O_APPEND)))
      {
      perror("Unable to open sample.dat.");
      _exit(1);
      }

   if ( -1 == _lseek(fh,7,SEEK_SET) ) /* place the file pointer at the */
      {                              /* eighth position in the file   */
      perror("Unable to _lseek");
      _close(fh);
      return 1;
      }

   if (8 != _read(fh,buffer,8))
      {
      perror("Unable to read from sample.dat.");
      _close(fh);
      return 1;
      }

   printf("Successfully read in the following:\n%s\n ",buffer);

   _close(fh);

   return 0;

/***********  The expected output is:  *****************

      Creating sample.dat.
      Successfully read in the following:
      Program
*/
   }


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _chsize - Alter Length of File
o fseek  - Reposition File Position
o _tell - Get Pointer Position
o io.h
o stdio.h


ΓòÉΓòÉΓòÉ 6.147. _ltoa - Convert Long Integer to String ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

char *_ltoa(long value, char *string, int radix);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _ltoa function converts the digits of the given long integer value to a
character string that ends with a null character and stores the result in
string.  The radix argument specifies the base of value; it must be in the
range 2 to 36. If radix equals 10 and value is negative, the first character of
the stored string is the minus sign (-).

Note:  The space allocated for string must be large enough to hold the returned
string. The function can return up to 33 bytes including the null character
(\0).

The _ltoa function returns a pointer to string.  There is no error return
value.

Example of _ltoa


ΓòÉΓòÉΓòÉ <hidden> Example of _ltoa ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example converts the long integer -255L to a decimal, binary, and hex
value, and stores its character representation in the array buffer.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
    char buffer[35];
    char *p;

    p = _ltoa(-255L, buffer, 10);
    printf("The result of _ltoa(-255) with radix of 10 is %s\n", p);

    p = _ltoa(-255L, buffer, 2);
    printf("The result of _ltoa(-255) with radix of 2\n    is %s\n", p);

    p = _ltoa(-255L, buffer, 16);
    printf("The result of _ltoa(-255) with radix of 16 is %s\n", p);

    return 0;

    /* The expected output is:

       The result of _ltoa(-255) with radix of 10 is -255
       The result of _ltoa(-255) with radix of 2
           is 11111111111111111111111100000001
       The result of _ltoa(-255) with radix of 16 is ffffff01  */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o atol  - Convert Character Strings
o _ecvt - Convert Floating-Point to Character
o _fcvt - Convert Floating-Point to String
o _gcvt - Convert Floating-Point to String
o _itoa - Convert Integer to String
o _ultoa - Convert Unsigned Long Integer to String
o stdlib.h


ΓòÉΓòÉΓòÉ 6.148. _makepath - Create Path ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

void _makepath(char *path, char *drive, char *dir, char *fname, char *ext);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _makepath function creates a single path name, composed of a drive letter,
directory path, file name, and file name extension.

The path argument should point to an empty buffer large enough to hold the
complete path name. The constant _MAX_PATH, defined in <stdlib.h>, specifies
the maximum size allowed for path. The other arguments point to the following
buffers containing the path name elements:

Buffer         Description
drive          Contains a letter (A, B, ...) corresponding to the desired drive
               and an optional following colon.  The _makepath routine inserts
               the colon automatically in the composite path name if it is
               missing.  If drive is a null character or an empty string, no
               drive letter or colon appears in the composite path string.
dir            Contains the path of directories, not including the drive
               designator or the actual file name.  The trailing slash is
               optional, and either slash (/) or backslash (\) or both can be
               used in a single dir argument.  If a trailing slash or backslash
               (/ or \) is not specified, it is inserted automatically.  If dir
               is a null character or an empty string, no slash is inserted in
               the composite path string.
fname          Contains the base file name without any extensions.
ext            Contains the actual file name extension, with or without a
               leading period.  The _makepath function inserts the period
               automatically if it does not appear in ext.  If ext is a null
               character or an empty string, no period is inserted in the
               composite path string.

The size limits on the above four fields are those specified by the constants
_MAX_DRIVE, _MAX_DIR, _MAX_FNAME, and _MAX_EXT, which are defined in
<stdlib.h>. The composite path should be no larger than the _MAX_PATH constant
also defined in <stdlib.h>; otherwise, the operating system does not handle it
correctly.

Note:  No checking is done to see if the syntax of the file name is correct.

There is no return value.

Example of _makepath


ΓòÉΓòÉΓòÉ <hidden> Example of _makepath ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example builds a file name path from the specified components:

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
   char path_buffer [_MAX_PATH];
   char drive [_MAX_DRIVE];
   char dir [_MAX_DIR];
   char fname [_MAX_FNAME];
   char ext [_MAX_EXT];

   _makepath (path_buffer, "c",
        "qc\\bob\\eclibref\\e", "makepath", "c");
   printf ("Path created with _makepath: %s\n\n",
        path_buffer);

   _splitpath (path_buffer, drive, dir, fname, ext);
   printf ("Path extracted with _splitpath:\n");
   printf ("drive: %s\n", drive);
   printf ("directory: %s\n", dir);
   printf ("file name: %s\n", fname);
   printf ("extension: %s\n", ext);

   return 0;

/************  The output should be similar to:  ********

   Path created with _makepath:
         c:qc\bob\eclibref\e\makepath.c

   Path extracted with _splitpath:
   drive: c:
   directory: qc\bob\eclibref\e\
   file name: makepath
   extension: .c
*/

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _fullpath - Get Full Path Name of Partial Path
o _splitpath - Decompose Path Name
o stdlib.h


ΓòÉΓòÉΓòÉ 6.149. malloc  - Reserve Storage Block ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>  /* also defined in <malloc.h> */

void *malloc(size_t size);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA, Extension

The malloc function reserves a block of storage of size bytes. Unlike the
calloc function, malloc does not necessarily give all the bits of each element
an initial value of 0.

The malloc function returns a pointer to the reserved space.  The storage space
to which the return value points is guaranteed to be suitably aligned for
storage of any type of object.

The return value is NULL if there is not enough storage available, or if size
was specified as zero.

Example of malloc


ΓòÉΓòÉΓòÉ <hidden> Example of malloc ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example prompts for the number of array entries you want and then reserves
enough space in storage for the entries. If malloc was successful, the example
assigns values to the entries and prints out each entry;  otherwise, it prints
out an error.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
  long * array;    /* start of the array */
  long * index;    /* index variable     */
  int    i;        /* index variable     */
  int  num;        /* number of entries of the array */

  printf( "Enter the size of the array\n" );
  scanf( "%i", &num );

  /* allocate num entries */
  if ( (index = array = malloc( num * sizeof( long ))) != NULL )
  {

    for ( i = 0; i < num; ++i )           /* put values in array    */
       *index++ = i;                      /* using pointer notation */

    for ( i = 0; i < num; ++i )           /* print the array out    */
      printf( "array[ %i ] = %i\n", i, array[i] );
  }
  else { /* malloc error */
    perror( "Out of storage" );
    abort();
  }
}

/********************  Output should be similar to:  **************

Enter the size of the array
array[ 0 ] = 0
array[ 1 ] = 1
array[ 2 ] = 2
array[ 3 ] = 3
array[ 4 ] = 4
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o calloc  - Reserve and Initialize Storage
o _debug_malloc - Reserve Storage Blocks
o free  - Release Storage Blocks
o _msize - Return Number of Bytes Allocated
o realloc  - Change Reserved Storage Block Size
o _tmalloc - Reserve Tiled Storage Block
o malloc.h
o stdlib.h


ΓòÉΓòÉΓòÉ 6.150. _matherr - Process Math Library Errors ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h>

int _matherr(struct exception *x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

You can use the _matherr function to process errors generated by the functions
in the math library. The math functions call _matherr whenever they detect an
error. The _matherr function supplied with the C/C++ Tools library performs no
error handling and returns 0 to the calling function.

You can provide a different definition of the _matherr function to carry out
special error handling. Be sure to use the /NOE link option, if you are using
your own _matherr function. For the C/C++ Tools compiler, you can use the /B
option on the icc command line to pass the /NOE option to the linker, as in the
following:

   icc /B"/NOE" yourfile.c

When an error occurs in a math routine, _matherr is called with a pointer to
the following structure (defined in <math.h>) as an argument:

   struct exception {
       int type;
       char *name;
       double arg1, arg2, retval;
   };

The type variable specifies the type of math error. It is one of the following
values, defined in <math.h>:

Value          Meaning
DOMAIN         Argument domain error
OVERFLOW       Overflow range error
UNDERFLOW      Underflow range error
TLOSS          Total loss of significance
PLOSS          Partial loss of significance
SING           Argument singularity.

Because PLOSS is used by the C/2 compiler, it is provided to prevent errors
during compiling. The C/C++ Tools compiler does not actually generate this
value.

The name is a pointer to a null-ended string containing the name of the
function that caused the error. The arg1 and arg2 variables specify the
argument values that caused the error. If only one argument is given, it is
stored in arg1.

The retval is the default return value; you can change the return value. The
return value from _matherr must specify whether or not an error actually
occurred. If _matherr returns 0, an error message appears, and errno is set to
an appropriate error value. If _matherr returns a nonzero value, no error
message appears and errno remains unchanged.

Example of _matherr


ΓòÉΓòÉΓòÉ <hidden> Example of _matherr ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example is a definition that you can create to handle errors from the log
or log10 functions. The arguments to these logarithmic functions must be
positive double values. This routine processes a negative value in an argument
(a domain error) by returning the log of its absolute value. It suppresses the
error message normally displayed when this error occurs. If the error is a zero
argument or if some other routine produced the error, the example takes the
default actions.

                                                                        *
************************************************************************/

/*                                                      */
/*   Note: Use "icc /B"/NOE" yourfile.c" to compile */
/*   and link this example.                             */
/*                                                      */

#include <math.h>
#include <string.h>
#include <stdio.h>

int main(void)
{
     int value;

     printf("Trying to evaluate log10(-1000.00) will create
             a math exception.\n");
     value = log10(-1000.00);
     printf("The _matherr() exception handler evaluates
             the expression to\n");
     printf("log10(-1000.00) = %d\n", value);

     return 0;
}


int _matherr(struct exception *x)
{
    printf("inside _matherr\n");
    if (x->type == DOMAIN)
    {
        if (strcmp(x->name, "log") == 0)
        {
            x->retval = log(-(x->arg1));
            return(1);
        }
        else if (strcmp(x->name, "log10") == 0)
        {
            x->retval = log10(-(x->arg1));
            return(1);
        }
    }
    return 0;     /* Use default actions */


/********************  The output should be similar to:  ****************

   Trying to evaluate log10(-1000.00) will create a math exception.
   inside _matherr
   The _matherr() exception handler evaluates the expression to
   log10(-1000.00) = 3
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o log  - Calculate Natural Logarithm
o log10  - Calculate Base 10 Logarithm
o math.h


ΓòÉΓòÉΓòÉ 6.151. max - Return Larger of Two Values ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

type max(type a, type b);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The max macro compares two values and determines the larger of the two. The
data type can be any arithmetic data type, signed or unsigned.  Both arguments
must have the same type for each call to max.

Note:  Because max is a macro, if the evaluation of the arguments contains side
effects (post-increment operators, for example), the results of both the side
effects and the macro will be undefined.

The max macro returns the larger of the two values.

Example of max


ΓòÉΓòÉΓòÉ <hidden> Example of max ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example prints the larger of the two values, a and b.

                                                                        *
************************************************************************/

#include <stdlib.h>
#include <stdio.h>

int main (void)
{
    int a = 10;
    int b = 21;

    printf ("The larger of %d and %d is %d\n", a, b, max(a, b));

    return 0;

    /* The expected output is:

       The larger of 10 and 21 is 21  */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o min - Return Lesser of Two Values
o stdlib.h


ΓòÉΓòÉΓòÉ 6.152. mblen  - Multibyte String Length ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

int mblen(const char *string, size_t n);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The mblen function determines the length in bytes of the multibyte character
pointed to by string. A maximum of n bytes is examined.

If string is NULL, the mblen function returns:

o Nonzero when DBCS-host code (EBCDIC systems) is used
o Zero otherwise.

If string is not NULL, the mblen function returns:

o Zero if string points to the null character
o The number of bytes comprising the multibyte character
o -1 if string does not point to a valid multibyte character.

Example of mblen


ΓòÉΓòÉΓòÉ <hidden> Example of mblen ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses mblen and mbtowc to convert a multibyte character into a
single wide character.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>

int length, temp;
char string [6] = "w";
wchar_t arr[6];

int main(void)

{
   /* Set string to point to a multibyte character  */
   .
   .
   .
   length = mblen(string, MB_CUR_MAX);
   temp = mbtowc(arr,string,length);
   printf("wide character string: %ls",arr);
}


ΓòÉΓòÉΓòÉ <hidden> Related Infromation ΓòÉΓòÉΓòÉ

o mbtowc  - Convert Multibyte Character to wchar_t
o mbstowcs  - Convert Multibyte Characters to wchar_t Characters
o strlen  - Determine String Length
o wcslen  - Calculate Length of wchar_t String
o wctomb  - Convert wchar_t Character to Multibyte Character
o stdlib.h


ΓòÉΓòÉΓòÉ 6.153. mbstowcs  - Convert Multibyte Characters to wchar_t Characters ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

size_t mbstowcs(wchar_t *pwc, const char *string, size_t n);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The mbstowcs function determines the length of the sequence of the multibyte
characters pointed to by string.  It then stores the code for the sequence of
multibyte characters in the wchar_t object pointed to by pwc.  A maximum of n
wchar_t characters is examined.

The mbstowcs function returns the number of wchar_t characters generated not
including any terminating zero codes.  If a multibyte character that is not
valid is encountered, the function returns (size_t)-1.

Example of mbstowcs


ΓòÉΓòÉΓòÉ <hidden> Example of mbstowcs ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses mblen and mbstowcs to convert a multibyte character string
into a wide character string.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>

int length, temp;
char string [80];
wchar_t arr[80];

int main(void)
{
   /* Set string to point to a multibyte character string. */
   .
   .
   .
   length = mblen(string, MB_CUR_MAX);
   temp = mbstowcs(arr,string,length);
   printf("wide character string: %ls",arr);
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o mblen  - Multibyte String Length
o mbtowc  - Convert Multibyte Character to wchar_t
o wcslen  - Calculate Length of wchar_t String
o wcstombs  - Convert wchar_t String to Multibyte Character String
o stdlib.h


ΓòÉΓòÉΓòÉ 6.154. mbtowc  - Convert Multibyte Character to wchar_t ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

int mbtowc(wchar_t *pwc, const char *string, size_t n);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The mbtowc function first determines the length of the multibyte character
pointed to by string.  It then stores the code for the multibyte character in
the wchar_t object pointed to by pwc.  A maximum of n bytes is examined.

If string is NULL, the mbtowc function returns:

o Nonzero when DBCS-host code (EBCDIC systems) is used
o 0 otherwise.

If string is not NULL, the mbtowc function returns:

o 0 if string points to the null character
o The number of bytes comprising the converted multibyte character
o -1 if string does not point to a valid multibyte character.

Example of mbtowc


ΓòÉΓòÉΓòÉ <hidden> Example of mbtowc ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses mblen and mbtowc to convert a multibyte character into a
single wide character.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>

int length, temp;
char string [6];
wchar_t arr[6];

int main(void)
{
   /* Set string to point to a multibyte character. */
   .
   .
   .
   length = mblen(string, MB_CUR_MAX);
   temp = mbtowc(arr,string,length);
   printf("wide character string: %ls",arr);
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o mblen  - Multibyte String Length
o mbstowcs  - Convert Multibyte Characters to wchar_t Characters
o wcslen  - Calculate Length of wchar_t String
o wctomb  - Convert wchar_t Character to Multibyte Character
o stdlib.h


ΓòÉΓòÉΓòÉ 6.155. memccpy - Copy Bytes ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>     /* also defined in <memory.h> */

void *memccpy(void *dest, void *src, int c, unsigned cnt);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The memccpy function copies bytes from src to dest up to and including the
first occurrence of the character c or until cnt bytes have been copied,
whichever comes first.

If the character c is copied, memccpy returns a pointer to the byte in dest
that immediately follows the character. If c is not copied, memccpy returns
NULL. <memory.h>)

Example of memccpy


ΓòÉΓòÉΓòÉ <hidden> Example of memccpy ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example copies up to 55 characters, or until it copies the '.' character,
from the source to the buffer.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

char source[60];
char result[60];

int main(void)
{
    memcpy(source,"This is the string. This part won't be copied.", 55);

    if (memccpy(result, source, '.', 55) == NULL)
    {
       printf("Error in copying source.\n");
       exit(1);
    }
    else
       printf("%s\n", result);

    return 0;

    /* The expected output is:

       This is the string.     */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o memchr  - Search Buffer
o memcmp  - Compare Buffers
o memcpy  - Copy Bytes
o memmove  - Copy Bytes
o memset  - Set Bytes to Value
o memory.h
o string.h


ΓòÉΓòÉΓòÉ 6.156. memchr  - Search Buffer ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>  /* also defined in <memory.h> */

void *memchr(const void *buf, int c, size_t count);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA, Extension

The memchr function searches the first count bytes of buf for the first
occurrence of c converted to an unsigned character.  The search continues until
it finds c or examines count bytes.

The memchr function returns a pointer to the location of c in buf.  It returns
NULL if c is not within the first count bytes of buf.

Example of memchr


ΓòÉΓòÉΓòÉ <hidden> Example of memchr ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example finds the first occurrence of "x" in the string that you provide.
If it is found, the string that starts with that character is printed.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>

int main(int argc, char ** argv)
{
  char * result;

  if ( argc != 2 )
    printf( "Usage: %s string\n", argv[0] );
  else
  {
    if ((result = memchr( argv[1], 'x', strlen(argv[1])) ) != NULL)
      printf( "The string starting with x is %s\n", result );
    else
      printf( "The letter x cannot be found in the string\n" );
  }
}

/********************  Output should be similar to:  **************

The string starting with x is xing
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o memccpy - Copy Bytes
o memicmp - Compare Bytes
o memmove  - Copy Bytes
o memset  - Set Bytes to Value
o strchr  - Search for Character
o memory.h
o string.h


ΓòÉΓòÉΓòÉ 6.157. memcmp  - Compare Buffers ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>  /* also defined in <memory.h> */

int memcmp(const void *buf1, const void *buf2, size_t count);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA, Extension

The memcmp function compares the first count bytes of buf1 and buf2 and returns
a value indicating their relationship as follows:

Value               Meaning
Less than 0         buf1 less than buf2
0                   buf1 identical to buf2
Greater than 0      buf1 greater than buf2

Example of memcmp


ΓòÉΓòÉΓòÉ <hidden> Example of memcmp ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example compares first and second arguments passed to main to determine
which, if either, is greater.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>

int main(int argc, char ** argv)
{
  int  len;
  int  result;

  if ( argc != 3 )
  {
     printf( "Usage: %s string1 string2\n", argv[0] );
  }
  else
  {
     /* Determine the length to be used for comparison */
     if (strlen( argv[1] ) < strlen( argv[2] ))
       len = strlen( argv[1] );
     else
       len = strlen( argv[2] );

     result = memcmp( argv[1], argv[2], len );

     printf( "When the first %i characters are compared,\n", len );
     if ( result == 0 )
       printf( "\"%s\" is identical to \"%s\"\n", argv[1], argv[2] );
     else if ( result < 0 )
       printf( "\"%s\" is less than \"%s\"\n", argv[1], argv[2] );
     else
       printf( "\"%s\" is greater than \"%s\"\n", argv[1], argv[2] );
  }
}

/****************  If the program is passed the arguments  **************
*************  firststring and secondstring,  *****
********************  output should be:  *************************

When the first 11 characters are compared,
"firststring" is less than "secondstring"
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o memccpy - Copy Bytes
o memchr  - Search Buffer
o memcpy  - Copy Bytes
o memicmp - Compare Bytes
o memmove  - Copy Bytes
o memset  - Set Bytes to Value
o strcmp  - Compare Strings
o memory.h
o string.h


ΓòÉΓòÉΓòÉ 6.158. memcpy  - Copy Bytes ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>  /* also defined in <memory.h> */

void *memcpy(void *dest, const void *src, size_t count);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA, Extension

The memcpy function copies count bytes of src to dest.  For memcpy, the
behavior is undefined if copying takes place between objects that overlap.
(The memmove function allows copying between objects that may overlap.)

The memcpy function returns a pointer to dest.

Example of memcpy


ΓòÉΓòÉΓòÉ <hidden> Example of memcpy ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example copies the contents of source to target.

                                                                        *
************************************************************************/

#include <string.h>
#include <stdio.h>

#define MAX_LEN 80

char source[ MAX_LEN ] = "This is the source string";
char target[ MAX_LEN ] = "This is the target string";

int main(void)
{
  printf( "Before memcpy, target is \"%s\"\n", target );
  memcpy( target, source, sizeof(source));
  printf( "After memcpy, target becomes \"%s\"\n", target );
}

/*********************  Expected output:  ************************

Before memcpy, target is "This is the target string"
After memcpy, target becomes "This is the source string"
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o memccpy - Copy Bytes
o memchr  - Search Buffer
o memcmp  - Compare Buffers
o memicmp - Compare Bytes
o memmove  - Copy Bytes
o strcpy  - Copy Strings
o memory.h
o string.h


ΓòÉΓòÉΓòÉ 6.159. memicmp - Compare Bytes ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>    /* Also defined in <memory.h> */

int memicmp(void *buf1, void *buf2, unsigned int cnt);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The memicmp function compares the first cnt bytes of buf1 and buf2 without
regard to the case of letters in the two buffers.  The function converts all
uppercase characters into lowercase and then performs the comparison.

The return value of memicmp indicates the result as follows:

Value                 Meaning
Less than 0           buf1 less than buf2
0                     buf1 identical to buf2
Greater than 0        buf1 greater than buf2.

Example of memicmp


ΓòÉΓòÉΓòÉ <hidden> Example of memicmp ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example copies two strings that each contain a substring of 29 characters
that are the same except for case. The example then compares the first 29 bytes
without regard to case.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>

char first[100], second[100];

int main(void)
{
    int result;

    strcpy(first, "Those Who Will Not Learn From History");
    strcpy(second,"THOSE WHO WILL NOT LEARN FROM their mistakes");

    printf("Comparing the first 29 characters of two strings.\n");
    result = memicmp(first, second, 29);

    printf("The first 29 characters of String 1 are ");
    if (result < 0)
       printf("less than String 2.\n");
    else
       if (result == 0)
          printf("equal to String 2.\n");
       else
          printf("greater than String 2.\n");

    return 0;

    /* The expected output is:

       Comparing the first 29 characters of two strings.
       The first 29 characters of String 1 are equal to String 2  */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o memchr  - Search Buffer
o memcmp  - Compare Buffers
o memcpy  - Copy Bytes
o memmove  - Copy Bytes
o memset  - Set Bytes to Value
o memory.h
o string.h


ΓòÉΓòÉΓòÉ 6.160. memmove  - Copy Bytes ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>  /* also defined in <memory.h> */

void *memmove(void *dest, const void *src, size_t count);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA, Extension

The memmove function copies count bytes of src to dest. The memmove function
allows copying between objects that may overlap as if src is first copied into
a temporary array.

The memmove function returns a pointer to dest.

Example of memmove


ΓòÉΓòÉΓòÉ <hidden> Example of memmove ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example copies the word shiny from position target + 2 to position target
+ 8.

                                                                        *
************************************************************************/

#include <string.h>
#include <stdio.h>

#define SIZE    21

char target[SIZE] = "a shiny white sphere";

int main( void )
{
  char * p = target + 8;  /* p points at the starting character
                          of the word we want to replace */
  char * source = target + 2; /* start of "shiny" */

  printf( "Before memmove, target is \"%s\"\n", target );
  memmove( p, source, 5 );
  printf( "After memmove, target becomes \"%s\"\n", target );
}

/*********************  Expected output:  ************************

Before memmove, target is "a shiny white sphere"
After memmove, target becomes "a shiny shiny sphere"
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o memccpy - Copy Bytes
o memchr  - Search Buffer
o memcmp  - Compare Buffers
o memcpy  - Copy Bytes
o memicmp - Compare Bytes
o memset  - Set Bytes to Value
o strcpy  - Copy Strings
o memory.h
o string.h


ΓòÉΓòÉΓòÉ 6.161. memset  - Set Bytes to Value ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>  /* also defined in <memory.h> */

void *memset(void *dest, int c, size_t count);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA, Extension

The memset function sets the first count bytes of dest to the value c.  The
value of c is converted to an unsigned character.

The memset function returns a pointer to dest.

Example of memset


ΓòÉΓòÉΓòÉ <hidden> Example of memset ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example sets 10 bytes of the buffer to "A" and the next 10 bytes to "B".

                                                                        *
************************************************************************/

#include <string.h>
#include <stdio.h>

#define  BUF_SIZE  20

int main(void)
{
   char buffer[BUF_SIZE + 1];
   char *string;

   memset(buffer, 0, sizeof(buffer));
   string = memset(buffer,'A', 10);
   printf("\nBuffer contents: %s\n", string);
   memset(buffer+10, 'B', 10);
   printf("\nBuffer contents: %s\n", buffer);
}

/*******************  Output should be similar to:  ***************

Buffer contents: AAAAAAAAAA

Buffer contents: AAAAAAAAAABBBBBBBBBB
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o memccpy - Copy Bytes
o memcpy  - Copy Bytes
o memicmp - Compare Bytes
o memmove  - Copy Bytes
o memory.h
o strnset - strset - Set Characters in String
o string.h


ΓòÉΓòÉΓòÉ 6.162. min - Return Lesser of Two Values ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

type min(type a, type b);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The min macro compares two values and determines the smaller of the two. The
data type can be any arithmetic data type, signed or unsigned. The type must be
the same for both arguments to min.

Note:  Because min is a macro, if the evaluation of the arguments contains side
effects (post-increment operators, for example), the results of both the side
effects and the macro will be undefined.

The min macro returns the smaller of the two values.

Example of min


ΓòÉΓòÉΓòÉ <hidden> Example of min ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example prints the smaller of the two values, a and b.

                                                                        *
************************************************************************/

#include <stdlib.h>
#include <stdio.h>

int main(void)
{
    int a = 10;
    int b = 21;

    printf ("The smaller of %d and %d is %d\n", a, b, min (a, b));

    return 0;

    /* The expected output is:

       The smaller of 10 and 21 is 10  */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o max - Return Larger of Two Values
o stdlib.h


ΓòÉΓòÉΓòÉ 6.163. _mkdir - Create New Directory ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <direct.h>

int _mkdir(char *pathname);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _mkdir function creates a new directory with the specified pathname.
Because only one directory can be created at a time, only the last component of
pathname can name a new directory.

The _mkdir function returns the value 0 if the directory was created.  A return
value of -1 indicates an error, and errno is set to one of the following
values:

Value          Meaning
EACCESS        The directory was not created;  the given name is the name of an
               existing file, directory, or device.
ENOENT         The pathname was not found.

Example of _mkdir


ΓòÉΓòÉΓòÉ <hidden> Example of _mkdir ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example creates two new directories:  one at the root on drive B:, and one
in the tmp subdirectory of the current working directory.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <direct.h>
#include <string.h>

int main(void)
{
    char *dir1, *dir2;

/*  Create the directory "aleng" in the root directory of the C: drive. */
    dir1 = "c:\\aleng";
    if ((_mkdir(dir1)) == 0)
        printf("%s directory was created.\n",dir1);
    else
        printf("%s directory was not created.\n",dir1);

/*  Create the subdirectory "simon" in the current directory. */
    dir2 = "simon";
    if ((_mkdir(dir2)) == 0)
        printf("%s directory was created.\n",dir2);
    else
        printf("%s directory was not created.\n",dir2);

/*  Remove the directory "aleng" from the root directory
                   of the C: drive. */
    printf("Removing directory 'aleng' from the root directory.\n");

    if (_rmdir(dir1))
       perror(NULL);
    else
       printf("%s directory was removed.\n",dir1);

/*  Remove the subdirectory "simon" from the current directory. */
    printf("Removing subdirectory 'simon' from the current directory.\n");

    if (_rmdir(dir2))
       perror(NULL);
    else
       printf("%s directory was removed.\n",dir2);

    return 0;

/*************** The output should be similar to:  ********************

   c:\aleng directory was created.
   simon directory was created.
   Removing directory 'aleng' from the root directory.
   c:\aleng directory was removed.
   Removing subdirectory 'simon' from the current directory.
   simon directory was removed.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ


o _chdir - Change Current Working Directory
o _getcwd - Get Path Name of Current Directory
o _getdcwd - Get Full Path Name of Current Directory
o _rmdir - Remove Directory
o direct.h


ΓòÉΓòÉΓòÉ 6.164. mktime  - Convert Local Time ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <time.h>

time_t mktime(struct tm *time);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The mktime function converts local time, stored as a structure pointed to by
time, into a time_t structure suitable for use with other time functions. The
values of some structure elements pointed to by time are not restricted to the
ranges shown on gmtime.

The values of tm_wday and tm_yday passed to mktime are ignored and are assigned
their correct values on return.

The mktime function returns the calendar time having type time_t.  The value
(time_t)(-1) is returned if the calendar time cannot be represented.

Note:  The time and date functions begin at 00:00:00 Coordinated Universal
Time, January 1, 1970.

Example of mktime


ΓòÉΓòÉΓòÉ <hidden> Example of mktime ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example prints the day of the week that is 40 days and 16 hours from the
current date.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <time.h>

char *wday[] = { "Sunday", "Monday", "Tuesday", "Wednesday",
                 "Thursday", "Friday", "Saturday" };

int main(void)
{
  time_t t1, t3;
  struct tm *t2;

  t1 = time(NULL);
  t2 = localtime(&t1);
  t2 -> tm_mday += 40;
  t2 -> tm_hour += 16;
  t3 = mktime(t2);

  printf("40 days and 16 hours from now, it will be a %s \n",
          wday[t2 -> tm_wday]);
}

/*******************  Output should be similar to:  ***************

40 days and 16 hours from now, it will be a Sunday
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o asctime  - Convert Time
o ctime  - Convert Time
o gmtime  - Convert Time
o localtime  - Convert Time
o time  - Determine Current Time
o time.h


ΓòÉΓòÉΓòÉ 6.165. modf  - Separate Floating-Point Value ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h>

double modf(double x, double *intptr);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The modf function breaks down the floating-point value x into fractional and
integral parts.  The signed fractional portion of x is returned.  The integer
portion is stored as a double value pointed to by intptr.  Both the fractional
and integral parts are given the same sign as x.

Example of modf


ΓòÉΓòÉΓòÉ <hidden> Example of modf ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example breaks the floating-point number -14.876 into its fractional and
integral components.

                                                                        *
************************************************************************/

#include <math.h>
#include <stdio.h>

int main(void)
{
   double x, y, d;

   x = -14.876;
   y = modf(x, &d);

   printf("x = %lf\n", x);
   printf("Integral part = %lf\n", d);
   printf("Fractional part = %lf\n", y);
}

/****************  Output should be similar to:  ******************

x = -14.876000
Integral part = -14.000000
Fractional part = -0.876000
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fmod  - Floating-Point Remainder
o frexp  - Separate Floating-Point Value
o ldexp  - Multiply by a Power of Two
o math.h


ΓòÉΓòÉΓòÉ 6.166. _msize - Return Number of Bytes Allocated ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>  or ##include <malloc.h>

size_t _msize(void *ptr)


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _msize function returns the number of bytes that were allocated to the
pointer argument passed. This function requires a pointer that was returned
from any of the calloc, malloc, realloc, _tcalloc, _tmalloc, and _trealloc
functions.

You cannot pass the argument of an object that has been freed.

The _msize function returns the number of bytes allocated. If the argument is
not a valid pointer returned from the malloc, calloc, and realloc functions,
the return value is undefined. If NULL is passed, _msize returns 0.

Example of _msize


ΓòÉΓòÉΓòÉ <hidden> Example of _msize ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example displays the size of an allocated object from malloc.

                                                                        *
************************************************************************/


#include <stdio.h>
#include <stdlib.h>

int main(void)
{

 char *myptr;

 /* allocate an object */
 myptr = malloc(5);

 printf("The size of the allocated object is %u\n",_msize(myptr));

 return(0);

 /************** The output should be:  ****************************

     The size of the allocated object is 5

 */
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o calloc  - Reserve and Initialize Storage
o malloc  - Reserve Storage Block
o realloc  - Change Reserved Storage Block Size
o _tcalloc - Reserve Tiled Storage Block
o _tmalloc - Reserve Tiled Storage Block
o _trealloc - Reallocate Tiled Storage Block
o malloc.h
o stdlib.h


ΓòÉΓòÉΓòÉ 6.167. _onexit - Record Termination Function ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

onexit_t _onexit(onexit_t func);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _onexit function records the address of a function func to call when the
program ends normally.  Successive calls to _onexit create a stack of functions
that run in a last-in, first-out order. The functions passed to _onexit cannot
take parameters.

You can record up to 32 termination functions with calls to _onexit and atexit.
If you exceed 32 functions, _onexit returns the value NULL.

Note:  For portability, use the ANSI-standard atexit function, which is
equivalent to _onexit.

If successful, _onexit returns a pointer to the function; otherwise, it returns
a NULL value.

Example of _onexit


ΓòÉΓòÉΓòÉ <hidden> Example of _onexit ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example specifies and defines four distinct functions that run
consecutively at the completion of main:

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>

int fn1(void)
{
    printf("next.\n");
}

int fn2(void)
{
    printf("run ");
}

int fn3(void)
{
    printf("is ");
}

int fn4(void)
{
    printf("This ");
}

int main(void)
{
    _onexit(fn1);
    _onexit(fn2);
    _onexit(fn3);
    _onexit(fn4);
    printf("This is run first.\n");

    return 0;

/*****************  The output should be similar to:  *******************

   This is run first.
   This is run next.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o abort  - Stop a Program
o atexit  - Record Program Termination Function
o exit  - End Program
o _exit - End Process
o stdlib.h


ΓòÉΓòÉΓòÉ 6.168. _open - Open File ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <io.h>
#include <fcntl.h>
#include <sys\stat.h>

int _open(char *pathname, int oflag, int pmode);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _open function opens the file specified by pathname and prepares the file
for subsequent reading or writing as defined by oflag. The _open function can
also prepare the file for reading and writing. The oflag is an integer
expression formed by combining one or more of the following constants, defined
in <fcntl.h>. When more than one constant is given, the constants are joined
with the bitwise OR operator (|).

Oflag         Meaning
O_APPEND      Reposition the file pointer to the end of the file before every
              write operation.
O_CREAT       Create and open a new file.  This flag has no effect if the file
              specified by pathname exists.
O_EXCL        Return an error value if the file specified by pathname exists.
              This flag applies only when used with O_CREAT.
O_RDONLY      Open the file for reading only.  If this flag is given, neither
              O_RDWR nor O_WRONLY can be given.
O_RDWR        Open the file for reading and writing.  If this flag is given,
              neither O_RDONLY nor O_WRONLY can be given.
O_TRUNC       Open and truncate an existing file to 0 length. The file must
              have write permission. The contents of the file are destroyed,
              and O_TRUNC cannot be specified with O_RDONLY.
O_WRONLY      Open the file for writing only.  If this flag is given, neither
              O_RDONLY nor O_RDWR can be given.
O_BINARY      Open the file in binary (untranslated) mode. (See fopen.)
O_TEXT        Open the file in text (translated) mode. (See fopen.)

If neither O_BINARY or O_TEXT is specified, the default will be O_TEXT; it is
an error to specify both O_BINARY and O_TEXT.

You must specify one of the access mode flags, O_RDONLY, O_WRONLY, or O_RDWR.
There is no default.

Warning: Use O_TRUNC with care; it destroys the complete contents of an
existing file.

The pmode argument is an integer expression containing one or both of the
constants S_IWRITE and S_IREAD, defined in <sys\stat.h>. The pmode is required
only when O_CREAT is specified. If the file exists, pmode is ignored.
Otherwise, pmode specifies the permission settings for the file. These are set
when the new file is closed for the first time. The meaning of the pmode
argument is as follows:

Value                   Meaning
S_IWRITE                Writing permitted
S_IREAD                 Reading permitted
S_IREAD | S_IWRITE      Reading and writing permitted.

If write permission is not given, the file is read-only. Under the OS/2
operating system, all files are readable; you cannot give write-only
permission. The modes S_IWRITE and S_IREAD | S_IWRITE are equivalent.

The _open function applies the current file permission mask to pmode before
setting the permissions.  (See _umask - Sets File Mask of Current Process).

The _open function returns a file handle for the opened file. A return value of
-1 indicates an error, and errno is set to one of the following values:

Value          Meaning
EACCESS        The given pathname is a directory; or the file is read-only but
               an open for writing was attempted; or a sharing violation
               occurred.
EEXIST         The O_CREAT and O_EXCL flags are specified, but the named file
               already exists.
EMFILE         No more file handles are available.
EINVAL         An incorrect argument was passed.
ENOENT         The file or pathname were not found.
EOS2ERR        The call to the operating system was not successful.

Example of _open


ΓòÉΓòÉΓòÉ <hidden> Example of _open ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example tries to open the file edopen.dat by creating it as a new file,
truncating it if it exists and opening it so it can be read and written to. The
_open command issued also grants permission to read from and write to the file.

                                                                        *
************************************************************************/

#include <io.h>
#include <stdio.h>
#include <fcntl.h>
#include <sys\stat.h>

int main(void)
{
   int fh;

   if ( -1 == (fh = _open("edopen.dat",
      O_CREAT | O_TRUNC | O_RDWR,
      S_IREAD | S_IWRITE)))
   {
      perror("Unable to open edopen.dat");
      return 1;
   }

   printf("File was successfully opened.\n");

   if (-1 == _close(fh))
   {
      perror("close error");
      return 1;
   }
   return 0;

   /* The expected ouptut is:

      File was successfully opened.  */
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _close - Closes File Associated with Handle
o _creat - Create New File
o _fdopen - Associates Input Or Output With File
o fopen  - Open Files
o _sopen - Open Shared File
o _umask - Sets File Mask of Current Process
o fcntl.h
o io.h
o sys\stat.h


ΓòÉΓòÉΓòÉ 6.169. _outp - Write Byte to Output Port ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <conio.h>             /*  Declared in both  */
#include <builtin.h>

int _outp( const unsigned int port, const int value );


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _outp function writes a byte value to the specified port. The port number
must be an unsigned int value within the range 0 to 65 535 inclusive. The byte
value must be within the range 0 to 255 inclusive.

Because it is a built-in function and has no backing code in the library:

o You cannot take the address of _outp.
o You cannot parenthesize an _outp function call, because parentheses specify a
  call to the backing code for the function.

You can run code containing this function only at ring zero. Otherwise, an
invalid instruction exception is generated.

The _outp function returns the integer value that was output to the specified
port. There is no error return value and this function does not set errno.

Example of _outp


ΓòÉΓòÉΓòÉ <hidden> Example of _outp ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses the _outp function to write a byte to a specified output port
and return the data written.

                                                                        *
************************************************************************/

#include <builtin.h>
#define LOWER  0
#define UPPER1 255
#define UPPER2 65535

int Add1(int j);
static int g;
enum fruit {apples=10, bananas, cantalopes};
enum fruit f = cantalopes;

int arr[]={cantalopes, bananas, apples};

struct
   {
   int i;
   char ch;
   } st;

int main(void)
   {
   static int i;
   volatile const int c = 0;
   st.i = c - bananas;

   g = _outp(LOWER,apples);

   i = _outp(255, 0);
                                     /* ============================= */
                                     /* Types of port number passed : */
                                     /* ----------------------------- */
   i = _outp(UPPER2,UPPER1);         /* - #define constant            */
   i = _outp(st.i, bananas);         /* - element of structure        */
   i = _outp(f,arr[1]);              /* - enumerated variable         */
   i = _outp(_inp(arr[2]),apples);   /* - return value from a         */
                                     /*   builtin function call       */
                                     /* ----------------------------- */

   i = _outp(_outp(apples,Add1(LOWER)),6);

   return 0;
}


int Add1(int j)
   {
   j += 1;
   return j;
   }


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _inp - Read Byte from Input Port
o _inpw - Read Unsigned Short from Input Port
o _inpd - Read Double Word from Input Port
o _outpw - Write Word to Output Port
o _outpd - Write Double Word to Output Port


ΓòÉΓòÉΓòÉ 6.170. _outpd - Write Double Word to Output Port ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <conio.h>          /*  Declared in both  */
#include <builtin.h>

unsigned long _outpd( const unsigned int port, const unsigned long value );


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _outpd function writes an unsigned long value to the specified port. The
port number must be a value within the range 0 to 65 535 inclusive. The
unsigned long value must be within the range 0 to 4 294 967 295 inclusive.

Because it is a built-in function and has no backing code in the library:

o You cannot take the address of _outpd.
o You cannot parenthesize an _outpd function call, because parentheses specify
  a call to the backing code for the function in the library, and _outpd has no
  backing code.

You can run code containing this function only at ring zero. Otherwise, an
invalid instruction exception is generated.

The _outpd function returns the unsigned long value that was output to the
specified port.  There is no error return value and this function does not set
errno.

Example of _outpd


ΓòÉΓòÉΓòÉ <hidden> Example of _outpd ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses the _outpd function to write a doubleword value to a
specified output port and return the data written.

                                                                        *
************************************************************************/

#include <builtin.h>
#define LOWER  0
#define UPPER1 65535
#define UPPER2 4294967295

int Add1(int j);
volatile int g;
enum fruit {apples=10, bananas, cantalopes};
enum fruit f = cantalopes;

int arr[]={cantalopes, bananas, apples};

union
   {
   volatile int i;
   volatile char ch;
   } un;

int main(void)
   {
   unsigned long l;
   volatile const short c = 0;
   un.i = bananas * f;

   g = _outpd(0,LOWER);

                                     /* ============================= */
                                     /* Types of port number passed : */
                                     /* ----------------------------- */
   l = _outpd(UPPER1, UPPER2);       /* - #define constant            */
   l = _outpd(un.i ,f);              /* - element of union            */
   l = _outpd(Add1(c), apples);      /* - return value from a         */
                                     /*   function call               */
                                     /* ----------------------------- */

   l = _outpd(_outpw(255,Add1(LOWER)),6);


   return 0;
}

int Add1(int j)
   {
   j += 1;
   return j;
   }


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _inp - Read Byte from Input Port
o _inpw - Read Unsigned Short from Input Port
o _inpd - Read Double Word from Input Port
o _outp - Write Byte to Output Port
o _outpw - Write Word to Output Port


ΓòÉΓòÉΓòÉ 6.171. _outpw - Write Word to Output Port ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <conio.h>        /*  Declared in both  */
#include <builtin.h>

unsigned short _outpw( const unsigned int port,
const unsigned short word );


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _outpw function writes an unsigned short word to the specified port. The
port number must be an unsigned int value within the range 0 to 65 535
inclusive. The unsigned short word must be in the range 0 to 65 535.

Because it is a built-in function and has no backing code in the library:

o You cannot take the address of _outpw.
o You cannot parenthesize a _outpw function call, because parentheses specify a
  call to the backing code for the function.

You can run code containing this function only at ring zero. Otherwise, an
invalid instruction exception is generated.

This function returns the unsigned short value that was output to the specified
port. There is no error return value and this function does not set errno.

Example of _outpw


ΓòÉΓòÉΓòÉ <hidden> Example of _outpw ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses the _outpw function to write an unsigned short value to a
specified output port and return the data written.

                                                                        *
************************************************************************/

#include <builtin.h>
#define LOWER 0
#define UPPER 65535

int Add1(int j);
unsigned int g;

int main(void)
   {
   enum fruit {apples=10, bananas, cantalopes};
   enum fruit f = cantalopes;

   int arr[]={cantalopes, bananas, apples};

   unsigned short s;
   static int i = 0;
   volatile const int c = 255;

   g = _outpw(cantalopes, i);

                                     /* ============================= */
                                     /* Types of port number passed : */
                                     /* ----------------------------- */
   s = _outpw(UPPER, LOWER);         /* - #define constant            */
   s = _outpw(c, Add1(255));         /* - constant                    */
   s = _outpw(_inpw(arr[2]),apples); /* - return value from a         */
                                     /*   builtin function call       */
                                     /* ----------------------------- */

   s = _outpw(_outpw(bananas ,UPPER),6);

   return 0;
}

int Add1(int j)
   {
   j += 1;
   return j;
   }


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _inp - Read Byte from Input Port
o _inpw - Read Unsigned Short from Input Port
o _inpd - Read Double Word from Input Port
o _outp - Write Byte to Output Port
o _outpd - Write Double Word to Output Port


ΓòÉΓòÉΓòÉ 6.172. __parmdwords - Get Number of dwords in Parameter List ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>  /* also defined in <builtin.h> */

unsigned char __parmdwords(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The __parmdwords function returns the hidden parameter passed in the AL
register for _System linkage calls. The hidden parameter contains the size of
the parameter list that is passed to the function containing the call to
__parmdwords.  The size is in doublewords (dwords), and can be between 0 and
255. If the parameter list is larger than 255 dwords, the hidden parameter
contains the 8 least significant bits of the value.

This function allows the implementer of a function to increase the number of
parameters the function takes without changing the name of the function. The
new version of the function can call __parmdwords to check the size of the
parameter list and determine whether the call was written for the earlier
version of the function or for the extended version.

Warning: The __parmdwords function has several limitations:

 1. Because it is a built-in function and has no backing code in the library:

   o You cannot take the address of __parmdwords.
   o You cannot parenthesize a __parmdwords function call because parentheses
     specify a call to the backing code for the function.

 2. The __parmdwords function can only be used for functions with the _System
    linkage type. If you use it with other linkage types, an error message is
    generated, and your program will not compile correctly.

The __parmdwords function returns the size of the parameter list passed to the
function in units of dwords.

Example of __parmdwords


ΓòÉΓòÉΓòÉ <hidden> Example of __parmdwords ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example shows two versions of an API that prints out messages.  The second
version uses __parmdwords to determine whether the call was intended for the
original or the updated version.

                                                                        *
************************************************************************/

#include <stdlib.h>
#include <stdio.h>

#pragma linkage(ErrorHandler, system)
int ErrorHandler(int MessageNum, int Severity);
/* Extended version of API */

/* Old version API prototype --  int ErrorHandler(int MessageNum); */

#define MESSAGE1 1
#define MESSAGE2 2

#define INFORMATIONAL 3
#define WARNING       2
#define ERROR         1
#define FATAL         0

int ErrorHandler(int MessageNum, int Severity)
{
   int rc = 0;
   switch ((int)__parmdwords())
   {
   case 2: /* Extended version with Severity parameter */
      switch (Severity)
      {
         case FATAL:
            printf("Fatal Error:");
            break;
         case ERROR:
            printf("Error:");
            break;
         case WARNING:
            printf("Warning:");
            break;
         case INFORMATIONAL:
            printf("Informational:");
            break;
         default:
            rc = 1;
            printf("Bad Severity Number");
      }
      /* intentional fall through */
   case 1: /* Old version of API without Severity parameter */
      switch (MessageNum)
      {
         case MESSAGE1:
            printf("Some immensely profound message\n");
            break;
         case MESSAGE2:
            printf("Some other immensely profound message\n");
            break;
         default:
            printf("Very trivial message,
                     why not try MESSAGE1 or MESSAGE2?\n");
            rc = 1;
      }
   }
   return rc;
}

/* Old version of main:
     int main(void)
     {
        return ErrorHandler(MESSAGE1);
     }                               */

     /* The expected output from the old version is:

        Some immensely profound message              */

/* New version of main:  */

int main(void)
{
   return ErrorHandler(MESSAGE1, FATAL);

   /* The expected output is:

      Fatal Error:Some immensely profound message  */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o "Calling Conventions" in the Programming Guide
o stdlib.h


ΓòÉΓòÉΓòÉ 6.173. perror  - Print Error Message ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

void perror(const char *string);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The perror function prints an error message to stderr.  If string is not NULL
and string does not point to a null character, the string pointed to by string
is printed to the standard error stream, followed by a colon and a space.  The
message associated with the value in errno is then printed followed by a
new-line character.

To produce accurate results, you should ensure that perror is called
immediately after a library function returns with an error;  otherwise,
subsequent calls may alter the errno value.

The perror function returns no value.

Example of perror


ΓòÉΓòÉΓòÉ <hidden> Example of perror ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example tries to open a stream.  If the fopen function fails, the example
prints a message and ends the program.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
   FILE *fh;

   if ((fh = fopen("myfile.dat","r")) == NULL)
   {
      perror("Could not open data file");
      abort();
   }
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o clearerr  - Reset Error Indicators
o ferror  - Test for Read/Write Errors
o strerror  - Set Pointer to Runtime Error Message
o _strerror - Set Pointer to System Error String
o Runtime Return Codes and Messages
o stdio.h


ΓòÉΓòÉΓòÉ 6.174. pow  - Compute Power ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h>

double pow(double x, double y);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The pow function returns the value of x**y (x to the power of y). If y is 0,
pow returns the value 1.  If x is 0 and y is negative, pow sets errno to EDOM
and returns 0.  If both x and y are 0, or if x is negative and y is not an
integer, pow sets errno to EDOM, and returns 0.

If an overflow results, pow sets errno to ERANGE and

Example of pow


ΓòÉΓòÉΓòÉ <hidden> Example of pow ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example calculates the value of 2**3.

                                                                        *
************************************************************************/

#include <math.h>
#include <stdio.h>

int main(void)
{
   double x, y, z;

   x = 2.0;
   y = 3.0;
   z = pow(x,y);

   printf("%lf to the power of %lf is %lf\n", x, y, z);
}

/*****************  Output should be similar to:  *****************

2.000000 to the power of 3.000000 is 8.000000
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o exp  - Exponential Function
o _fsqrt -  Calculate Square Root
o log  - Calculate Natural Logarithm
o log10  - Calculate Base 10 Logarithm
o sqrt  - Calculate Square Root
o math.h


ΓòÉΓòÉΓòÉ 6.175. printf  - Formatted Print ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int printf(const char *format-string, argument-list);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA, Extension

The printf function formats and prints a series of characters and values to the
standard output stream stdout.  The format-string consists of ordinary
characters, escape sequences, and format specifications.  The ordinary
characters are copied in order of their appearance to stdout.  Format
specifications, beginning with a percent sign (%), determine the output format
for any argument-list following the format-string.  The format-string is a
multibyte character string beginning and ending in its initial shift state.

The format-string is read left to right.  When the first format specification
is found, the value of the first argument after the format-string is converted
and output according to the format specification.  The second format
specification causes the second argument after the format-string to be
converted and output, and so on through the end of the format-string.  If there
are more arguments than there are format specifications, the extra arguments
are evaluated and ignored.  The results are undefined if there are not enough
arguments for all the format specifications.  A format specification has the
following form:

ΓöÇΓöÇ%ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇtypeΓöÇΓöÇ
    Γöé     Γöé  Γöé     Γöé  Γöé         Γöé  Γöé   Γöé
    ΓööΓöÇΓöÇflagsΓöÇΓöÇΓöÿ  ΓööΓöÇΓöÇwidthΓöÇΓöÇΓöÿ  ΓööΓöÇΓöÇ.ΓöÇΓöÇprecisionΓöÇΓöÇΓöÿ  Γö£ΓöÇΓöÇhΓöÇΓöÇΓöñ
                           Γöé   Γöé
                           Γö£ΓöÇΓöÇLΓöÇΓöÇΓöñ
                           Γöé   Γöé
                           ΓööΓöÇΓöÇlΓöÇΓöÇΓöÿ
Each field of the format specification is a single character or number
signifying a particular format option.  The type character, which appears after
the last optional format field, determines whether the associated argument is
interpreted as a character, a string, a number, or pointer.  The simplest
format specification contains only the percent sign and a type character (for
example, %s).

The following optional fields control other aspects of the formatting:

Field       Description
flags       Justification of output and printing of signs, blanks, decimal
            points, octal, and hexadecimal prefixes, and the semantics for
            wchar_t precision unit.
width       Minimum number of characters (bytes) output.
precision   Maximum number of characters (bytes) printed for all or part of the
            output field, or minimum number of digits printed for integer
            values.
h,l,L       Size of argument expected.

If a percent sign (%) is followed by a character that has no meaning as a
format field, the character is simply copied to stdout.  For example, to print
a percent sign character, use %%.

In extended mode, printf also converts floating-point values of NaN and
infinity to the strings "NAN" or "nan" and "INFINITY" or "infinity". The case
and sign of the string is determined by the format specifiers.  See Infinity
and NaN Support for more information on infinity and NaN values.

The printf function returns the number of characters (bytes) printed.

Example of printf


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fprintf  - Write Formatted Data
o fscanf  - Read Formatted Data
o scanf  - Read Data
o sprintf  - Formatted Print to Buffer
o sscanf  - Read Data
o Infinity and NaN Support
o stdio.h


ΓòÉΓòÉΓòÉ 6.175.1. Format Specification - Types ΓòÉΓòÉΓòÉ

The type characters and their meanings are given in the following table:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CHAR- Γöé ARGUMENT  Γöé OUTPUT FORMAT                      Γöé
Γöé ACTER Γöé       Γöé                             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé d, i  Γöé Integer   Γöé Signed decimal integer.                 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé u   Γöé Integer   Γöé Unsigned decimal integer.                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé o   Γöé Integer   Γöé Unsigned octal integer.                 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé x   Γöé Integer   Γöé Unsigned hexadecimal integer, using abcdef.       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé X   Γöé Integer   Γöé Unsigned hexadecimal integer, using ABCDEF.       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé f   Γöé Double   Γöé Signed value having the form [-]dddd.dddd, where dddd  Γöé
Γöé    Γöé       Γöé is one or more decimal digits.  The number of digits   Γöé
Γöé    Γöé       Γöé before the decimal point depends on the magnitude of   Γöé
Γöé    Γöé       Γöé the number.  The number of digits after the decimal   Γöé
Γöé    Γöé       Γöé point is equal to the requested precision.        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé e   Γöé Double   Γöé Signed value having the form [-]d.dddd"e"[sign]ddd,   Γöé
Γöé    Γöé       Γöé where d is a single-decimal digit, dddd is one or more  Γöé
Γöé    Γöé       Γöé decimal digits, ddd is 2 or 3 decimal digits, and sign  Γöé
Γöé    Γöé       Γöé is + or -.                        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé E   Γöé Double   Γöé Identical to the "e" format except that "E" introduces  Γöé
Γöé    Γöé       Γöé the exponent instead of "e".               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé g   Γöé Double   Γöé Signed value printed in "f" or "e" format.  The "e"   Γöé
Γöé    Γöé       Γöé format is used only when the exponent of the value is  Γöé
Γöé    Γöé       Γöé less than -4 or greater than precision.  Trailing zeros Γöé
Γöé    Γöé       Γöé are truncated, and the decimal point appears only if   Γöé
Γöé    Γöé       Γöé one or more digits follow it.              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé G   Γöé Double   Γöé Identical to the "g" format except that "E" introduces  Γöé
Γöé    Γöé       Γöé the exponent (where appropriate) instead of "e".     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé c   Γöé Character  Γöé Single character.                    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé s   Γöé String   Γöé Characters printed up to the first null character    Γöé
Γöé    Γöé       Γöé (\"0") or until precision is reached.          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé n   Γöé Pointer to Γöé Number of characters successfully written so far to the Γöé
Γöé    Γöé integer   Γöé stream or buffer; this value is stored in the integer  Γöé
Γöé    Γöé       Γöé whose address is given as the argument.         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé p   Γöé Pointer   Γöé Pointer to void converted to a sequence of printable   Γöé
Γöé    Γöé       Γöé characters.                       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "lc"  Γöé Wide char- Γöé Multibyte character.                   Γöé
Γöé    Γöé acter    Γöé                             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "ls"  Γöé Wide    Γöé Multibyte characters printed up to the first "wchar_t"  Γöé
Γöé    Γöé string   Γöé null character ("L\0") or until precision is reached.  Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 6.175.2. Format Specification - Flags ΓòÉΓòÉΓòÉ

The flag characters and their meanings are as follows (notice that more than
one flag can appear in a format specification):

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé FLAG    Γöé MEANING                  Γöé DEFAULT        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé -     Γöé Left-justify the result within the field  Γöé Right-justify.    Γöé
Γöé      Γöé width.                   Γöé            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé +     Γöé Prefix the output value with a sign (+ or Γöé Sign appears only   Γöé
Γöé      Γöé -) if the output value is of a signed   Γöé for negative signed  Γöé
Γöé      Γöé type.                   Γöé values (-).      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé blank(' ')Γöé Prefix the output value with a blank if  Γöé No blank.       Γöé
Γöé      Γöé the output value is signed and positive.  Γöé            Γöé
Γöé      Γöé The "+" flag overrides the blank flag if  Γöé            Γöé
Γöé      Γöé both appear, and a positive signed value  Γöé            Γöé
Γöé      Γöé will be output with a sign.        Γöé            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé #     Γöé When used with the "o", "x", or "X"    Γöé No prefix.      Γöé
Γöé      Γöé formats, the "#" flag prefixes any     Γöé            Γöé
Γöé      Γöé nonzero output value with "0", "0"x, or  Γöé            Γöé
Γöé      Γöé "0"X, respectively.            Γöé            Γöé
Γöé      Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé      Γöé When used with the "f", "e", or "E"    Γöé Decimal point     Γöé
Γöé      Γöé formats, the "#" flag forces the output  Γöé appears only if    Γöé
Γöé      Γöé value to contain a decimal point in all  Γöé digits follow it.   Γöé
Γöé      Γöé cases.                   Γöé            Γöé
Γöé      Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé      Γöé When used with the "g" or "G" formats,   Γöé Decimal point     Γöé
Γöé      Γöé the "#" flag forces the output value to  Γöé appears only if    Γöé
Γöé      Γöé contain a decimal point in all cases and  Γöé digits follow it;   Γöé
Γöé      Γöé prevents the truncation of trailing    Γöé trailing zeros are  Γöé
Γöé      Γöé zeros.                   Γöé truncated.      Γöé
Γöé      Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé      Γöé When used with the "ls" format, the "#"  Γöé Precision indicates  Γöé
Γöé      Γöé flag causes precision to be measured in  Γöé the maximum number  Γöé
Γöé      Γöé "wchar_t" characters.           Γöé of bytes to be    Γöé
Γöé      Γöé                      Γöé output.        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "0"    Γöé When used with the "d", "i", "o", "u",   Γöé Space padding.    Γöé
Γöé      Γöé "x", "X", "e", "E", "f", "g", or "G"    Γöé            Γöé
Γöé      Γöé formats, the "0" flag causes leading    Γöé            Γöé
Γöé      Γöé "0"'s to pad the output to the field    Γöé            Γöé
Γöé      Γöé width.  The "0" flag is ignored if preci- Γöé            Γöé
Γöé      Γöé sion is specified for an integer or if   Γöé            Γöé
Γöé      Γöé the "-" flag is specified.         Γöé            Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The # flag should not be used with c, lc, d, i, u, s, or p types.


ΓòÉΓòÉΓòÉ 6.175.3. Format Specification - Width ΓòÉΓòÉΓòÉ

Width is a nonnegative decimal integer controlling the minimum number of
characters printed.  If the number of characters in the output value is less
than the specified width, blanks are added on the left or the right (depending
on whether the - flag is specified) until the minimum width is reached.

Width never causes a value to be truncated;  if the number of characters in the
output value is greater than the specified width, or width is not given, all
characters of the value are printed (subject to the precision specification).

For the ls type, width is specified in bytes. If the number of bytes in the
output value is less than the specified width, single-byte blanks are added on
the left or the right (depending on whether the - flag is specified) until the
minimum width is reached.

The width specification can be an asterisk (*), in which case an argument from
the argument list supplies the value.  The width argument must precede the
value being formatted in the argument list.


ΓòÉΓòÉΓòÉ 6.175.4. Format Specification - Precision ΓòÉΓòÉΓòÉ

Precision is a nonnegative decimal integer preceded by a period, which
specifies the number of characters to be printed or the number of decimal
places.  Unlike the width specification, the precision can cause truncation of
the output value or rounding of a floating-point value.

The precision specification can be an asterisk (*), in which case an argument
from the argument list supplies the value.  The precision argument must precede
the value being formatted in the argument list.

The interpretation of the precision value and the default when the precision is
omitted depend upon the type, as shown in the following table:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé TYPE  Γöé MEANING                    Γöé DEFAULT        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé   i  Γöé Precision specifies the minimum number of   Γöé If precision is "0"  Γöé
Γöé   d  Γöé digits to be printed.  If the number of    Γöé or omitted entirely, Γöé
Γöé   u  Γöé digits in the argument is less than      Γöé or if the period (.) Γöé
Γöé   o  Γöé precision, the output value is padded on the  Γöé appears without a   Γöé
Γöé   x  Γöé left with zeros.  The value is not truncated  Γöé number following it, Γöé
Γöé   X  Γöé when the number of digits exceeds precision.  Γöé the precision is set Γöé
Γöé    Γöé                        Γöé to 1.         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé   f  Γöé Precision specifies the number of digits to  Γöé Default precision is Γöé
Γöé   e  Γöé be printed after the decimal point.  The last Γöé six.  If precision  Γöé
Γöé   E  Γöé digit printed is rounded.           Γöé is "0" or the period Γöé
Γöé    Γöé                        Γöé appears without a   Γöé
Γöé    Γöé                        Γöé number following it, Γöé
Γöé    Γöé                        Γöé no decimal point is  Γöé
Γöé    Γöé                        Γöé printed.       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé   g  Γöé Precision specifies the maximum number of   Γöé All significant    Γöé
Γöé   G  Γöé significant digits printed.          Γöé digits are printed.  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé   c  Γöé No effect.                   Γöé The character is   Γöé
Γöé    Γöé                        Γöé printed.       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé   lc Γöé No effect.                   Γöé The "wchar_t" char-  Γöé
Γöé    Γöé                        Γöé acter is printed.   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé   s  Γöé Precision specifies the maximum number of   Γöé Characters are    Γöé
Γöé    Γöé characters to be printed.  Characters in    Γöé printed until a null Γöé
Γöé    Γöé excess of precision are not printed.      Γöé character is     Γöé
Γöé    Γöé                        Γöé encountered.     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé   ls Γöé Precision specifies the maximum number of   Γöé "wchar_t" characters Γöé
Γöé    Γöé bytes to be printed.  Bytes in excess of pre- Γöé are printed until a  Γöé
Γöé    Γöé cision are not printed; however, multibyte   Γöé null character is   Γöé
Γöé    Γöé integrity is always preserved.         Γöé encountered.     Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 6.175.5. Format Specification - h, l, L ΓòÉΓòÉΓòÉ

The h, l, and L characters specify the size of the expected argument.  Their
meanings are as follows:

h    A prefix with the integer types d, i, o, u, x, X, and n that specifies
     that the argument is short int or unsigned short int.
l    A prefix with d, i, o, u, x, X, and n types that specifies that the
     argument is a long int or unsigned long int.
L    A prefix with e, E, f, g, or G types that specifies that the argument is
     long double.


ΓòÉΓòÉΓòÉ <hidden> Example of printf ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example prints data in a variety of formats.

                                                                        *
************************************************************************/

#include <stdio.h>

int main(void)
{
   char ch = 'h', *string = "computer";
   int count = 234, hex = 0x10, oct = 010, dec = 10;
   double fp = 251.7366;


   printf("%d   %+d    %06d     %X    %x     %o\n\n",
      count, count, count, count, count, count);

   printf("1234567890123%n4567890123456789\n\n", &count);

   printf("Value of count should be 13; count = %d\n\n", count);

   printf("%10c%5c\n\n", ch, ch);

   printf("%25s\n%25.4s\n\n", string, string);


   printf("%f    %.2f    %e    %E\n\n", fp, fp, fp, fp);

   printf("%i    %i     %i\n\n", hex, oct, dec);

}

/*****************  Output should be similar to:  *****************

234   +234    000234     EA    ea     352

12345678901234567890123456789

Value of count should be 13; count = 13

         h    h

                 computer
                     comp

251.736600    251.74    2.517366e+02    2.517366E+02

16    8     10


ΓòÉΓòÉΓòÉ 6.176. putc - putchar  - Write a Character ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int putc(int c, FILE *stream);

int putchar(int c);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The putc function converts c to unsigned char and then writes c to the output
stream at the current position.  The putchar function is identical to
putc(c, stdout).

The putc and putchar functions return the character written.  A return value of
EOF indicates an error.

The putc function can be implemented as a macro so the argument may be
evaluated multiple times.

Example of putc - putchar


ΓòÉΓòÉΓòÉ <hidden> Example of putc - putchar ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example writes the contents of a buffer to a data stream.  In this
example, the body of the for statement is null because the example carries out
the writing operation in the test expression.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>

#define  LENGTH 80

int main(void)
{
   FILE *stream = stdout;
   int i, ch;
   char buffer[LENGTH + 1] = "Hello world";

   /* This could be replaced by using the fwrite routine */
   for ( i = 0;
        (i < strlen(buffer)) && ((ch = putc(buffer[i], stream)) != EOF);
         ++i);
}

/********************  Expected output:  **************************

Hello world
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fputc  - Write a Character
o _fputchar - Write Character
o fwrite  - Write Items
o getc  - Read a Character
o _putch - Write Character to Screen
o puts  - Write a String
o stdio.h
o _write - Writes from Buffer to File


ΓòÉΓòÉΓòÉ 6.177. _putch - Write Character to Screen ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <conio.h>

int _putch(int c);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _putch function writes the character c directly to the screen.

If successful, _putch returns c. If an error occurs, _putch returns EOF.

Example of _putch


ΓòÉΓòÉΓòÉ <hidden> Example of _putch ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example defines a function gchar that is similar to _getche using the
_putch and _getch functions:

                                                                        *
************************************************************************/

#include <conio.h>

int gchar(void)
{
   int ch;

   ch = _getch();
   _putch(ch);
   return(ch);
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _cputs - Write String to Screen
o _cprintf - Print Characters to Screen
o fputc  - Write a Character
o _getch - _getche - Read Character from Keyboard
o putc - putchar  - Write a Character
o puts  - Write a String
o _write - Writes from Buffer to File
o conio.h


ΓòÉΓòÉΓòÉ 6.178. _putenv - Modify Environment Variables ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

int _putenv(char *envstring);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _putenv function adds new environment variables or modifies the values of
existing environment variables. Environment variables define the environment in
which a process runs (for example, the default search path for libraries to be
linked with a program).

The envstring argument must be a pointer to a string with the form:

   varname=string

where varname is the name of the environment variable to be added or modified
and string is the value of the variable. See the Notes below.

If varname is already part of the environment, string replaces its current
value; if not, the new varname is added to the environment with the value
string. To set a variable to an empty value, specify an empty string. A
variable can be removed from the environment by specifying varname only, for
example,

   _putenv("PATH");

Do not free a pointer to an environment entry while the environment entry is
still in use, or the environment variable will point into freed space. A
similar problem can occur if you pass a pointer to a local variable to _putenv
and then exit from the function in which the variable is declared.

The environment manipulated by _putenv is local to the process currently
running. You cannot enter new items in your command level environment using
_putenv. When the program ends, the environment reverts to the parent process
environment. This environment is passed on to some child processes created by
the _spawn, _exec, or system functions, and they get any new environment
variables added using _putenv.

DosScanEnv will not reflect any changes made using the _putenv function, but
getenv will reflect any changes made by _putenv.

Notes

 1. The _putenv function can change the value of _environ, thus invalidating
    the envp argument to the main function.

 2. %envvar%, where envvar is any OS/2 environment variable, cannot be used
    with _putenv to concatenate new envstring and old envstring.

The _putenv function returns 0 if it is successful.  A return value of -1
indicates an error.

Example of _putenv


ΓòÉΓòÉΓòÉ <hidden> Example of _putenv ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example tries to change the environment variable PATH, and then uses
getenv to get the current path. If the call to _putenv fails, the example
writes an error message.

                                                                        *
************************************************************************/

#include <stdlib.h>
#include <stdio.h>

int main(void)
{
    char *pathvar;

    if ( _putenv("PATH=a:\\bin;b:\\andy") == -1 )
    {
        printf("_putenv failed - out of memory\n");
        exit(-1);
    }

    /* getting and printing the current environment path  */
    pathvar = getenv("PATH");
    printf("The current path is: %s\n", pathvar);

    return 0;

    /* The expected output is:

       The current path is: a:\bin;b:\andy   */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _execl - _execvp - Load and Run Child Process
o getenv  - Search for Environment Variables
o _spawnl -_spawnvpe -Start and Run Child Processes
o system - Invoke the Command Processor
o envp Parameter to main
o stdlib.h


ΓòÉΓòÉΓòÉ 6.179. puts  - Write a String ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int puts(const char *string);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The puts function writes the given string to the standard output stream stdout;
it also appends a new-line character to the output.  The terminating null
character is not written.

The puts function returns EOF if an error occurs.  A nonnegative return value
indicates that no error has occurred.

Example of puts


ΓòÉΓòÉΓòÉ <hidden> Example of puts ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example writes Hello World to stdout.

                                                                        *
************************************************************************/

#include <stdio.h>

int main(void)
{
  if ( puts("Hello World") == EOF )
    printf( "Error in puts\n" );
}

/************************  Expected output:  *********************

Hello World
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _cputs - Write String to Screen
o fputs  - Print Strings
o gets  - Read a Line
o putc - putchar  - Write a Character
o stdio.h


ΓòÉΓòÉΓòÉ 6.180. qsort  - Sort Array ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

void qsort(void *base, size_t num, size_t width,
           int(*compare)(const void *element1, const void *element2));


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA, Extension

The qsort function sorts an array of num elements, each of width bytes in size.
The base pointer is a pointer to the array to be sorted.  The qsort function
overwrites this array with the sorted elements.

The compare pointer points to a function, which you supply, that compares two
array elements and returns an integer value specifying their relationship.  The
qsort function calls the compare function one or more times during the sort,
passing pointers to two array elements on each call.  The function must compare
the elements, and then return one of the following values:

Value               Meaning
Less than 0         element1 less than element2
0                   element1 equal to element2
Greater than 0      element1 greater than element2

The sorted array elements are stored in ascending order, as defined by your
comparison function.  You can sort in reverse order by reversing the sense of
"greater than" and "less than" in the comparison function.  The order of the
elements is unspecified when two elements compare equally.

There is no return value.

Example of qsort


ΓòÉΓòÉΓòÉ <hidden> Example of qsort ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example sorts the arguments (argv) in ascending lexical sequence, using
the comparison function compare() supplied in the example.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

               /* Declaration of compare() as a function */
int compare(const void *, const void *);

int main (int argc, char *argv[ ])
{
   int i;
   argv++;
   argc--;
   qsort((char *)argv, argc, sizeof(char *), compare);
   for (i = 0; i < argc; ++i)
      printf("%s\n", argv[i]);
   return 0;
}

int compare (const void *arg1, const void *arg2)
{
               /* Compare all of both strings */
   return(strcmp(*(char **)arg1, *(char **)arg2));
}

/***********  If the program is passed the arguments:  ************
************  Does, this, really, sort, the, arguments, correctly?,  ****
****************  then the expected output is:  *******************

arguments
correctly?
really
sort
the
this
Does
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o bsearch  - Search Arrays
o _lfind - _lsearch - Find Key in Array
o search.h
o stdlib.h


ΓòÉΓòÉΓòÉ 6.181. raise  - Send Signal ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <signal.h>

int raise(int sig);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The raise function sends the signal sig to the running program. The return
value is zero if successful, nonzero if unsuccessful.

Example of raise


ΓòÉΓòÉΓòÉ <hidden> Example of raise ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example establishes a signal handler called sig_hand for the signal
SIGUSR1. The signal handler is called whenever the SIGUSR1 signal is raised and
will ignore the first nine occurrences of the signal.  On the tenth raised
signal, it exits the program with an error code of 10.  Note that the signal
handler must be reestablished each time it is called.

                                                                        *
************************************************************************/

#include <signal.h>
#include <stdio.h>

void sig_hand(int);  /* declaration of sig_hand() as a function */

int main(void)
{
   signal(SIGUSR1, sig_hand); /* set up handler for SIGUSR1 */
   .
   .
   .
   raise(SIGUSR1);   /* signal SIGUSR1 is raised */
                     /* sig_hand() is called     */
}

void sig_hand(int sig)
{
   static int count = 0;  /* initialized only once */

   count++;
   if (count == 10)  /* ignore the first 9 occurrences of this signal */
      exit(10);
   else
      signal(SIGUSR1, sig_hand);  /* set up the handler again */
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o signal Install Interrupt Handlers
o signal.h


ΓòÉΓòÉΓòÉ 6.182. rand  - Generate Random Number ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

int rand(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The rand function generates a pseudo-random integer in the range 0 to RAND_MAX
(macro defined in <stdlib.h>).  Use the srand function before calling rand to
set a starting point for the random number generator. If you do not make a call
to srand, the default seed is 1.

Example of rand


ΓòÉΓòÉΓòÉ <hidden> Example of rand ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example prints the first 10 random numbers generated.

                                                                        *
************************************************************************/

#include <stdlib.h>
#include <stdio.h>

int main(void)
{
   int x;

   for (x = 1; x <= 10; x++)
      printf("iteration %d, rand=%d\n", x, rand());
}

/*********************  Output should be similar to:  ************

iteration 1, rand=16838
iteration 2, rand=5758
iteration 3, rand=10113
iteration 4, rand=17515
iteration 5, rand=31051
iteration 6, rand=5627
iteration 7, rand=23010
iteration 8, rand=7419
iteration 9, rand=16212
iteration 10, rand=4086
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o srand  - Set Seed for rand Function
o stdlib.h


ΓòÉΓòÉΓòÉ 6.183. _read - Read Into Buffer ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <io.h>

int _read(int handle, char *buffer, unsigned int count);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _read function reads count bytes from the file associated with handle into
buffer. The read operation begins at the current position of the file pointer
associated with the given file. After the read operation, the file pointer
points to the next unread character.

The _read function returns the number of bytes placed in buffer. This number
can be less than count if there are fewer than count  bytes left in the file or
if the file was opened in text mode (see the note below). The return value 0
indicates an attempt to read at end-of-file. A return value -1 indicates an
error. If -1 is returned, the current file position is undefined, and errno is
set to one of the following values:

Value          Meaning
EBADF          The given handle is incorrect, or the file is not open for
               reading, or the file is locked.
EOS2ERR        The call to the operating system was not successful.

Note:  If the file was opened in text mode, the return value might not
correspond to the number of bytes actually read. When text mode is in effect,
carriage return characters are deleted from the input stream without affecting
the file pointer.

Example of _read


ΓòÉΓòÉΓòÉ <hidden> Example of _read ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example opens the file sample.dat and attempts to read from it.

                                                                        *
************************************************************************/

#include <io.h>
#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>
#include <string.h>

int main(void)
{
   int  fh;
   char buffer[20];

   memset(buffer,'\0',20);

   printf("\nCreating sample.dat.\n");
   system("echo Sample Program > sample.dat");

   if (-1 == (fh = _open("sample.dat",O_RDWR | O_APPEND)))
   {
      perror("Unable to open sample.dat.");
      return 1;
   }

   if (7 != _read(fh,buffer,7))
   {
      perror("Unable to read from sample.dat.");
      _close(fh);
      return 1;
   }

   printf("Successfully read in the following:\n%s\n ",buffer);

   _close(fh);
   return 0;

/*****************  The expected output is:  ****************************

      Creating sample.dat.
      Successfully read in the following:
      Sample
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _creat - Create New File
o fread  - Read Items
o _open - Open File
o _sopen - Open Shared File
o _write - Writes from Buffer to File
o io.h


ΓòÉΓòÉΓòÉ 6.184. realloc  - Change Reserved Storage Block Size ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>  /* also defined in <malloc.h> */

void *realloc(void *ptr, size_t size);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA , Extension

The realloc function changes the size of a previously reserved storage block.
The ptr argument points to the beginning of the block.  The size argument gives
the new size of the block, in bytes.  The contents of the block are unchanged
up to the shorter of the new and old sizes.

If the ptr is NULL, realloc reserves a block of storage of size bytes. It does
not necessarily give all bits of each element an initial value of 0.

If size is 0 and the ptr is not NULL, the storage allocated to ptr is freed and
NULL is returned.

The realloc function returns a pointer to the reallocated storage block.  The
storage location of the block might be moved by the realloc function.  Thus,
the ptr argument to realloc is not necessarily the same as the return value.

The return value is NULL if size is 0. If there is not enough storage to expand
the block to the given size, the original block is unchanged and NULL is
returned.

The storage to which the return value points is guaranteed to be aligned for
storage of any type of object.

Example of realloc


ΓòÉΓòÉΓòÉ <hidden> Example of realloc ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example allocates storage for the prompted size of array and then uses
realloc to reallocate the block to hold the new size of the array. The contents
of the array are printed after each allocation.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
  long * array;    /* start of the array */
  long * ptr;      /* pointer to array   */
  int    i;        /* index variable     */
  int  num1, num2; /* number of entries of the array */

  void print_array( long *ptr_array, int size);

  printf( "Enter the size of the array\n" );
  scanf( "%i", &num1 );

  /* allocate num1 entries using malloc() */
  if ( (array = malloc( num1 * sizeof( long ))) != NULL )
  {
     for ( ptr = array, i = 0; i < num1 ; ++i ) /* assign values */
        *ptr++ = i;
     print_array( array, num1 );
     printf("\n");
  }
  else { /*  malloc error  */
    perror( "Out of storage" );
    abort();
  }

  /* Change the size of the array ... */
  printf( "Enter the size of the new array\n" );
  scanf( "%i", &num2);

  if ( (array = realloc( array, num2* sizeof( long ))) != NULL )
  {
     for ( ptr = array + num1, i = num1; i <= num2; ++i )
        *ptr++ = i + 2000;  /* assign values to new elements */
     print_array( array, num2 );
  }

  else { /* realloc error */
    perror( "Out of storage" );
    abort();
  }
}

void print_array( long  * ptr_array, int size )
{
  int i;
  long * index = ptr_array;

  printf("The array of size %d is:\n", size);
  for ( i = 0; i < size; ++i )           /* print the array out    */
    printf( "  array[ %i ] = %li\n", i, ptr_array[i] );
}

/******************  If the initial value entered  *********************
**************  is 2 and the second value entered is 4,  ****************
*******************  then the expected output is:  ****************

Enter the size of the array
The array of size 2 is:
  array[ 0 ] = 0
  array[ 1 ] = 1

Enter the size of the new array
The array of size 4 is:
  array[ 0 ] = 0
  array[ 1 ] = 1
  array[ 2 ] = 2002
  array[ 3 ] = 2003
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o calloc  - Reserve and Initialize Storage
o _debug_realloc - Change Reserved Storage Block Size
o free  - Release Storage Blocks
o malloc  - Reserve Storage Block
o _msize - Return Number of Bytes Allocated
o _trealloc - Reallocate Tiled Storage Block
o malloc.h
o stdlib.h


ΓòÉΓòÉΓòÉ 6.185. remove  - Delete File ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int remove(const char *filename);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The remove function deletes the file specified by filename. The remove function
returns the value 0 if it successfully deletes the file.  A return value of
nonzero indicates an error.

Note:  You cannot remove a nonexistent file or a file that is open.

Example of remove


ΓòÉΓòÉΓòÉ <hidden> Example of remove ΓòÉΓòÉΓòÉ

/************************************************************************
*

When you invoke this example with a file name, the program attempts to remove
that file. It issues a message if an error occurs.

                                                                        *
************************************************************************/

#include <stdio.h>

int main(int argc, char ** argv)
{
  if ( argc != 2 )
    printf( "Usage: %s fn\n", argv[0] );
  else
    if ( remove( argv[1] ) != 0 )
      perror( "Could not remove file" );
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fopen  - Open Files
o rename  - Rename File
o _rmtmp - Remove Temporary Files
o _unlink - Delete File
o stdio.h


ΓòÉΓòÉΓòÉ 6.186. rename  - Rename File ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>  /* also defined in <io.h> */

int rename(const char *oldname, const char *newname);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The rename function renames the file specified by oldname to the name given by
newname.  The oldname pointer must specify the name of an existing file.  The
newname pointer must not specify the name of an existing file. You cannot
rename a file with the name of an existing file. You also cannot rename an open
file.

The rename function returns 0 if it is successful.  On an error, it returns a
nonzero value.

Example of rename


ΓòÉΓòÉΓòÉ <hidden> Example of rename ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example takes two file names as input and uses rename to change the file
name from the first name to the second name.

                                                                        *
************************************************************************/

#include <stdio.h>

int main(int argc, char ** argv )
{
  if ( argc != 3 )
    printf( "Usage: %s old_fn new_fn\n", argv[0] );
  else if ( rename( argv[1], argv[2] ) != 0 )
    perror ( "Could not rename file" );
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fopen  - Open Files
o remove  - Delete File
o stdio.h


ΓòÉΓòÉΓòÉ 6.187. rewind  - Adjust Current File Position ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

void rewind(FILE *stream);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The rewind function repositions the file pointer associated with stream to the
beginning of the file.  A call to rewind is the same as:

   (void) fseek(stream, 0L, SEEK_SET);

except that rewind also clears the error indicator for the stream.

There is no return value.

Example of rewind


ΓòÉΓòÉΓòÉ <hidden> Example of rewind ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example first opens a file myfile for input and output.  It writes
integers to the file, uses rewind to reposition the file pointer to the
beginning of the file, and then reads the data back in.

                                                                        *
************************************************************************/

#include <stdio.h>

FILE *stream;

int data1, data2, data3, data4;
int main(void)
{
   data1 = 1; data2 = -37;

      /* Place data in the file */
   stream = fopen("myfile.dat", "w+");
   fprintf(stream, "%d %d\n", data1, data2);

      /* Now read the data file */
   rewind(stream);
   fscanf(stream, "%d", &data3);
   fscanf(stream, "%d", &data4);
   printf("The values read back in are: %d and %d\n",
       data3, data4);
}

/********************  Output should be similar to:  **************

The values read back in are: 1 and -37
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fgetpos  - Get File Position
o fseek  - Reposition File Position
o fsetpos  - Set File Position
o ftell  - Get Current Position
o _lseek - Move File Pointer
o _tell - Get Pointer Position
o stdio.h


ΓòÉΓòÉΓòÉ 6.188. _rmdir - Remove Directory ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <direct.h>

int _rmdir(char *pathname);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _rmdir function deletes the directory specified by pathname.  The directory
must be empty, and it must not be the current working directory or the root
directory.

The _rmdir function returns the value 0 if the directory is successfully
deleted.  A return value of -1 indicates an error, and errno is set to one of
the following values:

Value          Meaning
EACCESS        One of the following has occurred:

   o The given path name is not a directory.
   o The directory is not empty.
   o The directory is read only.
   o The directory is the current working directory or root directory being
     used by a process.
ENOENT         The path name was not found.

Example of _rmdir


ΓòÉΓòÉΓòÉ <hidden> Example of _rmdir ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example deletes two directories. One is in the root directory and the
other one in the current working directory.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <direct.h>
#include <string.h>

int main(void)
{
    char *dir1, *dir2;

/*  Create the directory "aleng" in the root directory of the C: drive. */
    dir1 = "c:\\aleng";
    if ((_mkdir(dir1)) == 0)
        printf("%s directory was created.\n",dir1);
    else
        printf("%s directory was not created.\n",dir1);

/*  Create the subdirectory "simon" in the current directory. */
    dir2 = "simon";
    if ((_mkdir(dir2)) == 0)
        printf("%s directory was created.\n",dir2);
    else
        printf("%s directory was not created.\n",dir2);

/*  Remove the directory "aleng" from the root directory
                   of the C: drive. */
    printf("Removing directory 'aleng' from the root directory.\n");

    if (_rmdir(dir1))
       perror(NULL);
    else
       printf("%s directory was removed.\n",dir1);

/*  Remove the subdirectory "simon" from the current directory. */
    printf("Removing subdirectory 'simon' from the current directory.\n");

    if (_rmdir(dir2))
       perror(NULL);
    else
       printf("%s directory was removed.\n",dir2);

    return 0;

/*************** The output should be similar to:  ********************

   c:\aleng directory was created.
   simon directory was created.
   Removing directory 'aleng' from the root directory.
   c:\aleng directory was removed.
   Removing subdirectory 'simon' from the current directory.
   simon directory was removed.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _chdir - Change Current Working Directory
o _getdcwd - Get Full Path Name of Current Directory
o _getcwd - Get Path Name of Current Directory
o _mkdir - Create New Directory
o direct.h


ΓòÉΓòÉΓòÉ 6.189. _rmtmp - Remove Temporary Files ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int _rmtmp(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _rmtmp function closes and deletes all temporary files in all directories
that are held open by the calling process.

The _rmtmp function returns the number of temporary files removed and deleted.

Example of _rmtmp


ΓòÉΓòÉΓòÉ <hidden> Example of _rmtmp ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example uses _rmtmp to remove a number of temporary files.

                                                                        *
************************************************************************/

#include <stdio.h>

int main(void)
{
    int num;
    FILE *stream;

    if ( (stream = tmpfile()) == NULL )
        printf("Could not open new temporary file\n");
    else
    {
        num = _rmtmp();
        printf("Number of temporary files removed = %d\n", num);
    }

    return 0;

    /* The expected output is:

       Number of temporary files removed = 1   */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _flushall - Write Buffers to Files
o remove  - Delete File
o tmpfile  - Create Temporary File
o tmpnam  - Produce Temporary File Name
o _unlink - Delete File
o stdio.h


ΓòÉΓòÉΓòÉ 6.190. _rotl - _rotr - Bit Rotation ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

unsigned int _rotl(unsigned int value, int shift);

unsigned int _rotr(unsigned int value, int shift);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

These functions take a 4-byte integer value and rotate it by shift bits.

Note:  Because the size of an int is only 2 bytes in 16-bit compilers, if you
are migrating 16-bit programs, some parts of your programs may have to be
rewritten if they use this function.

Both functions return the rotated value.  There is no error return.

Example of _rotl - _rotr


ΓòÉΓòÉΓòÉ <hidden> Example of _rotl - _rotr ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example uses _rotr and _rotl with different shift values to rotate the
integer value 0x01234567:

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
    unsigned int val = 0X01234567;

    printf("The value of 0x%8.8lx rotated 4 bits to the left
             is 0x%8.8lx\n", val, _rotl(val, 4));

    printf("The value of 0x%8.8lx rotated 16 bits to the right
             is 0x%8.8lx\n", val, _rotr(val, 16));

    return 0;


/***************  The output should be similar to:  ****************

   The value of 0x01234567 rotated 4 bits to the left is 0x12345670
   The value of 0x01234567 rotated 16 bits to the right is 0x45670123
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _lrotl - _lrotr - Rotate Bits
o _swab - Swap Adjacent Bytes
o stdlib.h


ΓòÉΓòÉΓòÉ 6.191. scanf  - Read Data ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int scanf(const char *format-string, argument-list);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA, Extension

The scanf function reads data from the standard input stream stdin into the
locations given by each entry in argument-list.  Each argument must be a
pointer to a variable with a type that corresponds to a type specifier in
format-string.  The format-string controls the interpretation of the input
fields, and is a multibyte character string beginning and ending in its initial
shift state.

The format-string can contain one or more of the following:

o White-space characters, as specified by isspace (such as blanks and new-line
  characters). A white-space character causes scanf to read, but not to store,
  all consecutive white-space characters in the input up to the next character
  that is not white space.  One white-space character in format-string matches
  any combination of white-space characters in the input.

o Characters that are not white space, except for the percent sign character
  (%).  A non-white-space character causes scanf to read, but not to store, a
  matching non-white-space character.  If the next character in stdin does not
  match, scanf ends.

o Format specifications, introduced by the percent sign (%).  A format
  specification causes scanf to read and convert characters in the input into
  values of a specified type.  The value is assigned to an argument in the
  argument list.

The scanf function reads format-string from left to right.  Characters outside
of format specifications are expected to match the sequence of characters in
stdin;  the matched characters in stdin are scanned but not stored.  If a
character in stdin conflicts with format-string, scanf ends.  The conflicting
character is left in stdin as if it had not been read.

When the first format specification is found, the value of the first input
field is converted according to the format specification and stored in the
location specified by the first entry in argument-list.  The second format
specification converts the second input field and stores it in the second entry
in argument-list, and so on through the end of format-string.

An input field is defined as all characters up to the first white-space
character (space, tab, or new line), up to the first character that cannot be
converted according to the format specification, or until the field width is
reached, whichever comes first.  If there are too many arguments for the format
specifications, the extra arguments are ignored.  The results are undefined if
there are not enough arguments for the format specifications.

A format specification has the following form:

ΓöÇΓöÇ%ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇtypeΓöÇΓöÇ
    Γöé   Γöé  Γöé     Γöé  Γöé   Γöé
    ΓööΓöÇΓöÇ*ΓöÇΓöÇΓöÿ  ΓööΓöÇΓöÇwidthΓöÇΓöÇΓöÿ  Γö£ΓöÇΓöÇhΓöÇΓöÇΓöñ
               Γöé   Γöé
               Γö£ΓöÇΓöÇlΓöÇΓöÇΓöñ
               Γöé   Γöé
               ΓööΓöÇΓöÇLΓöÇΓöÇΓöÿ

Each field of the format specification is a single character or a number
signifying a particular format option.  The type character, which appears after
the last optional format field, determines whether the input field is
interpreted as a character, a string, or a number.  The simplest format
specification contains only the percent sign and a type character (for example,
%s).

Each field of the format specification is discussed in Format Specification
Fields. If a percent sign (%) is followed by a character that has no meaning as
a format control character, that character and following characters up to the
next percent sign are treated as an ordinary sequence of characters;  that is,
a sequence of characters that must match the input.  For example, to specify a
percent-sign character, use %%.

The scanf function scans each input field character by character.  It might
stop reading a particular input field either before it reaches a space
character, when the specified width is reached, or when the next character
cannot be converted as specified.  When a conflict occurs between the
specification and the input character, the next input field begins at the first
unread character.  The conflicting character, if there was one, is considered
unread and is the first character of the next input field or the first
character in subsequent read operations on stdin.

In extended mode, scanf also reads in the strings the strings "INFINITY",
"INF", and "NAN" (in upper or lowercase) and converts them to the corresponding
floating-point value.  The sign of the value is determined by the format
specification. See Infinity and NaN Support for more information on infinity
and NaN values.

The scanf function returns the number of fields that were successfully
converted and assigned.  The return value does not include fields that were
read but not assigned.

The return value is EOF for an attempt to read at end-of-file if no conversion
was performed. A return value of 0 means that no fields were assigned.

Example of scanf


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fscanf  - Read Formatted Data
o printf  - Formatted Print
o sscanf  - Read Data
o Infinity and NaN Support
o stdio.h


ΓòÉΓòÉΓòÉ 6.191.1. Format Specification Fields ΓòÉΓòÉΓòÉ

The scanf format specification fields are described below.

*

An asterisk (*) following the percent sign suppresses assignment of the next
input field, which is interpreted as a field of the specified type.  The field
is scanned but not stored.

width

The width is a positive decimal integer controlling the maximum number of
characters to be read from stdin.  No more than width characters are converted
and stored at the corresponding argument.  Fewer than width characters are read
if a white-space character (space, tab, or new line), or a character that
cannot be converted according to the given format occurs before width is
reached.

h, l, L

The optional prefix l shows that you use the long version of the following
type, while the prefix h indicates that the short version is to be used.  The
corresponding argument should point to a long or double object (for the l
character), a long double object (for the L character), or a short object (with
the h character).  The l and h modifiers can be used with the d, i, o, x, and u
type characters. The l modifier can also be used with the e, f, and g type
characters.  The L modifier can be used with the e, f and g type characters.
The l and h modifiers are ignored if specified for any other type. Note that
the l modifier is also used with the c and s characters to indicate a multibyte
character or string.

type

The type characters and their meanings are in the following table:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé CHAR-  Γöé TYPE OF INPUT EXPECTED      Γöé TYPE OF ARGUMENT         Γöé
Γöé ACTER  Γöé                  Γöé                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "d"   Γöé Decimal integer          Γöé Pointer to "int"         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "o"   Γöé Octal integer           Γöé Pointer to "unsigned int"     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "x",  Γöé Hexadecimal integer        Γöé Pointer to "unsigned int"     Γöé
Γöé "X"   Γöé                  Γöé                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "i"   Γöé Decimal, hexadecimal, or octal  Γöé Pointer to "int"         Γöé
Γöé     Γöé integer              Γöé                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "u"   Γöé Unsigned decimal integer     Γöé Pointer to "unsigned int"     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "e, f, Γöé Floating-point value consisting  Γöé Pointer to "float"        Γöé
Γöé g"   Γöé of an optional sign (+ or -);  a Γöé                  Γöé
Γöé     Γöé series of one or more decimal   Γöé                  Γöé
Γöé "E, G" Γöé digits possibly containing a   Γöé                  Γöé
Γöé     Γöé decimal point;  and an optional  Γöé                  Γöé
Γöé     Γöé exponent (e or E) followed by a  Γöé                  Γöé
Γöé     Γöé possibly signed integer value   Γöé                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "d(n,p)Γöé Packed decimal value consisting  Γöé Pointer to "decimal(n,p)".    Γöé
Γöé     Γöé of an optional sign (+ or -);   Γöé                  Γöé
Γöé     Γöé then a nonempty sequence of    Γöé                  Γöé
Γöé     Γöé digits optionally a series of   Γöé                  Γöé
Γöé     Γöé one or more decimal digits pos-  Γöé                  Γöé
Γöé     Γöé sibly containing a decimal    Γöé                  Γöé
Γöé     Γöé point, but not a decimal suffix. Γöé                  Γöé
Γöé     Γöé The subject sequence is defined  Γöé                  Γöé
Γöé     Γöé as the longest initial subse-   Γöé                  Γöé
Γöé     Γöé quence of the input string,    Γöé                  Γöé
Γöé     Γöé starting with the first non-   Γöé                  Γöé
Γöé     Γöé white-space character, in the   Γöé                  Γöé
Γöé     Γöé expected form.  It contains no  Γöé                  Γöé
Γöé     Γöé characters if the input string  Γöé                  Γöé
Γöé     Γöé is empty or consists entirely of Γöé                  Γöé
Γöé     Γöé white space, or if the first   Γöé                  Γöé
Γöé     Γöé non-white-space character is   Γöé                  Γöé
Γöé     Γöé anything other than a sign, a   Γöé                  Γöé
Γöé     Γöé digit, or a decimal point char-  Γöé                  Γöé
Γöé     Γöé acter.              Γöé                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "c"   Γöé Character;  white-space charac-  Γöé Pointer to "char" large enough  Γöé
Γöé     Γöé ters that are ordinarily skipped Γöé for input field          Γöé
Γöé     Γöé are read when "c" is specified  Γöé                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "s"   Γöé String              Γöé Pointer to character array large Γöé
Γöé     Γöé                  Γöé enough for input field plus a   Γöé
Γöé     Γöé                  Γöé terminating null character    Γöé
Γöé     Γöé                  Γöé ("\0"), which is automatically  Γöé
Γöé     Γöé                  Γöé appended             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "n"   Γöé No input read from stream or   Γöé Pointer to "int", into which is  Γöé
Γöé     Γöé buffer              Γöé stored the number of characters  Γöé
Γöé     Γöé                  Γöé successfully read from the    Γöé
Γöé     Γöé                  Γöé stream or buffer up to that    Γöé
Γöé     Γöé                  Γöé point in the call to "scanf"   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "p"   Γöé Pointer to "void" converted to  Γöé Pointer to "void"         Γöé
Γöé     Γöé series of characters       Γöé                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "lc"  Γöé Multibyte character constant   Γöé Pointer to "wchar_t"       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "ls"  Γöé Multibyte string constant     Γöé Pointer to "wchar_t" string    Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

To read strings not delimited by space characters, substitute a set of
characters in brackets ([ ]) for the s (string) type character.  The
corresponding input field is read up to the first character that does not
appear in the bracketed character set.  If the first character in the set is a
caret (^), the effect is reversed:  the input field is read up to the first
character that does appear in the rest of the character set.

To store a string without storing an ending null character (\0), use the
specification %ac, where a is a decimal integer.  In this instance, the c type
character means that the argument is a pointer to a character array.  The next
a characters are read from the input stream into the specified location, and no
null character is added.

The input for a %x format specifier is interpreted as a hexadecimal number.


ΓòÉΓòÉΓòÉ <hidden> Example of scanf ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example scans various types of data:

                                                                        *
************************************************************************/

#include <stdio.h>

int main(void)
{
   int i;
   float fp;
   char c, s[81];

   printf("Enter an integer, a real number, a character "
          "and a string : \n");
   if (scanf("%d %f %c %s", &i, &fp, &c, s) != 4)
      printf("Not all of the fields were not assigned\n");
   else
   {
      printf("integer = %d\n", i);
      printf("real number = %f\n", fp);
      printf("character = %c\n", c);
      printf("string = %s\n",s);
   }
}

/*****************  If input is: 12 2.5 a yes,  *******************
**************  then output should be similar to:  ****************

Enter an integer, a real number, a character and a string :
integer = 12
real number = 2.500000
character = a
string = yes
*/

/************************************************************************
*
This example converts a hexadecimal integer to a decimal integer.  The while
loop ends if the input value is not a hexadecimal integer.

                                                                        *
************************************************************************/

#include <stdio.h>

int main(void)
{
   int number;

   printf("Enter a hexadecimal number or anything else to quit:\n");
   while (scanf("%x",&number))
      {
      printf("Hexadecimal Number = %x\n",number);
      printf("Decimal Number     = %d\n",number);
      }
}

/***************  If input is: 0x231 0xf5e 0x1 q,  ****************
****************  then output should be similar to:  **************

Enter a hexadecimal number or anything else to quit:
Hexadecimal Number = 231
Decimal Number     = 561
Hexadecimal Number = f5e
Decimal Number     = 3934
Hexadecimal Number = 1
Decimal Number     = 1
*/


ΓòÉΓòÉΓòÉ 6.192. _searchenv - Search for File ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

void _searchenv(char *name, char *env_var, char *path);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _searchenv function searches for the target file in the specified domain.
The env_var variable can be any environment variable that specifies a list of
directory paths, such as PATH, LIB, INCLUDE, or other user-defined variables.
Most often, it is PATH, causing a search for name in all directories specified
in the PATH variable.

The routine first searches for the file in the current working directory.  If
it does not find the file, it next looks through the directories specified by
the environment variable.

If the target file is found in one of the directories, the newly created path
is copied into the buffer that path points to.  You must ensure sufficient
space for the constructed path name.  If the target file is not found, path
contains an empty null-terminated string.

There is no return value.

Example of _searchenv


ΓòÉΓòÉΓòÉ <hidden> Example of _searchenv ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example searches for the files searchen.c and cmd.exe.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
    char path_buffer [_MAX_PATH];

    _searchenv ("cmd.exe", "PATH", path_buffer);
    printf ("path: %s\n", path_buffer);

    _searchenv ("searchen.c", "DPATH", path_buffer);
    printf ("path: %s\n", path_buffer);

    return 0;

/*****************  Output  ************************
*  If the first path that contains cmd.exe is      *
*  in the C: environment and this program is       *
*  not run from another directory with a cmd.exe   *
*  file, the first line of the output should be    *
*  similar to:                                     *

   path: C:\OS2\cmd.exe                                                    */


*  Assuming the file searchen.c does not exist in  *
*  the current directory or any of the directories *
*  in the environment, the next line of the output *
*  should be similar to:   *

   path:
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o getenv  - Search for Environment Variables
o _putenv - Modify Environment Variables
o stdlib.h


ΓòÉΓòÉΓòÉ 6.193. setbuf  - Control Buffering ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

void setbuf(FILE *stream, char *buffer);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The setbuf function allows you to control buffering for the specified stream.
The stream pointer must refer to an open file before any I/O or repositioning
has been done.

If the buffer argument is NULL, the stream is unbuffered.  If not, the buffer
must point to a character array of length BUFSIZ, which is the buffer size
defined in the stdio.h header file.  The system uses the buffer, which you
specify, for input/output buffering instead of the default system-allocated
buffer for the given stream.

The setvbuf function is more flexible than setbuf.

There is no return value.

Example of setbuf


ΓòÉΓòÉΓòÉ <hidden> Example of setbuf ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example opens the file myfile for writing. It then calls the setbuf
function to establish a buffer of length BUFSIZ. When string is written to the
stream, the buffer buf is used and contains the string before it is flushed to
the file.

                                                                        *
************************************************************************/

#include <stdio.h>

int main(void)
{
   char buf[BUFSIZ];
   char string[] = "hello world";
   FILE *stream;

   memset(buf,'\0',BUFSIZ);  /* initialize buf to null characters */

   stream = fopen("myfile.dat", "wb");

   setbuf(stream,buf);       /* set up buffer */

   fwrite(string, sizeof(string), 1, stream);

   printf("%s\n",buf);       /* string is found in buf now */

   fclose(stream);           /* buffer is flushed out to myfile.dat */
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fclose  - Close Stream
o fflush  - Write Buffer to File
o _flushall - Write Buffers to Files
o fopen  - Open Files
o setvbuf  - Control Buffering
o stdio.h


ΓòÉΓòÉΓòÉ 6.194. _set_crt_msg_handle - Change Runtime Message Output Handle ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int _set_crt_msg_handle(int fh);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _set_crt_msg_handle function changes the file handle to which runtime
messages are sent, which is usually file handle 2, to fh. Runtime messages
include exception handling messages and output from debug memory management
routines.

Use _set_crt_msg_handle to trap runtime message output in applications where
handle 2 is not defined, such as Presentation Manager applications.

The file handle fh must be a writable file or pipe handle. Set fh only for the
current library environment.

The _set_crt_msg_handle function returns the handle to be used for runtime
message output. If an handle that is not valid is passed as an argument, it is
ignored and no change takes place.

Example of _set_crt_msg_handle


ΓòÉΓòÉΓòÉ <hidden> Example of _set_crt_msg_handle ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example causes an exception by dereferencing a null pointer and uses
_set_crt_msg_handle to send the exception messages to the file crt.out.

                                                                        *
************************************************************************/


#include <io.h>
#include <stdio.h>
#include <fcntl.h>
#include <sys\stat.h>

main()
{

 int fh;
 char *p=NULL;

 if (-1 == (fh = open("crt.out",O_CREAT|O_TRUNC|O_RDWR,
                      S_IREAD|S_IWRITE)))
 {
   perror("Unable to open crt.out");
   return 1;
 }

 /* change file handle where messages are sent */
 if (_set_crt_msg_handle(fh)!=fh)
 {
   perror("could not change msg handle");
   return 1;
 }

 *p='x';   /* cause an exception, output should be in crt.out */

 if (-1 == close(fh))
 {
   perror("Unable to close crt.out");
   return(1);
 }

 return(0);

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _open - Open File
o _fileno - Determine File Handle
o _sopen - Open Shared File
o stdio.h


ΓòÉΓòÉΓòÉ 6.195. setjmp  - Preserve Environment ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <setjmp.h>

int setjmp(jmp_buf env);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The setjmp macro saves a stack environment that can subsequently be restored by
longjmp.  The setjmp macro and longjmp function provide a way to perform a
nonlocal goto. They are often used in signal handlers.

A call to setjmp causes it to save the current stack environment in env.  A
subsequent call to longjmp restores the saved environment and returns control
to a point corresponding to the setjmp call.  The values of all variables
(except register variables) accessible to the function receiving control
contain the values they had when longjmp was called.  The values of register
variables are unpredictable.  Nonvolatile auto variables that are changed
between calls to setjmp and longjmp are also unpredictable.

The setjmp macro returns the value 0 after saving the stack environment.  If
setjmp returns as a result of a longjmp call, it returns the value argument of
longjmp, or 1 if the value argument of longjmp is 0.  There is no return value.

Example of setjmp


ΓòÉΓòÉΓòÉ <hidden> Example of setjmp ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example stores the stack environment at the statement:

  if(setjmp(mark) != 0) ...

When the system first performs the if statement, it saves the environment in
mark and sets the condition to FALSE because setjmp returns a 0 when it saves
the environment. The program prints the message:

  setjmp has been called

The subsequent call to function p tests for a local error condition, which can
cause it to perform the longjmp function.  Then, control returns to the
original setjmp function using the environment saved in mark.  This time the
condition is TRUE because -1 is the return value from the longjmp function. The
program then performs the statements in the block and prints:

  longjmp has been called

Then the program calls the recover function and exits.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <setjmp.h>

jmp_buf mark;

void p(void);
void recover(void);

int main(void)
{
   if (setjmp(mark) != 0)
   {
      printf("longjmp has been called\n");
      recover();
      exit(1);
   }
   printf("setjmp has been called\n");
   .
   .
   .
   p();
   .
   .
   .
}

void p(void)
{
   int error = 0;
   .
   .
   .
   error = 9;
   .
   .
   .
   if (error != 0)
      longjmp(mark, -1);
   .
   .
   .
}

void recover(void)
{
   .
   .
   .
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o longjmp  - Restore Stack Environment
o goto
o volitile and constant Qualifiers
o auto Storage Class Specifier
o setjmp.h


ΓòÉΓòÉΓòÉ 6.196. setlocale  - Set Locale ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <locale.h>

char *setlocale(int category, const char *locale);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The setlocale function changes or queries variables, defined in the locale.h
header file, that indicate location.  The values for category are listed below.

Category            Purpose
LC_ALL              Names entire locale of program.
LC_COLLATE          Affects behavior of the strcoll and strxfrm functions.
LC_CTYPE            Affects behavior of the character handling functions.
LC_MONETARY         Affects monetary information returned by localeconv.
LC_NUMERIC          Affects the decimal-point character for the formatted
                    input/output and string conversion functions, and the
                    nonmonetary formatting information returned by the
                    localeconv function.
LC_TIME             Affects behavior of the strftime function.
LC_TOD              Affects the behavior of the time functions.

You can set the value of locale to "C", "",LC_C, LC_C_GERMANY, LC_C_FRANCE,
LC_C_SPAIN, LC_C_ITALY, LC_C_JAPAN, LC_C_USA or LC_C_UK. A locale value of "C"
indicates the default C environment.  A locale value of "" tells setlocale to
use the default locale for the implementation.

The setlocale function returns a pointer to the string associated with the
specified category for the new locale.  The string can be used on a subsequent
call to restore that part of the program's locale.

Note:  Because the string to which a successful call to setlocale points may be
overwritten by subsequent calls to the setlocale function, you should copy the
string if you plan to use it later.

On error, the setlocale function returns NULL and the program's locale is not
changed.

To query the locale, give a NULL as the second parameter.  For example, to
query all the categories of your locale, enter the following statement:

    char *string = setlocale(LC_ALL, NULL);

Example of setlocale


ΓòÉΓòÉΓòÉ <hidden> Example of setlocale ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example sets the locale of the program to be LC_C_FRANCE and prints the
string that is associated with the locale.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <locale.h>

char *string;

int main(void)
{
   string = setlocale(LC_ALL, LC_C_FRANCE);
   if (string != NULL)
      printf(" %s \n",string);
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o getenv  - Search for Environment Variables
o localeconv  - Query Locale Conventions
o _putenv - Modify Environment Variables
o locale.h


ΓòÉΓòÉΓòÉ 6.197. _setmode - Set File Translation Mode ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <fcntl.h>
#include <io.h>

int _setmode(int handle, int mode);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _setmode function sets the translation mode of the file given by handle to
mode. The mode must be one of the values in the following table:

Value          Meaning
O_TEXT         Sets the translated text mode.  Carriage-return line-feed
               combinations are translated into a single line feed on input.
               Line-feed characters are translated into carriage-return
               line-feed combinations on output.
O_BINARY       Sets the binary (untranslated) mode.  The above translations are
               suppressed.

Use the _setmode function to change the translation mode of a file handle. The
translation mode only affects the _read and _write functions. This function
does not affect the translation mode of streams.

If a file handle is acquired other than by a call to _open, _creat, _sopen or
_fileno, The _setmode function should be called for that file handle before
using it within the _read or _write functions.

The _setmode function returns the previous translation mode if successful. A
return value of -1 indicates an error, and errno is set to one of the following
values:

Value          Meaning
EBADF          The file handle is not a handle for an open file.
EINVAL         Incorrect mode (neither O_TEXT nor O_BINARY)

Example of _setmode


ΓòÉΓòÉΓòÉ <hidden> Example of _setmode ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses _open to create the file SETMODE.DAT and writes to it. The
program then uses _setmode to change the translation mode of SETMODE.DAT from
binary to text.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>
#include <io.h>
#include <sys\stat.h>

#define FILENAME "SETMODE.DAT"

/* routine to validate return codes */
void ckrc(rc) {
   if ((rc) == -1)
   {
      printf("Unexpected return code = -1\n");
      _exit(1);
   }
}

int main(void)
{
   int h;
   int xfer;
   int mode;
   char rbuf[256];
   char wbuf[] = "123\n456\n";

   ckrc(h =  _open(FILENAME,
    O_CREAT | O_RDWR |
    O_TRUNC | O_TEXT,
    S_IREAD | S_IWRITE));

   ckrc(_write(h,wbuf,sizeof(wbuf)));   /* write the file (text) */

   ckrc(_lseek(h,0,SEEK_SET)); /* seek back to the start of the file */

   ckrc(xfer = _read(h,rbuf,5));        /* read the file text */
   printf("Read in %d characters (4 expected)\n",xfer);

   ckrc(mode = _setmode(h,O_BINARY));
   if (mode == O_TEXT) printf("Mode changed from binary to text\n");
   else printf("Previous mode was not text (unexpected)\n");

   ckrc(xfer = _read(h,rbuf,5));        /* read the file (binary) */
   printf("Read in %d characters (5 expected)\n",xfer);

   ckrc(_close(h));

   remove (FILENAME);

   return 0;

/****************  The expected output is:  *****************************

      Read in 4 characters (4 expected)
      Mode changed from binary to text
      Read in 5 characters (5 expected)
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _creat - Create New File
o _open - Open File
o _sopen - Open Shared File
o _read - Read Into Buffer
o _write - Writes from Buffer to File
o fcntl.h
o io.h
o share.h
o sys\stat.h


ΓòÉΓòÉΓòÉ 6.198. setvbuf  - Control Buffering ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int setvbuf(FILE *stream, char *buf, int type, size_t size);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The setvbuf function allows control over the buffering strategy and buffer size
for a specified stream. The stream must refer to a file that has been opened,
but not read or written to.

The array pointed to by buf designates an area that you provide that the C
library may choose to use as a buffer for the stream.  A buf value of NULL
indicates that no such area is supplied and that the C library is to assume
responsibility for managing its own buffers for the stream.  If you supply a
buffer, it must exist until the stream is closed.

If type is _IOFBF or _IOLBF, size is the size of the supplied buffer.  If buf
is NULL, the C library will take size as the suggested size for its own buffer.
If type is _IONBF, both buf and size are ignored.

Value         Meaning
_IONBF        No buffer is used.
_IOFBF        Full buffering is used for input and output. Use buf as the
              buffer and size as the size of the buffer.
_IOLBF        Line buffering is used.  The buffer is flushed when a new-line
              character is written, when the buffer is full, or when input is
              requested.

The value for size must be greater than 0.

The setvbuf function returns a 0 if successful and nonzero if an invalid value
was specified in the parameter list, or if the request cannot be performed.

Warning: The array used as the buffer must still exist when the specified
stream is closed. For example, if the buffer is declared within the scope of a
function block, the stream must be closed before the function is terminated and
frees the storage allocated to the buffer.

Example of setvbuf


ΓòÉΓòÉΓòÉ <hidden> Example of setvbuf ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example sets up a buffer of buf for stream1 and specifies that input to
stream2 is to be unbuffered.

                                                                        *
************************************************************************/

#include <stdio.h>

#define  BUF_SIZE  1024

char buf[BUF_SIZE];
FILE *stream1, *stream2;

int main(void)
{
   stream1 = fopen("myfile1.dat", "r");
   stream2 = fopen("myfile2.dat", "r");

   /* stream1 uses a user-assigned buffer of BUF_SIZE bytes */
   if (setvbuf(stream1, buf, _IOFBF, sizeof(buf)) != 0)
      printf("Incorrect type or size of buffer\n");

   /* stream2 is unbuffered                                  */
   if (setvbuf(stream2, NULL, _IONBF, 0) != 0)
      printf("Incorrect type or size of buffer\n");
   .
   .
   .
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fclose  - Close Stream
o fflush  - Write Buffer to File
o _flushall - Write Buffers to Files
o fopen  - Open Files
o setbuf  - Control Buffering
o stdio.h


ΓòÉΓòÉΓòÉ 6.199. signal Install Interrupt Handlers ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <signal.h>

void (*signal(int sig, void (*sig_handler)(int)))(int);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA, Extension

The signal function assigns the interrupt signal sig to the signal handler
sig_handler. The sig argument must be one of the signal constants defined in
<signal.h>.

The meanings of the values of sig are as follows:

Value             Meaning
SIGABRT           Abnormal termination signal sent by the abort function.
                  Default action is to end the program with exit code 3.
SIGBREAK          Ctrl-Break signal. Default action is to end the program with
                  exit code 99.
SIGFPE            Floating-point exceptions that are not masked, such as
                  overflow, division by zero, and invalid operation.  Default
                  action is to end the program with exit code 99 and provide a
                  machine-state dump.
SIGILL            Instruction not allowed.  Default action is to end the
                  program with exit code 99 and provide a machine-state dump.
SIGINT            Ctrl-C signal. Default action is to end the program with exit
                  code 99.
SIGSEGV           Access to memory not valid. Default action is to end the
                  program with exit code 99 and provide a machine-state dump.
SIGTERM           Program termination signal sent by the user.  Default action
                  is to end the program with exit code 99.
SIGUSR1           Defined by the user. Default action is to ignore the signal.
SIGUSR2           Defined by the user. Default action is to ignore the signal.
SIGUSR3           Defined by the user. Default action is to ignore the signal.

Signals can be reported as a result of a machine interrupt (for example,
division by zero) or by an explicit request to report a signal by using the
raise function.

The sig_handler argument must be either the SIG_DFL or SIG_IGN constant, also
defined in <signal.h>, or the address of a function that takes an integer
argument (the signal).

The action taken when the interrupt signal is received depends on the value of
sig_handler:

Value           Meaning
SIG_DFL         This is the initial setting for all signals. For most signals,
                the system default is to end the program. All files controlled
                by the process are closed, but buffers are not flushed.  A
                machine-state dump is provided for SIGFPE, SIGILL, and SIGSEGV.
                The default response for the user-defined signals (SIGUSR1,
                SIGUSR2, and SIGUSR3) is to ignore them.
SIG_IGN         The interrupt signal is ignored.
SIG_HANDLER     Installs the specified function as the signal handler for the
                given signal.

For all signals, the function is passed two arguments. The first argument is
the signal number and the second is 0, unless the signal is SIG_FPE. For
SIG_FPE signals, the second argument passed is a floating-point error signal as
defined in <float.h>. If the signal handling function returns, the calling
process resumes running immediately following the point at which it received
the interrupt signal.

When a signal is reported and the sig_handler called, signal handling for that
signal is reset to the default. Depending on the purpose of the signal handler,
it can be desirable to reestablish the signal handling from within the
sig_handler function. You can also reset the default handling with an explicit
call to signal.

Signals and signal handlers are not shared between threads. If you do not
establish a signal handler within a thread, the default signal handling will be
used regardless of what handlers you may have established in other concurrent
threads.

Note:  If an exception occurs in a math or critical library function, it is
handled by the C/C++ Tools exception handler.  Your sig_handler will not be
called.

All calls to the signal function return the address of the previous handler for
the re-assigned signal.

A return value of SIG_ERR, defined in <signal.h>, indicates an error, and errno
is set to EINVAL. The possible causes of the error are an incorrect sig value
or an undefined value for func.

Example of signal


ΓòÉΓòÉΓòÉ <hidden> Example of signal ΓòÉΓòÉΓòÉ

/************************************************************************
*
In the following example, the call to signal in main establishes the function
handler to process the interrupt signal raised by abort.  An error value
returned from this call to signal causes the program to end with a printed
error message.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <signal.h>
#include <stdlib.h>

void handler(int sig)
{
    printf("Registered signal type for abort = %d\n", sig);
    printf("Abort should not flush this line");
}

int main(void)
{
    if (signal(SIGABRT, handler) == SIG_ERR)
    {
        perror("Could not set SIGABRT");
        exit(-1);
    }

    abort();   /* signal raised by abort */

    /* The expected output is:

       Registered signal type for abort = 5   */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o abort  - Stop a Program
o atexit  - Record Program Termination Function
o exit  - End Program
o _exit - End Process
o _fpreset - Reset Floating-Point Unit
o raise  - Send Signal
o _spawnl -_spawnvpe -Start and Run Child Processes
o signal.h


ΓòÉΓòÉΓòÉ 6.200. sin  - Calculate Sine ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h>

double sin(double x);     /* Calculate sine of x */


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The sin function calculates the sine of x, with x expressed in radians.

Example of sin


ΓòÉΓòÉΓòÉ <hidden> Example of sin ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example computes y as the sine of у/2.

                                                                        *
************************************************************************/

#include <math.h>
#include <stdio.h>

int main(void)
{
   double pi, x, y;

   pi = 3.1415926535;
   x = pi/2;
   y = sin(x);

   printf("sin( %lf ) = %lf\n", x, y);
}

/*********************  Output should be similar to:  *************

sin( 1.570796 ) = 1.000000
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o asin  - Calculate Arcsine
o _fasin - Calculate Arcsine
o _fcossin - Calculate Cosine and Sine
o _fsin - Calculate Sine
o _fsincos - Calculate Sine and Cosine
o sinh  - Calculate Hyperbolic Sine
o math.h


ΓòÉΓòÉΓòÉ 6.201. sinh  - Calculate Hyperbolic Sine ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h>

double sinh(double x);     /* Calculate hyperbolic sine of x */


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The sinh function calculates the hyperbolic sine of x, with x expressed in
radians. If the result is too large, sinh sets errno to ERANGE and returns the
value HUGE_VAL (positive or negative, depending on the value of x).

Example of sinh


ΓòÉΓòÉΓòÉ <hidden> Example of sinh ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example computes y as the hyperbolic sine of у/2.

                                                                        *
************************************************************************/

#include <math.h>
#include <stdio.h>

int main(void)
{
   double pi, x, y;

   pi = 3.1415926535;
   x = pi/2;
   y = sinh(x);

   printf("sinh( %lf ) = %lf\n", x, y);
}

/*********************  Output should be similar to:  *************

sinh( 1.570796 ) = 2.301299
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o asin  - Calculate Arcsine
o cosh  - Calculate Hyperbolic Cosine
o _fasin - Calculate Arcsine
o _fcossin - Calculate Cosine and Sine
o _fsin - Calculate Sine
o _fsincos - Calculate Sine and Cosine
o sin  - Calculate Sine
o tanh  - Calculate Hyperbolic Tangent
o math.h


ΓòÉΓòÉΓòÉ 6.202. _sopen - Open Shared File ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <fcntl.h>
#include <sys\stat.h>
#include <share.h>
#include <io.h>

int _sopen(char *pathname, int oflag, int shflag , int pmode);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _sopen function opens the file specified by pathname and prepares the file
for subsequent shared reading or writing as defined by oflag and shflag. The
oflag is an integer expression formed by combining one or more of the constants
defined in <fcntl.h>. When more than one constant is given, the constants are
joined with the OR operator (|).

Oflag          Meaning
O_APPEND       Reposition the file pointer to the end of the file before every
               write operation.
O_CREAT        Create and open a new file.  This flag has no effect if the file
               specified by pathname exists.
O_EXCL         Return an error value if the file specified by pathname exists.
               This flag applies only when used with O_CREAT.
O_RDONLY       Open the file for reading only.  If this flag is given, neither
               O_RDWR nor O_WRONLY can be given.
O_RDWR         Open the file for both reading and writing.  If this flag is
               given, neither O_RDONLY nor O_WRONLY can be given.
O_TRUNC        Open and truncate an existing file to 0 length. The file must
               have write permission. The contents of the file are destroyed.
               On the OS/2 operating system, do not specify O_TRUNC with
               O_RDONLY.
O_WRONLY       Open the file for writing only.  If this flag is given, neither
               O_RDONLY nor O_RDWR can be given.
O_BINARY       Open the file in binary (untranslated) mode. (See fopen. for a
               description of binary mode.)
O_TEXT         Open the file in text (translated) mode. (See fopen. for a
               description of text mode.)

The shflag argument is one of the following constants, defined in <share.h>.

Shflag          Meaning
SH_DENYRW       Deny read and write access to file
SH_DENYWR       Deny write access to file
SH_DENYRD       Deny read access to file
SH_DENYNO       Permit read and write access.

There is no default value for the shflag.

The pmode argument is an integer expression containing one or both of the
constants S_IWRITE and S_IREAD, defined in <sys\stat.h>. The pmode argument is
required only when O_CREAT is specified. If the file does not exist, pmode
specifies the permission settings of the file, which are set when the new file
is closed for the first time. If the file exists, the pmode argument is
ignored. The pmode argument is an integer expression containing one or both of
the constants S_IWRITE and S_IREAD. The meanings of the pmode argument are in
the following table.

Value                   Meaning
S_IWRITE                Writing permitted
S_IREAD                 Reading permitted
S_IREAD | S_IWRITE      Reading and writing permitted.

If write permission is not given, the file is read only.  On the OS/2 operating
system, all files are readable; you cannot give write-only permission.  Thus,
the modes S_IWRITE and S_IREAD | S_IWRITE are equivalent.

Specifying a pmode of S_IREAD is similar to making a file read-only with the
ATTRIB system command.

The _sopen function applies the current file permission mask to pmode before
setting the permissions. (See _umask - Sets File Mask of Current Process for
information on file permission masks.)

The _sopen function returns a file handle for the opened file. A return value
of -1 indicates an error, and errno is set to one of the following values:

Value          Meaning
EACCESS        The given path name is a directory, but the file is read-only
               and an open for writing was attempted, or a sharing violation
               occurred.
EEXIST         The O_CREAT and O_EXCL flags are specified, but the named file
               already exists.
EMFILE         No more file handles are available.
ENOENT         The file or path name was not found.
EINVAL         An incorrect argument was passed.
EOS2ERR        The call to the operating system was not successful.

Example of _sopen


ΓòÉΓòÉΓòÉ <hidden> Example of _sopen ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example opens the file sample.dat for shared reading and writing using
_sopen. It then opens the file for shared reading.

                                                                        *
************************************************************************/

#include <io.h>
#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>
#include <share.h>

int main(void)
{
   int  fh1, fh2;

   printf("\nCreating sample.dat.\n");
   system("echo Sample Program > sample.dat");

   /* share open the file for reading and writing */

   if (-1 == (fh1 = _sopen("sample.dat",O_RDWR,SH_DENYNO) ))
   {
      perror("_sopen failed");
      return 1;
   }

   /* share open the file for reading only */

   if (-1 == (fh2 = _sopen("sample.dat",O_RDONLY,SH_DENYNO) ))
   {
      perror("_sopen failed");
      _close(fh1);
      return 1;
   }

   printf("File sample.dat successfully opened for sharing.\n");
   _close(fh1);
   _close(fh2);
   return 0;
/*****************  The expected output is:  ****************************

      Creating sample.dat.
      File sample.dat successfully opened for sharing.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _close - Closes File Associated with Handle
o _creat - Create New File
o _open - Open File
o _fdopen - Associates Input Or Output With File
o fopen  - Open Files
o _sopen - Open Shared File
o _umask - Sets File Mask of Current Process
o fcntl.h
o io.h
o share.h
o sys\stat.h


ΓòÉΓòÉΓòÉ 6.203. _spawnl -_spawnvpe -Start and Run Child Processes ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <process.h>

int _spawnl(int modeflag, char *pathname, char *arg0, char *arg1, ...,
                char *argn, NULL);

int _spawnlp(int modeflag, char *pathname, char *arg0, char *arg1, ...,
                 char *argn, NULL);

int _spawnle(int modeflag, char *pathname, char *arg0, char *arg1, ...,
                 char *argn, NULL, char *envp[ ]);

int _spawnlpe(int modeflag, char *pathname, char *arg0, char *arg1, ...,
                  char *argn, NULL, char *envp[ ]);

int _spawnv(int modeflag, char *pathname, char *argv[ ]);

int _spawnvp(int modeflag, char *pathname, char *argv[ ]);

int _spawnve(int modeflag, char *pathname, char *argv[ ], char *envp[ ]);

int _spawnvpe(int modeflag, char *pathname, char *argv[ ], char *envp[ ])


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

Each of the _spawn functions creates and runs a new child process. Enough
storage must be available for loading and running the child process. All of the
_spawn functions are versions of the same routine; the letters at the end
determine the specific variation:

Letter   Variation
 p       Uses PATH environment variable to find the file to be run
 l       Lists command-line arguments separately
 v       Passes to the child process an array of pointers to command-line
         arguments
 e       Passes to the child process an array of pointers to environment
         strings.

The modeflag argument determines the action taken by the parent process before
and during the _spawn. The following values for modeflag are defined in
<process.h>.

Value          Meaning
P_WAIT         Suspend the parent process until the child process is complete.
P_NOWAIT       Continue to run the parent process concurrently.
P_OVERLAY      Start the child process, and then if successful, end the parent
               process.  (This has the same effect as _exec calls.)

The pathname argument specifies the file to run as the child process.  The
pathname can specify a full path (from the root), a partial path (from the
current working directory), or just a file name.  If pathname does not have a
file name extension or end with a period, the _spawn functions add the
extension .EXE and search for the file. If pathname has an extension, only that
extension is used.  If pathname ends with a period, the _spawn functions search
for pathname with no extension. The _spawnlp, _spawnlpe, _spawnvp, and
_spawnvpe functions search for pathname (using the same procedures) in the
directories specified by the PATH environment variable.

You pass arguments to the child process by giving one or more pointers to
character strings as arguments in the _spawn routine.  These character strings
form the argument list for the child process.

The argument pointers can be passed as separate arguments (_spawnl, _spawnle,
_spawnlp, and _spawnlpe) or as an array of pointers (_spawnv, _spawnve,
_spawnvp, and _spawnvpe).  At least one argument, either arg0 or argv[0], must
be passed to the child process.  By convention, this argument is a copy of the
pathname argument.  However, a different value will not produce an error.

Use the _spawnl, _spawnle, _spawnlp, and _spawnlpe routines in cases where you
know the number of arguments.  The arg0 is usually a pointer to pathname. The
arg1 through argn arguments are pointers to the character strings forming the
new argument list.  Following argn, there must be a NULL pointer to mark the
end of the argument list.

The _spawnv, _spawnve, _spawnvp, and _spawnvpe functions are useful when the
number of arguments to the child process is variable.  Pointers to the
arguments are passed as an array, argv.  The argv[0] argument is usually a
pointer to the pathname. The argv[1] through argv[n] arguments are pointers to
the character strings forming the new argument list.  The argv[n+1] argument
must be a NULL pointer to mark the end of the argument list.

Files that are open when a _spawn call is made remain open in the child
process.  In the _spawnl, _spawnlp, _spawnv, and _spawnvp calls, the child
process inherits the environment of the parent. The _spawnle, _spawnlpe,
_spawnve, and _spawnvpe functions let you alter the environment for the child
process by passing a list of environment settings through the envp argument.
The envp argument is an array of character pointers, each element of which
points to a null-terminated string, that defines an environment variable.  Such
a string has the form:

   NAME=value

where NAME is the name of an environment variable, and value is the string
value to which that variable is set.  (Notice that value is not enclosed in
double quotation marks.) The final element of the envp array should be NULL.
When envp itself is NULL, the child process inherits the environment settings
of the parent process.

Note:  Signal settings are not preserved in child processes created by calls to
       _spawn functions. The signal settings are reset to the default in the
       child process.

The return from a spawn has one of two different meanings.  The return value of
a synchronous spawn is the exit status of the child process.  The return value
of an asynchronous spawn is the process identification of the child process.
You can use the _wait or _cwait functions to get the child process exit code if
an asynchronous spawn was done.

A return value of -1 indicates an error (the child process is not started), and
errno is set to one of the following values:

Value       Meaning
EAGAIN      The limit of the number of processes that the OS/2 operating system
            permits has been reached.
EINVAL      The modeflag argument is incorrect.
ENOENT      The file or path name was not found or was not specified correctly.
ENOEXEC     The specified file is not executable or has an incorrect executable
            file format.
ENOMEM      Not enough storage is available to run the child process.

Example of _spawnl - _spawnvpe


ΓòÉΓòÉΓòÉ <hidden> Example of _spawnl - _spawnvpe ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example shows calls to four of the eight _spawn routines.  When called
without arguments from the command line, the program first runs the code for
case PARENT.  It spawns a copy of itself, waits for its child to run, then
spawns a second child.  The instructions for the child are blocked to run only
if argv[0] and one parameter were passed (case CHILD).  In its turn, each child
spawns a grandchild as a copy of the same program.  The grandchild instructions
are blocked by the existence of two passed parameters. The grandchild is
permitted to overlay the child.  Each of the processes prints a message
identifying itself.

                                                                        *
************************************************************************/

#include  <stdio.h>
#include  <process.h>
#define   PARENT        1
#define   CHILD         2
#define   GRANDCHILD    3

int main(int argc, char **argv, char **envp)
{
   int    result;
   char   *args[4];

   switch(argc)
   {
      case PARENT:
      /* no argument was passed:  spawn child and wait */
         result = _spawnle(P_WAIT, argv[0],
                               argv[0], "one", NULL, envp);
         if (result)
             abort();
         args[0] = argv[0];
         args[1] = "two";
         args[2] = NULL;

         /* spawn another child, and wait for it */
         result = _spawnve(P_WAIT, argv[0],
                      args, envp);
         if (result)
             abort();
         printf("Parent process ended\n");
         _exit(0);

      case CHILD:
      /* one argument passed:  allow grandchild to overlay */
         printf("child process %s began\n", argv[1]);
         if (*argv[1] == 'o')            /* child one? */
         {
            _spawnl(P_OVERLAY, argv[0],
                        argv[0], "one", "two", NULL);
            abort();
            /* not executed because child was overlaid */
         }
         if (*argv[1] == 't')            /* child two? */
         {
             args[0] = argv[0];
             args[1] = "two";
             args[2] = "one";
             args[3] = NULL;
             _spawnv(P_OVERLAY, argv[0], args);
             abort();
             /* not executed because child was overlaid */
         }
         abort();       /* argument not valid */

     case GRANDCHILD:   /* two arguments passed */
        printf("grandchild %s ran\n", argv[1]);
        _exit(0);
   }

/******  The output should be similar to:  *************

    child process one began
    grandchild one ran
    child process two began
    Parent process ended
    grandchild two ran
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o abort  - Stop a Program
o _cwait - Wait for Child Process
o _execl - _execvp - Load and Run Child Process
o exit  - End Program
o _exit - End Process
o _wait - Wait for Child Process
o process.h


ΓòÉΓòÉΓòÉ 6.204. _splitpath - Decompose Path Name ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

void _splitpath(char *path, char *drive, char *dir,
                    char *fname, char *ext);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _splitpath function decomposes an existing path name path into its four
components. The path should point to a buffer containing the complete path
name.

The maximum size necessary for each buffer is specified by the _MAX_DRIVE,
_MAX_DIR, _MAX_FNAME, and _MAX_EXT constants defined in <stdlib.h>.  The other
arguments point to the following buffers used to store the path name elements:

Buffer      Description
drive       Contains the drive letter followed by a colon (:) if a drive is
            specified in path.
dir         Contains the path of subdirectories, if any, including the trailing
            slash.  Slashes (/), backslashes (\), or both may be present in
            path.
fname       Contains the base file name without any extensions.
ext         Contains the file name extension, if any, including the leading
            period (.).

The return parameters contain empty strings for any path name components not
found in path.

There is no return value.

Example of _splitpath


ΓòÉΓòÉΓòÉ <hidden> Example of _splitpath ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example builds a file name path from the specified components, and then
extracts the individual components.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
   char path_buffer [_MAX_PATH];
   char drive [_MAX_DRIVE];
   char dir [_MAX_DIR];
   char fname [_MAX_FNAME];
   char ext [_MAX_EXT];

   _makepath (path_buffer, "c",
        "qc\\bob\\eclibref\\e", "makepath", "c");
   printf ("Path created with _makepath: %s\n\n",
        path_buffer);

   _splitpath (path_buffer, drive, dir, fname, ext);
   printf ("Path extracted with _splitpath:\n");
   printf ("drive: %s\n", drive);
   printf ("directory: %s\n", dir);
   printf ("file name: %s\n", fname);
   printf ("extension: %s\n", ext);

   return 0;

/************  The output should be similar to:  ********

   Path created with _makepath:
         c:qc\bob\eclibref\e\makepath.c

   Path extracted with _splitpath:
   drive: c:
   directory: qc\bob\eclibref\e\
   file name: makepath
   extension: .c
*/

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _fullpath - Get Full Path Name of Partial Path
o _getcwd - Get Path Name of Current Directory
o _getdcwd - Get Full Path Name of Current Directory
o _makepath - Create Path
o stdlib.h


ΓòÉΓòÉΓòÉ 6.205. sprintf  - Formatted Print to Buffer ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int sprintf(char *buffer, const char *format-string, argument-list);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA, Extension

The sprintf function formats and stores a series of characters and values in
the array buffer. Any argument-list is converted and put out according to the
corresponding format specification in the format-string.

The format-string consists of ordinary characters and has the same form and
function as the format-string argument for the printf function.  See printf for
a description of the format-string and arguments.

In extended mode, sprintf also converts floating-point values of NaN and
infinity to the strings "NAN" or "nan" and "INFINITY" or "infinity". The case
and sign of the string is determined by the format specifiers.  See Infinity
and NaN Support for more information on infinity and NaN values.

The sprintf function returns the number of characters written in the array, not
counting the ending null character.

Example of sprintf


ΓòÉΓòÉΓòÉ <hidden> Example of sprintf ΓòÉΓòÉΓòÉ

/************************************************************************
*

The following example uses sprintf to format and print various data.

                                                                        *
************************************************************************/

#include <stdio.h>

char buffer[200];
int i, j;
double fp;
char *s = "baltimore";
char c;

int main(void)
{
   c = 'l';
   i = 35;
   fp = 1.7320508;

   /* Format and print various data */
   j = sprintf(buffer, "%s\n", s);
   j += sprintf(buffer+j, "%c\n", c);
   j += sprintf(buffer+j, "%d\n", i);
   j += sprintf(buffer+j, "%f\n", fp);
   printf("string:\n%s\ncharacter count = %d\n", buffer, j);
}

/*********************  Output should be similar to:  *************

string:
baltimore
l
35
1.732051

character count = 24
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _cprintf - Print Characters to Screen
o fprintf  - Write Formatted Data
o printf  - Formatted Print
o sscanf  - Read Data
o Infinity and NaN Support
o vfprintf  - Print Argument Data
o vprintf  - Print Argument Data
o vsprintf  - Print Argument Data
o stdio.h


ΓòÉΓòÉΓòÉ 6.206. sqrt  - Calculate Square Root ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h>

double sqrt(double x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The sqrt function calculates the nonnegative value of the square root of x.

The sqrt function returns the square root result.  If x is negative, the
function sets errno to EDOM, and returns 0.

Example of sqrt


ΓòÉΓòÉΓòÉ <hidden> Example of sqrt ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example computes the square root of the quantity passed as the first
argument to main. It prints an error message if you pass a negative value.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>
#include <math.h>

int main(int argc, char ** argv)
{
  char * rest;
  double value;

  if ( argc != 2 )
    printf( "Usage: %s value\n", argv[0] );
  else
  {
    value = strtod( argv[1], &rest );
    if ( value < 0.0 )
       perror( "sqrt of a negative number" );
    else
       printf("sqrt( %lf ) = %lf\n", value, sqrt( value ));
  }
}

/********************  If the input is 45,  *****************************
****************  then the output should be similar to:  **********

sqrt( 45.000000 ) = 6.708204
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o exp  - Exponential Function
o _fsqrt -  Calculate Square Root
o hypot  - Calculate Hypotenuse
o log  - Calculate Natural Logarithm
o log10  - Calculate Base 10 Logarithm
o pow  - Compute Power
o math.h


ΓòÉΓòÉΓòÉ 6.207. srand  - Set Seed for rand Function ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

void srand(unsigned int seed);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The srand function sets the starting point for producing a series of
pseudo-random integers.  If srand is not called, the rand seed is set as if
srand(1) was called at program start.  Any other value for seed sets the
generator to a different starting point.

The rand function generates the pseudo-random numbers.

There is no return value.

Example of srand


ΓòÉΓòÉΓòÉ <hidden> Example of srand ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example first calls srand with a value other than 1 to initiate the random
value sequence.  Then the program computes 5 random values for the array of
integers called ranvals.

                                                                        *
************************************************************************/

#include <stdlib.h>
#include <stdio.h>

int main(void)
{
   int i, ranvals[5];

   srand(17);
   for (i = 0; i < 5; i++)
   {
      ranvals[i] = rand();
      printf("Iteration %d ranvals [%d] = %d\n", i+1, i, ranvals[i]);
   }
}

/******************  Output should be similar to:  ****************

Iteration 1 ranvals [0] = 24107
Iteration 2 ranvals [1] = 16552
Iteration 3 ranvals [2] = 12125
Iteration 4 ranvals [3] = 9427
Iteration 5 ranvals [4] = 13152
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o rand  - Generate Random Number
o stdlib.h


ΓòÉΓòÉΓòÉ 6.208. sscanf  - Read Data ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int sscanf(const char *buffer, const char *format, argument-list);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA, Extension

The sscanf function reads data from buffer into the locations given by
argument-list.  Each argument must be a pointer to a variable with a type that
corresponds to a type specifier in the format-string. See scanf for a
description of the format-string.

The sscanf function returns the number of fields that were successfully
converted and assigned.  The return value does not include fields that were
read but not assigned.

In extended mode, sscanf also reads in the strings the strings "INFINITY",
"INF", and "NAN" (in upper or lowercase) and converts them to the corresponding
floating-point value.  The sign of the value is determined by the format
specification. See Infinity and NaN Support for more information on infinity
and NaN values.

The return value is EOF when the end of the string is encountered before
anything is converted.

Example of sscanf


ΓòÉΓòÉΓòÉ <hidden> Example of sscanf ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses sscanf to read various data from the string tokenstring, and
then displays the data.

                                                                        *
************************************************************************/

#include <stdio.h>

#define  SIZE  81

char *tokenstring = "15 12 14";
int i;
float fp;
char s[SIZE];
char c;

int main(void)
{
   /* Input various data                              */
   sscanf(tokenstring, "%s %c%d%f", s, &c, &i, &fp);

   /* If there were no space between %s and %c,       */
   /* sscanf would read the first character following */
   /* the string, which is a blank space.             */

   /* Display the data */
   printf("string = %s\n",s);
   printf("character = %c\n",c);
   printf("integer = %d\n",i);
   printf("floating-point number = %f\n",fp);
}

/*****************  Output should be similar to:  *****************

string = 15
character = 1
integer = 2
floating-point number = 14.000000
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _cscanf - Read Data from Keyboard
o fscanf  - Read Formatted Data
o scanf  - Read Data
o sprintf  - Formatted Print to Buffer
o Infinity and NaN Support
o stdio.h


ΓòÉΓòÉΓòÉ 6.209. _stat - Get Information about File or Directory ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <sys\types.h>
#include <sys\stat.h>

int _stat(const char *pathname, struct stat *buffer);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _stat function stores information about the file or directory specified by
pathname in the structure to which buffer points.  The _stat structure, defined
in <sys\stat.h>, contains the following fields:

Field          Value
st_mode        Bit mask for file-mode information. The _stat function sets the
               S_IFCHR bit if handle refers to a device. The S_IFDIR bit is set
               if pathname specifies a directory. The S_IFREG bit is set if
               pathname specifies an ordinary file.  User read/write bits are
               set according to the permission mode of the file. The S_IEXEC
               bit is set using the file name extension. The other bits are
               undefined.

                                        F E D C B A 9 8 7 6 5 4 3 2 1 0
                                        Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöé Γöé
                                        ΓööΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓö┤ΓöÇΓöÿ

                                  S_IFREGΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Γöé Γöé     Γöé Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇexecute/search permission,
                              (regular file)     Γöé Γöé     Γöé Γöé     owner (S_IEXEC)
                                  S_IFDIRΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Γöé     Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇwrite permission, owner
                                  S_IFCHRΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ     ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇread permission, owner

st_dev         Drive number of the disk containing the file.
st_rdev        Drive number of the disk containing the file (same as st_dev).
st_nlink       Always 1.
st_size        Size of the file in bytes.
st_atime       Time of last modification of file.
st_mtime       Same as st_atime if not provided by the file system.
st_ctime       Same as st_atime if not provided by the file system.

Note:  If the given pathname specifies only a device (for example C:\), _stat
returns an error, and fields in the _stat structure are not meaningful.

The _stat function returns the value 0 if the file status information is
obtained.  A return value of -1 indicates an error, and errno is set to ENOENT,
indicating that the file name or path name could not be found.

Example of _stat


ΓòÉΓòÉΓòÉ <hidden> Example of _stat ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example requests that the status information for the file test.exe be
placed into the structure buf.  If the request is successful and the file is
executable, the example runs test.exe.

                                                                        *
************************************************************************/

#include <sys\types.h>
#include <sys\stat.h>
#include <process.h>
#include <stdio.h>

int main(void)
{
    struct stat buf;

    if (_stat("test.exe", &buf) == 0)
    {
        if ( (buf.st_mode & S_IFREG) &&
                       (buf.st_mode & S_IEXEC) )
                              _execl("test.exe", "test", NULL);
            /* file is executable */
    }
    else
        printf("File could not be found\n");

    return 0;

    /* The source for test.exe

        #include <stdio.h>

        int main(void)
        {                                                                      */
            puts("test.exe is an executable file");
        }                                                                      */
                                         */

/**********  The output should be similar to:  ***********

   test.exe is an executable file
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _fstat - Information about Open File
o sys\stat.h
o sys\types.h


ΓòÉΓòÉΓòÉ 6.210. _status87 - Get Floating-Point Status Word ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <float.h>  /* also defined in <builtin.h> */

unsigned int _status87(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _status87 function gets the current floating-point status word. The
floating-point status word is a combination of the numeric coprocessor status
word and other conditions detected by the numeric exception handler, such as
floating-point stack underflow and overflow.

The bits in the value returned reflect the floating-point status for the
current thread only before the call was made. The _status87 function does not
affect any other threads that may be processing.

Example of _status87


ΓòÉΓòÉΓòÉ <hidden> Example of _status87 ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses _status87 to get the value of the floating-point status word.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <float.h>

double a = 1e-40, b;
float x, y;

int main(void)
{
    printf("status = 0x%.4x - clear\n", _status87( ));

   /* change control word to mask all exceptions */
    _control87(0x037f,0xffff);

    y = a;         /* store into y is inexact and causes underflow */
    printf("status = 0x%.4X - inexact, underflow\n", _status87( ));

   /* reinitialize the floating point unit */
    _fpreset();

   /* change control word to mask all exceptions */
    _control87(0x037f,0xffff);

    b = y;         /* y is denormal */
    printf("status = 0x%.4X - denormal\n", _status87());

   /* reinitialize the floating point unit */
    _fpreset();

   return 0;

   /* The expected output is:

      status = 0x0000 - clear
      status = 0x0030 - inexact, underflow
      status = 0x0002 - denormal                */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _clear87 - Clear Floating-Point Status Word
o _control87 - Set Floating-Point Status Word
o _fpreset - Reset Floating-Point Unit
o float.h


ΓòÉΓòÉΓòÉ 6.211. strcat  - Concatenate Strings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

char *strcat(char *string1, const char *string2);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The strcat function concatenates string2 to string1 and ends the resulting
string with the null character.

The strcat function operates on null-terminated strings. The string arguments
to the function should contain a null character (\0) marking the end of the
string. No length checking is performed. Do not use a literal string for a
string1 value, although string2 may be a literal string.

If the storage of string1 overlaps the storage of string2, the behavior is
undefined. The strcat function returns a pointer to the concatenated string
(string1).

Example of strcat


ΓòÉΓòÉΓòÉ <hidden> Example of strcat ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example creates the string "computer program" using strcat.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>

#define SIZE 40


int main(void)
{
  char buffer1[SIZE] = "computer";
  char * ptr;

  ptr = strcat( buffer1, " program" );
  printf( "buffer1 = %s\n", buffer1 );

}

/*****************  Output should be similar to:  *****************

computer program
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strchr  - Search for Character
o strcmp  - Compare Strings
o strcpy  - Copy Strings
o strcspn  - Compare Strings
o strncat  - Concatenate Strings
o wcscat  - Append wchar_t Strings
o wcsncat  - Concatenate wchar_t Strings
o string.h


ΓòÉΓòÉΓòÉ 6.212. strchr  - Search for Character ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

char *strchr(const char *string, int c);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The strchr function finds the first occurrence of a character in a string. The
character c can be the null character (\0); the ending null character of string
is included in the search.

The strchr function operates on null-terminated strings. The string arguments
to the function should contain a null character (\0) marking the end of the
string.

The strchr function returns a pointer to the first occurrence of c converted to
a character in string. The function returns NULL if the ending null character
is not found.

Example of strchr


ΓòÉΓòÉΓòÉ <hidden> Example of strchr ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example finds the first occurrence of the character p in "computer
program".

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>

#define SIZE 40

int main(void)
{
  char buffer1[SIZE] = "computer program";
  char * ptr;
  int    ch = 'p';

  ptr = strchr( buffer1, ch );
  printf( "The first occurrence of %c in '%s' is '%s'\n",
            ch, buffer1, ptr );

}

/*****************  Output should be similar to:  *****************

The first occurrence of p in 'computer program' is 'puter program'
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strcmp  - Compare Strings
o strcspn  - Compare Strings
o strncmp  - Compare Strings
o strpbrk  - Find Characters in String
o strrchr  - Find Last Occurrence of Character in String
o strspn  - Search Strings
o wcschr  - Search wchar_t String for Given wchar_t
o wcsspn  - Search wchar_t Characters in String
o string.h


ΓòÉΓòÉΓòÉ 6.213. strcmp  - Compare Strings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

int strcmp(const char *string1, const char *string2);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The strcmp function compares string1 and string2.

The function operates on null-terminated strings. The string arguments to the
function should contain a null character (\0) marking the end of the string.
The strcmp function returns a value indicating the relationship between the two
strings, as follows:

Value               Meaning
Less than 0         string1 less than string2
0                   string1 identical to string2
Greater than 0      string1 greater than string2.

Example of strcmp


ΓòÉΓòÉΓòÉ <hidden> Example of strcmp ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example compares the two strings passed to main using strcmp.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>

int main(int argc, char ** argv)
{
  int  result;

  if ( argc != 3 )
  {
    printf( "Usage: %s string1 string2\n", argv[0] );
  }
  else
  {

    result = strcmp( argv[1], argv[2] );

    if ( result == 0 )
      printf( "\"%s\" is identical to \"%s\"\n", argv[1], argv[2] );
    else if ( result < 0 )
      printf( "\"%s\" is less than \"%s\"\n", argv[1], argv[2] );
    else
      printf( "\"%s\" is greater than \"%s\"\n", argv[1], argv[2] );
  }
}

/****************  If the input is the strings  *************************
***********  "is this first?" and "is this before that one?",  **********
******************  then the expected output is:  *****************

"is this first?" is greater than "is this before that one?"
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strcmpi - Compare Strings
o strcoll  - Compare Strings
o strcspn  - Compare Strings
o stricmp - Compare Strings
o strncmp  - Compare Strings
o strnicmp - Compare Strings
o wcscmp  - Compare wchar_t Strings
o wcsncmp  - Compare wchar_t Strings
o string.h


ΓòÉΓòÉΓòÉ 6.214. strcmpi - Compare Strings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

int strcmpi(const char *string1, const char *string2);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The strcmpi function compares string1 and string2 without sensitivity to case.
All alphabetic characters in the two arguments string1 and string2 are
converted to lowercase before the comparison.

The function operates on null-ended strings. The string arguments to the
function are expected to contain a null character (\0) marking the end of the
string.

The strcmpi function returns a value indicating the relationship between the
two strings, as follows:

Value             Meaning
Less than 0       string1 less than string2
0                 string1 equivalent to string2
Greater than 0    string1 greater than string2.

Example of strcmpi


ΓòÉΓòÉΓòÉ <hidden> Example of strcmpi ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses strcmpi to compare two strings:

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>

int main(void)
{
    /* Compare two strings without regard to case */

    if (0 == strcmpi("hello","HELLO"))
       printf("The strings are equivalent.\n");
    else
       printf("The strings are not equivalent.\n");

    return 0;

/***************  The output should be similar to:  *********************

     The strings are equivalent.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ


o strcoll  - Compare Strings
o strcspn  - Compare Strings
o strdup - Duplicate String
o stricmp - Compare Strings
o strncmp  - Compare Strings
o strnicmp - Compare Strings
o wcscmp  - Compare wchar_t Strings
o wcsncmp  - Compare wchar_t Strings
o string.h


ΓòÉΓòÉΓòÉ 6.215. strcoll  - Compare Strings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

int strcoll(const char *string1, const char *string2);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The strcoll function compares two strings using the collating sequence
specified by the program's locale.

The strcoll function returns a value indicating the relationship between the
strings, as listed below.

Value               Meaning
Less than 0         string1 less than string2
0                   string1 equivalent to string2
Greater than 0      string1 greater than string2

Example of strcoll


ΓòÉΓòÉΓòÉ <hidden> Example of strcoll ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example compares the two strings passed to main.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>

int main(int argc, char ** argv)
{
  int  result;

  if ( argc != 3 )
  {
    printf( "Usage: %s string1 string2\n", argv[0] );
  }
  else
  {

    result = strcoll( argv[1], argv[2] );

    if ( result == 0 )
      printf( "\"%s\" is identical to \"%s\"\n", argv[1], argv[2] );
    else if ( result < 0 )
      printf( "\"%s\" is less than \"%s\"\n", argv[1], argv[2] );
    else
      printf( "\"%s\" is greater than \"%s\"\n", argv[1], argv[2] );
  }
}

/******************  If the input is the strings  ***********************
****************  "firststring" and "secondstring",  ********************
******************  then the expected output is:  *****************

"firststring" is less than "secondstring"
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o setlocale  - Set Locale
o strcmp  - Compare Strings
o strcmpi - Compare Strings
o stricmp - Compare Strings
o strncmp  - Compare Strings
o strnicmp - Compare Strings
o strcspn  - Compare Strings
o wcscmp  - Compare wchar_t Strings
o wcsncmp  - Compare wchar_t Strings
o string.h


ΓòÉΓòÉΓòÉ 6.216. strcpy  - Copy Strings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

char *strcpy(char *string1, const char *string2);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The strcpy function copies string2, including the ending null character, to the
location specified by string1

The strcpy function operates on null-terminated strings. The string arguments
to the function should contain a null character (\0) marking the end of the
string. No length checking is performed. You should not use a literal string
for a string1 value, although string2 may be a literal string.

The strcpy function returns string1.

Example of strcpy


ΓòÉΓòÉΓòÉ <hidden> Example of strcpy ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example copies the contents of source to destination.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>

#define SIZE    40

int main(void)
{
  char source[ SIZE ] = "This is the source string";
  char destination[ SIZE ] = "And this is the destination string";
  char * return_string;

  printf( "destination is originally = \"%s\"\n", destination );
  return_string = strcpy( destination, source );
  printf( "After strcpy, destination becomes \"%s\"\n", destination );
}

/*****************  Output should be similar to:  *****************

destination is originally = "And this is the destination string"
After strcpy, destination becomes "This is the source string"
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strcat  - Concatenate Strings
o strdup - Duplicate String
o strncpy  - Copy Strings
o wcscpy  - Copy wchar_t Strings
o wcsncpy  - Copy wchar_t Strings
o string.h


ΓòÉΓòÉΓòÉ 6.217. strcspn  - Compare Strings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

size_t strcspn(const char *string1, const char *string2);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The strcspn function finds the first occurrence of a character in string1 that
belongs to the set of characters specified by string2. Ending null characters
are not considered in the search.

The strcspn function operates on null-terminated strings. The string arguments
to the function should contain a null character (\0) marking the end of the
string.

The strcspn function returns the index of the first character found. This value
is equivalent to the length of the initial substring of string1 that consists
entirely of characters not in string2.

Example of strcspn


ΓòÉΓòÉΓòÉ <hidden> Example of strcspn ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses strcspn to find the first occurrence of any of the characters
a, x, l or e in string.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>

#define SIZE    40

int main(void)
{
  char string[ SIZE ] = "This is the source string";
  char * substring = "axle";

  printf( "The first %i characters in the string \"%s\" "
          "are not in the string \"%s\" \n",
            strcspn(string, substring), string, substring);

}

/**********  Output should be similar to:  **************

The first 10 characters in the string "This is the source string"
are not in the string "axle"
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strchr  - Search for Character
o strcmp  - Compare Strings
o strcmpi - Compare Strings
o stricmp - Compare Strings
o strncmp  - Compare Strings
o strnicmp - Compare Strings
o strpbrk  - Find Characters in String
o strspn  - Search Strings
o wcscmp  - Compare wchar_t Strings
o wcsncmp  - Compare wchar_t Strings
o string.h


ΓòÉΓòÉΓòÉ 6.218. _strdate - Copy Current Date ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <time.h>

char *_strdate(char *date);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _strdate function stores the current date as a string in the buffer pointed
to by date in the following format:

   mm/dd/yy

The two digits mm represent the month, the digits dd represent the day of the
month, and the digits yy represent the year.  For example, the string 10/08/91
represents October 8, 1991. The buffer must be at least 9 bytes.

Note:  The time and date functions begin at 00:00 Coordinated Universal Time,
January 1, 1970.

The _strdate function returns a pointer to the buffer containing the date
string.  There is no error return.

Example of _strdate


ΓòÉΓòÉΓòÉ <hidden> Example of _strdate ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example prints the current date:

                                                                        *
************************************************************************/

#include <stdio.h>
#include <time.h>

int main(void)
{
    char buffer [9];

    printf("The current date is %s \n", _strdate(buffer));

    return 0;

/**************  The output should be similar to:  **********************

     The current date is 03/21/93
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o asctime  - Convert Time
o ctime  - Convert Time
o gmtime  - Convert Time
o localtime  - Convert Time
o mktime  - Convert Local Time
o time  - Determine Current Time
o _tzset - Assign Values to Locale Information
o time.h


ΓòÉΓòÉΓòÉ 6.219. strdup - Duplicate String ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

char *strdup(const char *string);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension &ipfisyn. root=copy.copy copying duplicate
duplicating

The strdup function reserves storage space for a copy of string by calling
malloc. The string argument to this function is expected to contain a null
character (\0) marking the end of the string.

The strdup function returns a pointer to the storage space containing the
copied string. If it cannot reserve storage strdup returns NULL.

Example of strdup


ΓòÉΓòÉΓòÉ <hidden> Example of strdup ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses strdup to duplicate a string and print the copy.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>

int main(void)
{
    char *string = "this is a copy";
    char *newstr;

    /* Make newstr point to a duplicate of str3 */
    if ( (newstr = strdup(string)) != NULL )
        printf("The new string is: %s\n", newstr);

    return 0;

    /* The expected ouput:

       The new string is: this is a copy  */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strcpy  - Copy Strings
o strncpy  - Copy Strings
o wcscpy  - Copy wchar_t Strings
o wcsncpy  - Copy wchar_t Strings
o string.h


ΓòÉΓòÉΓòÉ 6.220. strerror  - Set Pointer to Runtime Error Message ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

char *strerror(int errnum);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The strerror function maps the error number in errnum to an error message
string. The strerror function returns a pointer to the string. It does not use
the program locale in any way.

Example of strerror


ΓòÉΓòÉΓòÉ <hidden> Example of strerror ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example opens a file and prints a runtime error message if an error
occurs.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>
#include <errno.h>

int main(void)
{
   FILE *stream;
   .
   .
   .
   if ((stream = fopen("myfile.dat", "r")) == NULL)
      printf(" %s \n", strerror(errno));
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o clearerr  - Reset Error Indicators
o ferror  - Test for Read/Write Errors
o perror  - Print Error Message
o _strerror - Set Pointer to System Error String
o string.h


ΓòÉΓòÉΓòÉ 6.221. _strerror - Set Pointer to System Error String ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

char *_strerror(char *string);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _strerror function tests for system error. It gets the system error message
for the last library call that produced an error and prefaces it with your
string message.

Your string message can be a maximum of 94 bytes.

Unlike perror, _strerror by itself does not print a message.  To print the
message returned by _strerror to stdout, use a printf statement similar to the
following:

   if ((access("datafile",2)) == -1)
      printf(stderr,_strerror(NULL));

You could also print the message to stderr with an fprintf statement.

To produce accurate results, call _strerror immediately after a library
function returns with an error.  Otherwise, subsequent calls might write over
the errno value.

If string is equal to NULL, _strerror returns a pointer to a string containing
the system error message for the last library call that produced an error,
ended by a new-line character (\n).

If string is not equal to NULL, _strerror returns a pointer to a string
containing:

o Your string message
o A colon
o A space
o The system error message for the last library call producing an error
o A new-line character (\n).

Example of _strerror


ΓòÉΓòÉΓòÉ <hidden> Example of _strerror ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example shows how _strerror can be used with the fopen function.

                                                                        *
************************************************************************/

#include <string.h>
#include <stdio.h>

int main(void)
{
    FILE *fh1, *fh2;

    fh1 = fopen("data1","r");
    if (fh1 == NULL)
    /*  the error message goes through stdout not stderr  */
        printf(_strerror("Open failed on input file"));

    fh2 = fopen("data2","w+");
    if (fh2 == NULL)
       printf(_strerror("Open failed on output file"));
    else
       printf("Open on output file was successful.\n");

    if (fh1 != NULL)
       fclose(fh1);
    if (fh2 != NULL)
       fclose(fh2);

    return 0;


/***************  The output should be similar to:  *********************

   Open failed on input file: The file cannot be found.
   Open on output file was successful.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o clearerr  - Reset Error Indicators
o ferror  - Test for Read/Write Errors
o perror  - Print Error Message
o strerror  - Set Pointer to Runtime Error Message
o string.h


ΓòÉΓòÉΓòÉ 6.222. strftime  - Convert to Formatted Time ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <time.h>

size_t strftime(char *dest, size_t maxsize, const char *format,
                   const struct tm *timeptr);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The strftime function places characters into the array pointed to by dest
according to the string pointed to by format.  The format string is a multibyte
character string. This function uses the current locale.

The format string contains:

o Conversion specification characters
o Multibyte characters that are placed unchanged into the array.

The characters that are converted are determined by the locale and by the
values in the time structure pointed to by timeptr.  The conversion specifiers
and their meanings are listed below:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé SPECIFIERΓöé MEANING                              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "%a"   Γöé Insert abbreviated weekday name of locale.             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "%A"   Γöé Insert full weekday name of locale.                Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "%b"   Γöé Insert abbreviated month name of locale.              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "%B"   Γöé Insert full month name of locale.                 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "%c"   Γöé Insert date and time of locale.                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "%d"   Γöé Insert day of the month (01-31).                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "%H"   Γöé Insert hour (24-hour clock) as a decimal number (00-23).      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "%I"   Γöé Insert hour (12-hour clock) as a decimal number (01-12).      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "%j"   Γöé Insert day of the year (001-366).                 Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "%m"   Γöé Insert month (01-12).                       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "%M"   Γöé Insert minute (00-59).                       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "%p"   Γöé Insert equivalent of either AM or PM of locale.          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "%S"   Γöé Insert second (00-61).                       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "%U"   Γöé Insert week number of the year (00-53) where Sunday is the first  Γöé
Γöé      Γöé day of the week.                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "%w"   Γöé Insert weekday (0-6) where Sunday is 0.              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "%W"   Γöé Insert week number of the year (00-53) where Monday is the first  Γöé
Γöé      Γöé day of the week.                          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "%x"   Γöé Insert date representation of locale.               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "%X"   Γöé Insert time representation of locale.               Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "%y"   Γöé Insert year without the century (00-99).              Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "%Y"   Γöé Insert year.                            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "%Z"   Γöé Insert name of time zone, or no characters if time zone is not   Γöé
Γöé      Γöé available.                             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé "%%"   Γöé Insert %.                             Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The behavior is undefined when objects being copied overlap. maxsize specifies
the maximum number of characters that can be copied into the array.

The strftime function returns the number of characters (bytes) placed into the
array, not including the terminating null character.  On error, 0 is returned.

Note:  The time and date functions begin at 00:00 Universal Time, January 1,
1970.

Example of strftime


ΓòÉΓòÉΓòÉ <hidden> Example of strftime ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example places characters into the array dest and prints the resulting
string.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <time.h>

int main(void)
{
  char dest[70];
  int ch;
  time_t temp;
  struct tm *timeptr;

  temp = time(NULL);
  timeptr = localtime(&temp);
  ch = strftime(dest,sizeof(dest)-1,"Today is %A,"
              " %b %d. \n Time: %I:%M %p", timeptr);
  printf("%d characters placed in string to make: \n \n %s", ch, dest);
}

/*****************  Output should be similar to:  *****************

44 characters placed in string to make:

 Today is Wednesday, Oct 23.
 Time: 03:07 PM
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o asctime  - Convert Time
o ctime  - Convert Time
o gmtime  - Convert Time
o localtime  - Convert Time
o setlocale  - Set Locale
o time  - Determine Current Time
o time.h


ΓòÉΓòÉΓòÉ 6.223. stricmp - Compare Strings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

int stricmp(const char *string1, const char *string2);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The stricmp function compares string1 and string2 without sensitivity for case.
All alphabetic characters in the arguments string1 and string2 are converted to
lowercase before the comparison. The stricmp function operates on
null-terminated strings.

The function returns a value that indicates the following relationship between
the two strings :

Value             Meaning
Less than 0       string1 less than string2
0                 string1 identical to string2
Greater than 0    string1 greater than string2.

Example of stricmp


ΓòÉΓòÉΓòÉ <hidden> Example of stricmp ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example uses stricmp to compare two strings.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>

int main(void)
{
    char *str1 = "this is a string";
    char *str2 = "THIS IS A STRING";

    /* Compare two strings without regard to case */
    if ( stricmp( str1,str2 ) )
       printf("str1 is not the same as str2\n");
    else
       printf("str1 is the same as str2\n");

    return 0;

    /* The expected output is:

       str 1 is the same as str 2   */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strcmp  - Compare Strings
o strcmpi - Compare Strings
o strcspn  - Compare Strings
o strncmp  - Compare Strings
o strnicmp - Compare Strings
o wcscmp  - Compare wchar_t Strings
o wcsncmp  - Compare wchar_t Strings
o string.h
o strnicmp - Compare Strings


ΓòÉΓòÉΓòÉ 6.224. strlen  - Determine String Length ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

size_t strlen(const char *string);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The strlen function determines the length of string excluding the terminating
null character.

The strlen function returns the length of string.

Example of strlen


ΓòÉΓòÉΓòÉ <hidden> Example of strlen ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example determines the length of the string that is passed to main.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>

int main(int argc, char ** argv)
{

  if ( argc != 2 )
    printf( "Usage: %s string\n", argv[0] );
  else
    printf( "Input string has a length of %i\n", strlen( argv[1] ));
}

/******************  If the input is the string  ***********************
*****************"How long is this string?", ******************
******************  then the expected output is:  *****************

Input string has a length of 24
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o mblen  - Multibyte String Length
o strrev - Reverse String
o wcslen  - Calculate Length of wchar_t String
o string.h


ΓòÉΓòÉΓòÉ 6.225. strlwr - Convert Uppercase to Lowercase ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

char *strlwr(char *string);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The strlwr function converts any uppercase letters in the given null-terminated
string to lowercase.  Other characters are not affected.

The strlwr function returns a pointer to the converted string. There is no
error return.

Example of strlwr


ΓòÉΓòÉΓòÉ <hidden> Example of strlwr ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example makes a copy in all lowercase of the string "General Assembly",
and then prints the copy.

                                                                        *
************************************************************************/

#include <string.h>
#include <stdio.h>

int main(void)
{
    char *string="General Assembly";
    char *copy;

    copy = strlwr(strdup(string));

    printf("Expected result: general assembly\n");
    printf("strlwr returned: %s\n", copy);

    return 0;

    /* The expected output is:

       Expected result: general assembly
       strlwr returned: general assembly  */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strupr - Convert Lowercase to Uppercase
o _toascii - _tolower - _toupper - Convert Character
o tolower - toupper  - Convert Character Case
o string.h


ΓòÉΓòÉΓòÉ 6.226. strncat  - Concatenate Strings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

char *strncat(char *string1, const char *string2, size_t count);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The strncat function appends the first count characters of string2 to string1
and ends the resulting string with a null character (\0). If count is greater
than the length of string2, the length of string2 is used in place of count.

The strncat function operates on null-terminated strings. The string argument
to the function should contain a null character (\0) marking the end of the
string.

The strncat function returns a pointer to the joined string (string1).

Example of strncat


ΓòÉΓòÉΓòÉ <hidden> Example of strncat ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example demonstrates the difference between strcat and strncat.  strcat
appends the entire second string to the first, whereas strncat appends only the
specified number of characters in the second string to the first.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>

#define SIZE 40


int main(void)
{
  char buffer1[SIZE] = "computer";
  char * ptr;

  /* Call strcat with buffer1 and " program" */

  ptr = strcat( buffer1, " program" );
  printf( "strcat : buffer1 = \"%s\"\n", buffer1 );

  /* Reset buffer1 to contain just the string "computer" again */

  memset( buffer1, '\0', sizeof( buffer1 ));
  ptr = strcpy( buffer1, "computer" );

  /* Call strncat with buffer1 and " program" */
  ptr = strncat( buffer1, " program", 3 );
  printf( "strncat: buffer1 = \"%s\"\n", buffer1 );
}

/*****************  Output should be similar to:  *****************

strcat : buffer1 = "computer program"
strncat: buffer1 = "computer pr"
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strcat  - Concatenate Strings
o strnicmp - Compare Strings
o wcscat  - Append wchar_t Strings
o wcsncat  - Concatenate wchar_t Strings
o string.h


ΓòÉΓòÉΓòÉ 6.227. strncmp  - Compare Strings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

int strncmp(const char *string1, const char *string2, size_t count);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The strncmp function compares the first count characters of string1 and
string2.

The strncmp function returns a value indicating the relationship between the
substrings, as follows:

Value               Meaning
Less than 0         substring1 less than substring2
0                   substring1 equivalent to substring2
Greater than 0      substring1 greater than substring2

Example of strncmp


ΓòÉΓòÉΓòÉ <hidden> Example of strncmp ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example demonstrates the difference between strcmp and strncmp.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>

#define SIZE 10

int main(void)
{
  int  result;
  int  index = 3;
  char buffer1[SIZE] = "abcdefg";
  char buffer2[SIZE] = "abcfg";
  void print_result( int, char *, char * );

  result = strcmp( buffer1, buffer2 );
  printf( "Comparison of each character\n" );
  printf( "  strcmp: " );
  print_result( result, buffer1, buffer2 );

  result = strncmp( buffer1, buffer2, index);
  printf( "\nComparison of only the first %i characters\n", index );
  printf( "  strncmp: " );
  print_result( result, buffer1, buffer2 );
}

void print_result( int res, char * p_buffer1, char * p_buffer2 )
{
  if ( res == 0 )
    printf( "\"%s\" is identical to \"%s\"\n", p_buffer1, p_buffer2);
  else if ( res < 0 )
    printf( "\"%s\" is less than \"%s\"\n", p_buffer1, p_buffer2 );
  else
    printf( "\"%s\" is greater than \"%s\"\n", p_buffer1, p_buffer2 );
}

/*****************  Output should be similar to:  *****************

Comparison of each character
  strcmp: "abcdefg" is less than "abcfg"

Comparison of only the first 3 characters
  strncmp: "abcdefg" is identical to "abcfg"
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strcmp  - Compare Strings
o strcmpi - Compare Strings
o strcoll  - Compare Strings
o strcspn  - Compare Strings
o stricmp - Compare Strings
o strnicmp - Compare Strings
o wcscmp  - Compare wchar_t Strings
o wcsncmp  - Compare wchar_t Strings
o string.h


ΓòÉΓòÉΓòÉ 6.228. strncpy  - Copy Strings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

char *strncpy(char *string1, const char *string2, size_t count);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The strncpy function copies count characters of string2 to string1. If count is
less than or equal to the length of string2, a null character (\0) is not
appended to the copied string. If count is greater than the length of string2,
the string1 result is padded with null characters (\0) up to length count.

The strncpy function returns string1.

Example of strncpy


ΓòÉΓòÉΓòÉ <hidden> Example of strncpy ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example demonstrates the difference between strcpy and strncpy.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>

#define SIZE    40

int main(void)
{
  char source[ SIZE ] = "123456789";
  char source1[ SIZE ] = "123456789";
  char destination[ SIZE ] = "abcdefg";
  char destination1[ SIZE ] = "abcdefg";
  char * return_string;
  int    index = 5;

  /* This is how strcpy works */
  printf( "destination is originally = '%s'\n", destination );
  return_string = strcpy( destination, source );
  printf( "After strcpy, destination becomes '%s'\n\n", destination );


  /* This is how strncpy works */
  printf( "destination1 is originally = '%s'\n", destination1 );
  return_string = strncpy( destination1, source1, index );
  printf( "After strncpy, destination1 becomes '%s'\n", destination1 );
}

/*****************  Output should be similar to:  *****************

destination is originally = 'abcdefg'
After strcpy, destination becomes '123456789'

destination1 is originally = 'abcdefg'
After strncpy, destination1 becomes '12345fg'
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strcpy  - Copy Strings
o strdup - Duplicate String
o strnicmp - Compare Strings
o string.h


ΓòÉΓòÉΓòÉ 6.229. strnicmp - Compare Strings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

int strnicmp(const char *string1, const char *string2, int n);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The strnicmp function operates on, at most, the first n characters of
null-terminated strings. This function compares, at most, the first n
characters of string1 and string2.

The strnicmp function is case insensitive; the uppercase and lowercase forms of
a letter are considered equivalent.

The strnicmp returns a value indicating the relationship between the
substrings, as listed below.

Value             Meaning
Less than 0       substring1 less than substring2
0                 substring1 equivalent to substring2
Greater than 0    substring1 greater than substring2.

Example of strnicmp


ΓòÉΓòÉΓòÉ <hidden> Example of strnicmp ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example uses strnicmp to compare two strings.

                                                                        *
************************************************************************/

#include <string.h>
#include <stdio.h>

int main(void)
{
    char *str1 = "THIS IS THE FIRST STRING";
    char *str2 = "This is the second string";
    int numresult;

    /* Compare the first 11 characters of
       str1 and str2 without regard to case */
    numresult = strnicmp(str1, str2, 11);

    if (numresult < 0)
       printf("String 1 is less than string2.\n");
    else
       if (numresult > 0)
          printf("String 1 is greater than string2.\n");
       else
          printf("The two strings are equivalent.\n");

    return 0;

    /* The expected output is:

       The two strings are equivalent. */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strcmp  - Compare Strings
o strcmpi - Compare Strings
o stricmp - Compare Strings
o strncmp  - Compare Strings
o wcscmp  - Compare wchar_t Strings
o wcsncmp  - Compare wchar_t Strings
o string.h


ΓòÉΓòÉΓòÉ 6.230. strnset - strset - Set Characters in String ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

char *strnset(char *string, int c, size_t n);

char *strset(char *string, int c);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The strnset function sets at most the first n characters of string to c
(converted to a char). If n is greater than the length of string, the length of
string is used in place of n. The strset function sets all characters of string
except the ending null character (\0) to c (converted to a char).

For both functions, the string must be initialized and must end with a null
character (\0).

Both strset and strnset return a pointer to the altered string. There is no
error return value.

Example of strnset and strset


ΓòÉΓòÉΓòÉ <hidden> Example of strnset and strset ΓòÉΓòÉΓòÉ

/************************************************************************
*
In this example, the strnset function sets not more than 4 characters of a
string to the character 'x' Then the strset function changes any non-null
characters of a string to the character 'k'.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>

int main(void)
{
    char *str = "abcdefghi";
    printf("This is the string: %s\n",str);

    printf("This is the string after strnset: %s\n", strnset(str, 'x', 4));

    printf("This is the string after strset: %s\n", strset(str, 'k'));

    return 0;

/****************  The output should be similar to:  ********************

   This is the string: abcdefghi
   This is the string after strnset: xxxxefghi
   This is the string after strset: kkkkkkkkk
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strchr  - Search for Character
o strpbrk  - Find Characters in String
o wcschr  - Search wchar_t String for Given wchar_t
o wcspbrk  - Locate wchar_t Characters in String
o string.h


ΓòÉΓòÉΓòÉ 6.231. strpbrk  - Find Characters in String ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

char *strpbrk(const char *string1, const char *string2);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The strpbrk function locates the first occurrence in the string pointed to by
string1 of any character from the string pointed to by string2.

The strpbrk function returns a pointer to the character. If string1 and string2
have no characters in common, a NULL pointer is returned.

Example of strpbrk


ΓòÉΓòÉΓòÉ <hidden> Example of strpbrk ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example returns a pointer to the first occurrence in the array string of
either a or b.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>

int main(void)
{
   char *result, *string = "A Blue Danube";
   char *chars = "ab";

   result = strpbrk(string, chars);
   printf("The first occurrence of any of the characters \"%s\" in "
          "\"%s\" is \"%s\"\n", chars, string, result);
}

/*****************  Output should be similar to:  *****************

The first occurrence of any of the characters "ab" in "The Blue Danube"
is "anube"
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strchr  - Search for Character
o strcspn  - Compare Strings
o strrchr  - Find Last Occurrence of Character in String
o strspn  - Search Strings
o wcschr  - Search wchar_t String for Given wchar_t
o wcscspn  - Find Offset of First wchar_t Match
o wcspbrk  - Locate wchar_t Characters in String
o wcsrchr  - Locate wchar_t Character in String
o wcswcs  - Locate wchar_t Substring in wchar_t String
o string.h


ΓòÉΓòÉΓòÉ 6.232. strrchr  - Find Last Occurrence of Character in String ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

char *strrchr(const char *string, int c);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The strrchr function finds the last occurrence of c (converted to a character)
in string.  The ending null character is considered part of the string.

The strrchr function returns a pointer to the last occurrence of c in string.
If the given character is not found, a NULL pointer is returned.

Example of strrchr


ΓòÉΓòÉΓòÉ <hidden> Example of strrchr ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example compares the use of strchr and strrchr.  It searches the string
for the first and last occurrence of p in the string.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>

#define SIZE 40

int main(void)
{
  char buf[SIZE] = "computer program";
  char * ptr;
  int    ch = 'p';

  /* This illustrates strchr */
  ptr = strchr( buf, ch );
  printf( "The first occurrence of %c in '%s' is '%s'\n", ch, buf, ptr );

  /* This illustrates strrchr */
  ptr = strrchr( buf, ch );
  printf( "The last occurrence of %c in '%s' is '%s'\n", ch, buf, ptr );
}

/*****************  Output should be similar to:  *****************

The first occurrence of p in 'computer program' is 'puter program'
The last occurrence of p in 'computer program' is 'program'
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strchr  - Search for Character
o strcspn  - Compare Strings
o strpbrk  - Find Characters in String
o strspn  - Search Strings
o wcschr  - Search wchar_t String for Given wchar_t
o wcspbrk  - Locate wchar_t Characters in String
o wcsrchr  - Locate wchar_t Character in String
o wcswcs  - Locate wchar_t Substring in wchar_t String
o string.h


ΓòÉΓòÉΓòÉ 6.233. strrev - Reverse String ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

char *strrev(char *string);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The strrev function reverses the order of the characters in the given string.
The ending null character (\0) remains in place.

The strrev function returns a pointer to the altered string.  There is no error
return value.

Example of strrev


ΓòÉΓòÉΓòÉ <hidden> Example of strrev ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example determines if a string is a palindrome.  A palindrome is a string
that reads the same forward and backward.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>

int palindrome(char *string);
{
    char *string2;
    /* Duplicate string for comparison */
    if (( string2 = strdup(string) ) == NULL)  {
        printf ("Storage could not be reserved for string\n");
        _exit(-1);
    }

    /* If result equals 0, the string is a palindrome */
    return (strcmp(string, strrev(string2)));
}

int main(void)
{
    char string[81];
    printf("Please enter a string.\n");
    scanf("%80s", string);
    if (palindrome(string))
       printf("The string is not a palindrome.\n");
    else
       printf("The string is a palindrome.\n");

    return 0;


/**************  The output should be similar to:  **********************

   Please enter a string.
   level
   The string is a palindrome.


** ... or ... **


   Please enter a string.
   bolton
   The string is not a palindrome.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strcat  - Concatenate Strings
o strcmp  - Compare Strings
o strcpy  - Copy Strings
o strdup - Duplicate String
o strnset - strset - Set Characters in String
o string.h


ΓòÉΓòÉΓòÉ 6.234. strspn  - Search Strings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

size_t strspn(const char *string1, const char *string2);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The strspn function finds the first occurrence of a character in string1 that
is not contained in the set of characters specified by string2. The null
character (\0) that ends string2 is not considered in the matching process.

The strspn function returns the index of the first character found. This value
is equal to the length of the initial substring of string1 that consists
entirely of characters from string2. If string1 begins with a character not in
string2, strspn returns 0. If all the characters in string1 are found in
string2, the length of string1 is returned.

Example of strspn


ΓòÉΓòÉΓòÉ <hidden> Example of strspn ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example finds the first occurrence in the array string of a character that
is neither an a, b, nor c.  Because the string in this example is cabbage,
strspn returns 5, the length of the segment of cabbage before a character that
is not an a, b or c.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>

int main(void)
{
  char * string = "cabbage";
  char * source = "abc";
  int index;

  index = strspn( string, "abc" );
  printf( "The first %d characters of \"%s\" are found in \"%s\"\n",
          index, string, source );
}

/*****************  Output should be similar to:  *****************

The first 5 characters of "cabbage" are found in "abc"
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strchr  - Search for Character
o strcspn  - Compare Strings
o strpbrk  - Find Characters in String
o strrchr  - Find Last Occurrence of Character in String
o wcschr  - Search wchar_t String for Given wchar_t
o wcscspn  - Find Offset of First wchar_t Match
o wcspbrk  - Locate wchar_t Characters in String
o wcsrchr  - Locate wchar_t Character in String
o wcsspn  - Search wchar_t Characters in String
o wcswcs  - Locate wchar_t Substring in wchar_t String
o string.h


ΓòÉΓòÉΓòÉ 6.235. strstr  - Locate Substring ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

char *strstr(const char *string1, const char *string2);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The strstr function finds the first occurrence of string2 in string1. The
function ignores the null character (\0) that ends string2 in the matching
process.

The strstr function returns a pointer to the beginning of the first occurrence
of string2 in string1. If string2 does not appear in string1, strstr returns
NULL. If string2 points to a string with zero length, the function returns
string1.

Example of strstr


ΓòÉΓòÉΓòÉ <hidden> Example of strstr ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example locates the string haystack in the string "needle in a haystack".

                                                                        *
************************************************************************/

#include <string.h>
#include <stdio.h>

int main(void)
{
   char *string1 = "needle in a haystack";
   char *string2 = "haystack";
   char *result;

  result = strstr(string1,string2);
     /* Result = a pointer to "haystack" */
  printf("%s\n", result);
}

/*****************  Output should be similar to:  *****************

haystack
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strchr  - Search for Character
o strcspn  - Compare Strings
o strpbrk  - Find Characters in String
o strrchr  - Find Last Occurrence of Character in String
o strspn  - Search Strings
o wcschr  - Search wchar_t String for Given wchar_t
o wcscspn  - Find Offset of First wchar_t Match
o wcspbrk  - Locate wchar_t Characters in String
o wcsrchr  - Locate wchar_t Character in String
o wcsspn  - Search wchar_t Characters in String
o wcswcs  - Locate wchar_t Substring in wchar_t String
o string.h


ΓòÉΓòÉΓòÉ 6.236. _strtime - Copy Time ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <time.h>

char *_strtime(char *time);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _strtime function copies the current time into the buffer to which time
points.  The format is:

   hh:mm:ss

where

hh represents the hour in 24-hour notation,

mm represents the minutes past the hour,

ss represents the number of seconds.

For example, the string 18:23:44 represents 23 minutes and 44 seconds past 6
p.m.

The buffer must be at least 9 bytes.

Note:  The time and date functions begin at 00:00 Coordinated Universal Time,
January 1, 1970.

The value returned is a pointer to the buffer.  There is no error return.

Example of _strtime


ΓòÉΓòÉΓòÉ <hidden> Example of _strtime ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example prints the current time:

                                                                        *
************************************************************************/

#include <stdio.h>
#include <time.h>

int main(void)
{
    char buffer[9];

    printf("The current time is %s \n",
             _strtime(buffer));

    return 0;

/*********  The output should be similar to:  *******

   The current time is 16:09:22
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o asctime  - Convert Time
o ctime  - Convert Time
o gmtime  - Convert Time
o localtime  - Convert Time
o mktime  - Convert Local Time
o time  - Determine Current Time
o _tzset - Assign Values to Locale Information
o time.h


ΓòÉΓòÉΓòÉ 6.237. strtod  - Convert Character String to Numeric ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

double strtod(const char *nptr, char **endptr);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The strtod function converts a character string to a double-precision value.
The parameter nptr points to a sequence of characters that can be interpreted
as a numerical value of the type double.  This function stops reading the
string at the first character that it cannot recognize as part of a number.
This character can be the null character at the end of the string.

The strtod function expects nptr to point to a string with the following form:

 ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ
  Γöé        Γöé  Γöé    Γöé  Γöé                 Γöé
  ΓööΓöÇΓöÇwhitespaceΓöÇΓöÇΓöÿ  Γö£ΓöÇΓöÇ + ΓöÇΓöÇΓöñ  Γö£ΓöÇdigitsΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöñ
           Γöé    Γöé  Γöé      Γöé    Γöé  Γöé     Γöé  Γöé
           ΓööΓöÇΓöÇ - ΓöÇΓöÇΓöÿ  Γöé      ΓööΓöÇΓöÇ . ΓöÇΓöÿ  ΓööΓöÇdigitsΓöÇΓöÿ  Γöé
                 Γöé                 Γöé
                 ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ . ΓöÇΓöÇdigitsΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ
  Γöé              Γöé
  Γö£ΓöÇΓöÇeΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇdigitsΓöÇΓöÇΓöÿ
  Γöé   Γöé  Γöé   Γöé
  ΓööΓöÇΓöÇEΓöÇΓöÇΓöÿ  Γö£ΓöÇ + ΓöÇΓöñ
       Γöé   Γöé
       ΓööΓöÇ - ΓöÇΓöÿ

The first character that does not fit this form stops the scan.

The strtod function returns the value of the floating-point number, except when
the representation causes an underflow or overflow.  In the case of an
overflow, it returns -HUGE_VAL or +HUGE_VAL;  in the case of an underflow, it
returns 0.

In both cases, errno is set to ERANGE, depending on the base of the value. If
the string pointed to by nptr does not have the expected form, no conversion is
performed and the value of nptr is stored in the object pointed to by endptr,
provided that endptr is not a NULL pointer.

Example of strtod


ΓòÉΓòÉΓòÉ <hidden> Example of strtod ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example converts the strings to a double value.  It prints out the
converted value and the substring that stopped the conversion.

                                                                        *
************************************************************************/

#include <stdlib.h>
#include <stdio.h>

int main(void)
{
   char *string, *stopstring;
   double x;

   string = "3.1415926This stopped it";
   x = strtod(string, &stopstring);
   printf("string = %s\n", string);
   printf("   strtod = %lf\n", x);
   printf("   Stopped scan at %s\n\n", stopstring);

   string = "100ergs";
   x = strtod(string, &stopstring);
   printf("string = \"%s\"\n", string);
   printf("   strtod = %lf\n", x);
   printf("   Stopped scan at \"%s\"\n\n", stopstring);
}

/*****************  Output should be similar to:  *****************

string = 3.1415926This stopped it
   strtod = 3.141593
   Stopped scan at This stopped it

string = 100ergs
   strtod = 100.000000
   Stopped scan at ergs
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o atof  - Convert Character Strings
o atoi  - Convert Character Strings
o atol  - Convert Character Strings
o _atold - Convert ASCII String to Long Double
o strtol  - Convert Character String to Numeric
o strtold - Convert String to Long Double
o strtoul  - Convert String Segment to Unsigned Integer
o stdlib.h


ΓòÉΓòÉΓòÉ 6.238. strtok  - Tokenize String ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

char *strtok(char *string1, const char *string2);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The strtok function reads string1 as a series of zero or more tokens and
string2 as the set of characters serving as delimiters of the tokens in
string1. The tokens in string1 can be separated by one or more of the
delimiters from string2. The tokens in string1 can be located by a series of
calls to strtok.

In the first call to strtok for a given string1, strtok searches for the first
token in string1, skipping over leading delimiters.  A pointer to the first
token is returned.

To read the next token from string1, call strtok with a NULL string1 argument.
A NULL string1 argument causes strtok to search for the next token in the
previous token string. Each delimiter is replaced by a null character.  The set
of delimiters can vary from call to call, so string2 can take any value.

The first time strtok is called, it returns a pointer to the first token in
string1.  In later calls with the same token string, strtok returns a pointer
to the next token in the string.  A NULL pointer is returned when there are no
more tokens.  All tokens are null-terminated.

Example of strtok


ΓòÉΓòÉΓòÉ <hidden> Example of strtok ΓòÉΓòÉΓòÉ

/************************************************************************
*

Using a loop, this example gathers tokens, separated by blanks or commas, from
a string until no tokens are left.  After processing the tokens (not shown),
the example returns the pointers to the tokens a, string, of, and tokens.  The
next call to strtok returns NULL and the loop ends.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>

int main(void)
{
   char *token, *string = "a string, of, ,tokens\0,after null terminator";

   /* the string pointed to by string is broken up into the tokens
      "a string", " of", " ", and "tokens" ; the null terminator (\0)
      is encountered and execution stops after the token "tokens"     */
   token = strtok(string, ",");
   do
   {
      printf("token: %s\n", token);
   }
   while (token = strtok(NULL, ","));
}

/*****************  Output should be similar to:  *****************

token: a string
token:  of
token:
token: tokens
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strcat  - Concatenate Strings
o strchr  - Search for Character
o strcmp  - Compare Strings
o strcpy  - Copy Strings
o strcspn  - Compare Strings
o strspn  - Search Strings
o string.h


ΓòÉΓòÉΓòÉ 6.239. strtol  - Convert Character String to Numeric ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

long int strtol(const char *nptr, char **endptr, int base);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The strtol function converts a character string to a long-integer value. The
parameter nptr points to a sequence of characters that can be interpreted as a
numerical value of type long int. This function stops reading the string at the
first character that it cannot recognize as part of a number. This character
can be the null character (\0) at the end of the string. The ending character
can also be the first numeric character greater than or equal to the base.

When you use the strtol function, nptr should point to a string with the
following form:

ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ
  Γöé        Γöé  Γöé    Γöé  Γöé    Γöé  Γöé      Γöé
  ΓööΓöÇΓöÇwhitespaceΓöÇΓöÇΓöÿ  Γö£ΓöÇΓöÇ + ΓöÇΓöÇΓöñ  Γö£ΓöÇΓöÇ0ΓöÇΓöÇΓöÇΓöñ  ΓööΓöÇΓöÇdigitsΓöÇΓöÇΓöÿ
           Γöé    Γöé  Γöé    Γöé
           ΓööΓöÇΓöÇ - ΓöÇΓöÇΓöÿ  Γö£ΓöÇΓöÇ0xΓöÇΓöÇΓöñ
                 Γöé    Γöé
                 ΓööΓöÇΓöÇ0XΓöÇΓöÇΓöÿ

If base is in the range of 2 through 36, it becomes the base of the number. If
base is 0, the prefix determines the base (8, 16, or 10):  the prefix 0 means
base 8;  the prefix 0x or 0X means base 16;  using any other digit without a
prefix means decimal.

The strtol function returns the value represented in the string, except when
the representation causes an overflow.  In the case of an overflow, it returns
LONG_MAX or LONG_MIN, according to the sign of the value and errno is set to
ERANGE. If base is not a valid number, strtol sets errno to EDOM.

errno is set to ERANGE for the exceptional cases, depending on the base of the
value.  If the string pointed to by nptr does not have the expected form, no
conversion is performed and the value of nptr is stored in the object pointed
to by endptr, provided that endptr is not a NULL pointer.

Example of strtol


ΓòÉΓòÉΓòÉ <hidden> Example of strtol ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example converts the strings to a long value.  It prints out the converted
value and the substring that stopped the conversion.

                                                                        *
************************************************************************/

#include <stdlib.h>
#include <stdio.h>

int main(void)
{
   char *string, *stopstring;
   long l;
   int bs;

   string = "10110134932";
   printf("string = %s\n", string);
   for (bs = 2; bs <= 8; bs *= 2)
   {
      l = strtol(string, &stopstring, bs);
      printf("   strtol = %ld (base %d)\n", l, bs);
      printf("   Stopped scan at %s\n\n", stopstring);
      }
}

/*****************  Output should be similar to:  *****************

string = 10110134932
   strtol = 45 (base 2)
   Stopped scan at 34932

   strtol = 4423 (base 4)
   Stopped scan at 4932

   strtol = 2134108 (base 8)
   Stopped scan at 932
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o atof  - Convert Character Strings
o atoi  - Convert Character Strings
o atol  - Convert Character Strings
o _atold - Convert ASCII String to Long Double
o _ltoa - Convert Long Integer to String
o strtod  - Convert Character String to Numeric
o strtold - Convert String to Long Double
o strtoul  - Convert String Segment to Unsigned Integer
o stdlib.h


ΓòÉΓòÉΓòÉ 6.240. strtold - Convert String to Long Double ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

long double strtold(const char *nptr, char **endptr);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The strtold function converts a character string pointed to by nptr to a long
double value.  When it reads a character it does not recognize as part of a
number, strtold stops conversion and endptr points to the remainder of nptr.
This character may be the ending null character.

The string pointed to by nptr must have the following format:

 ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ
  ΓööΓöÇΓöÇwhitespaceΓöÇΓöÇΓöÿ  ΓööΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼Γöÿ
            Γö£ΓöÇΓöÇΓöÇ+ΓöÇΓöÇΓöÇΓöñ  Γö£ΓöÇΓöÇdigitsΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöñ
            ΓööΓöÇΓöÇΓöÇ-ΓöÇΓöÇΓöÇΓöÿ  Γöé      ΓööΓöÇΓöÇ.ΓöÇΓöÇΓöÿ ΓööΓöÇdigitsΓöÇΓöÿ Γöé
                  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇ.ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇdigitsΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ
  Γö£ΓöÇΓöÇeΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇdigitsΓöÇΓöÇΓöÿ
  ΓööΓöÇΓöÇEΓöÇΓöÇΓöÿ  Γö£ΓöÇΓöÇ+ΓöÇΓöÇΓöñ
       ΓööΓöÇΓöÇ-ΓöÇΓöÇΓöÿ

The digits are one or more decimal digits.  If no digits appear before the
decimal point, at least one digit must follow the decimal point.  An exponent
expressed as a decimal integer may follow the digits.  The exponent may be
signed.

The value of nptr can also be one of the strings infinity, inf, or nan.  These
strings are case insensitive, and can be preceded by a unary minus (-). They
are converted to infinity and NaN values. See Infinity and NaN Support for more
information about using infinity and NaN values.

If the string pointed to by nptr does not have the expected form, no conversion
is performed and endptr points to the value of nptr.

The strtold function ignores any white-space characters, as defined by the
isspace function.

If successful, strtold returns the value of the long double number.  If it
fails, strtold returns 0.  In the case of an underflow or overflow, it returns
the following:

Condition           Return Value
Underflow           0 with errno set to ERANGE
Positive overflow   +_LHUGE_VAL
Negative overflow   -_LHUGE_VAL.

Example of strtold


ΓòÉΓòÉΓòÉ <hidden> Example of strtold ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses strtold to convert two strings, "  -001234.5678e10end of
string" and "NaNQthis cannot be converted" to their corresponding long double
values.  It also prints out the part of the string that cannot be converted.

                                                                        *
************************************************************************/

#include <stdlib.h>
#include <stdio.h>

int main(void)
{
   char *nptr;
   char *endptr;

   nptr = "  -001234.5678e10end of string";

   printf("strtold = %.10Le\n", strtold(nptr, &endptr) );
   printf("end pointer at = %s\n\n", endptr);

   nptr = "NaNthis cannot be converted";

   printf("strtold = %.10Le\n", strtold(nptr, &endptr) );
   printf("end pointer at = %s\n\n", endptr);

   return 0;

   /* The expected output is:

      strtold = -1.2345678000e+13
      end pointer at = end of string

      strtold = nan
      end pointer at = this cannot be converted */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o atof  - Convert Character Strings
o atoi  - Convert Character Strings
o atol  - Convert Character Strings
o _atold - Convert ASCII String to Long Double
o strtod  - Convert Character String to Numeric
o strtol  - Convert Character String to Numeric
o strtoul  - Convert String Segment to Unsigned Integer
o Infinity and NaN Support
o stdlib.h


ΓòÉΓòÉΓòÉ 6.241. strtoul  - Convert String Segment to Unsigned Integer ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

unsigned long int strtoul(const char *string1, char **string2, int base);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The strtoul function converts a character string to an unsigned long-integer
value. The input string1 is a sequence of characters that can be interpreted as
a numerical value of the type unsigned long int.  The function stops reading
the string at the first character that it cannot recognize as part of a number.
This character can be the first numeric character greater than or equal to the
base. The strtoul function sets string2 to point to the resulting output string
if a conversion is performed and provided that string2 is not a NULL pointer.

When you are using the strtoul function, string1 should point to a string with
the following form:

ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ
  Γöé        Γöé  Γöé    Γöé  Γöé    Γöé  Γöé      Γöé
  ΓööΓöÇΓöÇwhitespaceΓöÇΓöÇΓöÿ  Γö£ΓöÇΓöÇ + ΓöÇΓöÇΓöñ  Γö£ΓöÇΓöÇ0ΓöÇΓöÇΓöÇΓöñ  ΓööΓöÇΓöÇdigitsΓöÇΓöÇΓöÿ
           Γöé    Γöé  Γöé    Γöé
           ΓööΓöÇΓöÇ - ΓöÇΓöÇΓöÿ  Γö£ΓöÇΓöÇ0xΓöÇΓöÇΓöñ
                 Γöé    Γöé
                 ΓööΓöÇΓöÇ0XΓöÇΓöÇΓöÿ

If base is in the range of 2 through 36, it becomes the base of the number.  If
base is 0, the prefix determines the base (8, 16, or 10):  the prefix 0 means
base 8;  the prefix 0x or 0X means base 16;  using any other digit without a
prefix means decimal.

The strtoul function returns the value represented in the string or returns 0
if no conversion could be performed. For an overflow, strtoul returns ULONG_MAX
and sets errno to ERANGE.  If base is not a valid number, strtoul sets errno to
EDOM.

Example of strtoul


ΓòÉΓòÉΓòÉ <hidden> Example of strtoul ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example converts the string to an unsigned long value.  It prints out the
converted value and the substring that stopped the conversion.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>

#define BASE 2

int main(void)
{
   char *string, *stopstring;
   unsigned long ul;

   string = "1000e13 e";
   printf("string = %s\n", string);
   ul = strtoul(string, &stopstring, BASE);
   printf("   strtoul = %ld (base %d)\n", ul, BASE);
   printf("   Stopped scan at %s\n\n", stopstring);
}

/*****************  Output should be similar to:  *****************

string = 1000e13 e
   strtoul = 8 (base 2)
   Stopped scan at e13 e
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o atof  - Convert Character Strings
o atoi  - Convert Character Strings
o atol  - Convert Character Strings
o _atold - Convert ASCII String to Long Double
o strtod  - Convert Character String to Numeric
o strtol  - Convert Character String to Numeric
o strtold - Convert String to Long Double
o _ultoa - Convert Unsigned Long Integer to String
o stdlib.h


ΓòÉΓòÉΓòÉ 6.242. strupr - Convert Lowercase to Uppercase ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

char *strupr(char *string);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The strupr function converts any lowercase letters in string to uppercase.
Other characters are not affected.

The strupr function returns a pointer to the converted string. There is no
error return.

Example of strupr


ΓòÉΓòÉΓòÉ <hidden> Example of strupr ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example makes a copy in all-uppercase of the string "DosWrite", and then
prints the copy.

                                                                        *
************************************************************************/

#include <string.h>
#include <stdio.h>

int main(void)
{
    char *string = "DosWrite";
    char *copy;

    copy=strupr(strdup(string));
    printf("This is a copy of the string\n");
    printf("with all letters capitalized: %s\n",copy);

    return 0;

    /* The expected output is:

       This is a copy of the string
       with all letters capitalized: DOSWRITE */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strlwr - Convert Uppercase to Lowercase
o _toascii - _tolower - _toupper - Convert Character
o tolower - toupper  - Convert Character Case
o string.h


ΓòÉΓòÉΓòÉ 6.243. strxfrm  - Transform Strings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <string.h>

size_t strxfrm(char *string1, const char *string2, size_t count);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The strxfrm function transforms the string pointed to by string2 and places the
result into the string pointed to by string1.  The transformation is determined
by the program's current locale.  The transformed string is not necessarily
readable, but can be used with the strcmp or strncmp functions.

The strxfrm function returns the length of the transformed string, excluding
the terminating null character.  If the value returned is greater than or equal
to count, the contents of the transformed string are indeterminate.

Example of strxfrm


ΓòÉΓòÉΓòÉ <hidden> Example of strxfrm ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example prompts the user to input a string of characters, then uses
strxfrm to transform the string and return its length.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <string.h>

int main(void)
{
   char *string1, buffer[80];
   int length;

   printf("Type in a string of characters.\n ");
   string1 = gets(buffer);
   length = strxfrm(NULL, string1, 0);
   printf("You would need a %d element array to hold the string\n",length);
   printf("\n\n%s\n\n transformed according",string1);
   printf(" to this program's locale. \n");
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o localeconv  - Query Locale Conventions
o setlocale  - Set Locale
o strcmp  - Compare Strings
o strcmpi - Compare Strings
o strcoll  - Compare Strings
o stricmp - Compare Strings
o strncmp  - Compare Strings
o strnicmp - Compare Strings
o string.h


ΓòÉΓòÉΓòÉ 6.244. _swab - Swap Adjacent Bytes ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

void _swab(char *source, char *destination, int n);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _swab function copies n bytes from source, swaps each pair of adjacent
bytes, and stores the result at destination.  The integer n should be an even
number to allow for swapping. If n is an odd number, a null character (\0) is
added after the last byte.

The _swab function is typically used to prepare binary data for transfer to a
machine that uses a different byte order.

There is no return value.

Example of _swab


ΓòÉΓòÉΓòÉ <hidden> Example of _swab ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example copies n bytes from one location to another, swapping each pair of
adjacent bytes:

                                                                        *
************************************************************************/

#include <stdlib.h>
#include <stdio.h>

/* This array is not a string because it does not end
             with a null character */
char from[20] = "hTsii  s atsirgn..x ";
char to[20];

int main(void)
{
    _swab(from, to, 19);

    printf("%s\n", to);
                      /* Because swab appends a null character, */
                      /* the array is now a string              */

    return 0;

/***************  The output should be similar to:  *********************

   This is a string..
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fgetc  - Read a Character
o fputc  - Write a Character
o stdlib.h


ΓòÉΓòÉΓòÉ 6.245. system - Invoke the Command Processor ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

int system(char *string);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA, Extension

The system function passes the command string to a command processor to be run.
The command processor specified in the COMSPEC environment variable is searched
for first. If it does not exist or is not a valid executable file, the default
command processor, CMD.EXE, is searched for in the current directory and in all
the directories specified in the PATH environment variable.

If the specified command is the name of an executable file created from a C
program, full initialization and termination is performed, including automatic
flushing of buffers and closing of files.  To pass information across a system
function, use a method of interprocess communication like pipes or shared
memory.

You can also use system to redirect standard streams using the redirection
operators (the angle brackets), for example:

   rc = system("cprogram < in.file");

The defaults for the standard streams will be whatever the standard streams are
at the point of the system call;  for example, if the root program redirects
stdout to file.txt, a printf call in a C module invoked by a system call will
append to file.txt.

If the argument is a null pointer, the system function returns nonzero if a
command processor exists and 0 if it does not exist. The return value will be
the return value from the command processor if it is successfully called. If
system cannot call the command processor successfully, the return value is -1
and errno is set to one of the following values:

Value         Meaning
ENOCMD        No valid command processor found.
ENOMEM        Insufficient memory to complete the function.
EOS2ERR       A system error occurred.  Check _doserrno for the specific OS/2
              error code.

Example of system


ΓòÉΓòÉΓòÉ <hidden> Example of system ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example shows how to use system to execute the OS/2 command dir c:\ :

                                                                        *
************************************************************************/

#include <stdlib.h>

int main(void)
{
    int rc;

    rc = system("dir c:\\");
    exit(rc);

    /* The expected output is a listing of files
         on the root directory of the c: drive   */
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o exit  - End Program
o _exit - End Process
o process.h
o stdlib.h


ΓòÉΓòÉΓòÉ 6.246. tan  - Calculate Tangent ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h>

double tan(double x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The tan function calculates the tangent of x, where x is expressed in radians.
If x is too large, a partial loss of significance in the result can occur.

Example of tan


ΓòÉΓòÉΓòÉ <hidden> Example of tan ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example computes x as the tangent of у/4.

                                                                        *
************************************************************************/

#include <math.h>
#include <stdio.h>

int main(void)
{
   double pi, x;

   pi = 3.1415926;
   x = tan(pi/4.0);

   printf("tan( %lf ) is %lf\n", pi/4, x);
}

/******************  Output should be similar to:  ****************

tan( 0.785398 ) is 1.000000
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o atan - atan2  - Calculate Arctangent
o cos  - Calculate Cosine
o _fpatan - Calculate Arctangent
o _fptan - Calculate Tangent
o sin  - Calculate Sine
o tanh  - Calculate Hyperbolic Tangent
o math.h


ΓòÉΓòÉΓòÉ 6.247. tanh  - Calculate Hyperbolic Tangent ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <math.h>

double tanh(double x);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The tanh function calculates the hyperbolic tangent of x, where x is expressed
in radians. The result of the tanh function cannot have a range error.


ΓòÉΓòÉΓòÉ <hidden> Example of tanh ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example computes x as the hyperbolic tangent of у/4.

                                                                        *
************************************************************************/

#include <math.h>
#include <stdio.h>

int main(void)
{
   double pi, x;

   pi = 3.1415926;
   x = tanh(pi/4);

   printf("tanh( %lf ) = %lf\n", pi/4, x);
}

/******************  Output should be similar to:  ****************

tanh( 0.785398 ) = 0.655794
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o atan - atan2  - Calculate Arctangent
o cosh  - Calculate Hyperbolic Cosine
o _fpatan - Calculate Arctangent
o _fptan - Calculate Tangent
o sinh  - Calculate Hyperbolic Sine
o tan  - Calculate Tangent
o math.h


ΓòÉΓòÉΓòÉ 6.248. _tcalloc - Reserve Tiled Storage Block ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#define __TILED__
#include <stdlib.h>  /* also defined in <malloc.h> */

void *_tcalloc(size_t number, size_t size)


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _tcalloc function allocates tiled memory for an array of number elements,
each of length size bytes, and initializes all bits of each element to 0. The
allocated memory is guaranteed not to cross a 64K boundary if the size is not
greater than 64K. Otherwise, the memory is aligned on a 64K boundary.

Note:  Memory allocated by _tcalloc must be freed using the _tfree function,
and not any other version of free.

The _tcalloc function returns a pointer to the allocated tiled memory. If not
enough storage is available, or if num or size is 0, _tcalloc returns NULL.

Example of _tcalloc


ΓòÉΓòÉΓòÉ <hidden> Example of _tcalloc ΓòÉΓòÉΓòÉ

/************************************************************************
*

This program allocates tiled memory for an array of 100 elements of size char.

                                                                        *
************************************************************************/


#ifndef __TILED__
   #define __TILED__
#endif
#include <stdlib.h>

int main()
    {
    char *memoryPtr;

    if ((memoryPtr = _tcalloc( 100, sizeof(char)) != NULL)
       {
       printf("Successfully allocated 100 char of tiled memory.\n");
       _tfree(memoryPtr);
       }
    else
       printf("Unable to allocate tiled object.\n");

/********  If the program is successful, the output should be:  ******

          Successfully allocated 100 char of tiled memory.

*********************************************************************/
    }


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o calloc  - Reserve and Initialize Storage
o _debug_calloc - Reserve and Initialize Storage
o _msize - Return Number of Bytes Allocated
o _tmalloc - Reserve Tiled Storage Block
o _trealloc - Reallocate Tiled Storage Block
o _tfree - Free Tiled Storage Block


ΓòÉΓòÉΓòÉ 6.249. _tell - Get Pointer Position ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <io.h>

long _tell(int handle);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _tell function gets the current position of the file pointer associated
with handle. The position is the number of bytes from the beginning of the
file.

The _tell function returns the current position. A return value of -1L
indicates an error, and errno is set to one of the following values:

Value          Meaning
EBADF          The file handle is not valid.
EOS2ERR        The call to the operating system was not successful.

On devices incapable of seeking (such as screens and printers), the return
value is -1L.

Example of _tell


ΓòÉΓòÉΓòÉ <hidden> Example of _tell ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example opens the file sample.dat. It then uses tell to get the current
position of the file pointer and report if it is successful or unsuccessful.
The program then closes sample.dat.

                                                                        *
************************************************************************/

#include <io.h>
#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>

int main(void)
{
   long filePtrPos;
   int  fh;

   printf("\nCreating sample.dat.\n");
   system("echo Sample Program > sample.dat");

   if (-1 == (fh = _open("sample.dat",O_RDWR | O_APPEND)))
   {
      perror("Unable to open sample.dat");
      return 1;
   }

   /* Get the current file pointer position. */

   if ( -1 == (filePtrPos = _tell(fh)))
   {
      perror("Unable to _tell");
      _close(fh);
      return 1;
   }

   printf("File pointer is at position %d.\n",filePtrPos);

   _close(fh);
   return 0;

/*******************  The expected output is:  **************************

      Creating sample.dat.
      File pointer is at position 0.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fseek  - Reposition File Position
o ftell  - Get Current Position
o _lseek - Move File Pointer
o io.h


ΓòÉΓòÉΓòÉ 6.250. _tempnam - Produce Temporary File Name ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

char *_tempnam(char *dir, char *prefix);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _tempnam function creates a temporary file name in another directory.  The
prefix is the prefix to the file name. The _tempnam function tests for the
existence of the file with the given name in the following directories, listed
in order of precedence:

o If the TMP environment variable is set and the directory specified by TMP
  exists, the directory is specified by TMP.

o If the TMP environment variable is not set or the directory specified by TMP
  does not exist, the directory is specified by the dir argument to _tempnam

o If the dir argument is NULL, or dir is the name of nonexistent directory, the
  directory is pointed to by P_tmpdir in <stdio.h>.

o If P_tmpdir does not exist, the directory is the current working directory.

Note:  Because _tempnam uses malloc to reserve space for the created file name,
you must free this space when you no longer need it.

The _tempnam function returns a pointer to the temporary name, if successful.
If the name cannot be created or it already exists, _tempnam returns the value
NULL.

Example of _tempnam


ΓòÉΓòÉΓòÉ <hidden> Example of _tempnam ΓòÉΓòÉΓòÉ

/***************************************************************************
*                                                                          *
This example creates a temporary file name using the directory a:\tmp:

                                                                        *
************************************************************************/

#include <stdio.h>

int main(void)
{
    char *name1;

    if((name1 = _tempnam("a:\\tmp","stq")) != NULL)
        printf("%s is safe to use as a temporary file.\n", name1);
    else

        printf("Cannot create unique filename\n");

    return 0;

/*****************  The output should be similar to:  *******************

   D:\stqU3CP2.C2T is safe to use as a temporary file.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o malloc  - Reserve Storage Block
o _rmtmp - Remove Temporary Files
o tmpfile  - Create Temporary File
o tmpnam  - Produce Temporary File Name
o stdio.h


ΓòÉΓòÉΓòÉ 6.251. _tfree - Free Tiled Storage Block ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#define __TILED__
#include <stdlib.h>  /* also defined in <malloc.h> */

void _tfree(void *ptr);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _tfree function frees the tiled memory pointed to by ptr that has been
allocated by one of the memory management functions. If ptr is NULL, then no
action occurs.

Note:  The _tfree function can only be used to free memory allocated by the
tiled memory management functions.

The _tfree function has no return value.

Example of _tfree


ΓòÉΓòÉΓòÉ <hidden> Example of _tfree ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses the _tfree function to free a block of tiled memory that was
previously allocated by the _tmalloc function.

                                                                        *
************************************************************************/


#ifndef __TILED__
   #define __TILED__
#endif
#include <stdlib.h>

int main()
    {
    char *memoryPtr;

    if ((memoryPtr = _tmalloc(100)) != NULL)
       {
       printf("Successfully allocated 100 bytes of tiled memory.\n");
       _tfree(memoryPtr);
       }
    else
       printf("Unable to allocate tiled object.\n");

/********  If the program is successful, the output should be:  *****

          Successfully allocated 100 bytes of tiled memory.

********************************************************************/
    }


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o free  - Release Storage Blocks
o _debug_free - Release Storage Blocks
o _tcalloc - Reserve Tiled Storage Block
o _trealloc - Reallocate Tiled Storage Block
o _tmalloc - Reserve Tiled Storage Block


ΓòÉΓòÉΓòÉ 6.252. _threadstore - Access Thread-Specific Storage ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

void *_threadstore(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _threadstore function gives you access to a private thread pointer that is
initialized to NULL. You can assign any thread-specific data structure to this
pointer.

The _threadstore function returns the address of the pointer to the defined
thread storage space.

Example of _threadstore


ΓòÉΓòÉΓòÉ <hidden> Example of _threadstore ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses the _threadstore function to point to storage that is local
to the thread. It prints the address pointed to by _threadstore.

                                                                        *
************************************************************************/


#include <stdlib.h>
#include <stddef.h>
#include <stdio.h>

#define  privateStore   (*_threadstore())


void thread(void *dummy)
    {
    privateStore = malloc(100);

    printf("The starting address of the storaged space is %p\n",
             privateStore);

    /* user must free storage before exiting thread */

    free (privateStore);
    _endthread();
    }

int main(void)
   {
   int i;

   for (i=0;i < 10; i++)
      {
      _beginthread(thread,NULL,(unsigned) 32096, NULL) ;
      }

   DosSleep(5000L);
   }


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _beginthread - Create New Thread
o _endthread - Terminate Current Thread
o stdlib.h


ΓòÉΓòÉΓòÉ 6.253. time  - Determine Current Time ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <time.h>

time_t time(time_t *timeptr);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The time function determines the current calendar time, which is not
necessarily the local time localtime.

The time function returns the current calendar time. The return value is also
stored in the location given by timeptr. If timeptr is NULL, the return value
is not stored. If the calendar time is not available, the value (time_t)(-1) is
returned.

Note:  The time and date functions begin at 00:00 Universal Time, January 1,
1970.

Example of time


ΓòÉΓòÉΓòÉ <hidden> Example of time ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example gets the time and assigns it to ltime.  It then uses the ctime
function to convert the number of seconds to the current date and time. This
example then prints a message giving the current time.

                                                                        *
************************************************************************/

#include <time.h>
#include <stdio.h>

int main(void)
{
   time_t ltime;

   time(<ime);
   printf("The time is %s\n", ctime(<ime));
}

/******************  Output should be similar to:  ****************

The time is Mon Mar 22 19:01:41 1993
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o asctime  - Convert Time
o ctime  - Convert Time
o gmtime  - Convert Time
o localtime  - Convert Time
o mktime  - Convert Local Time
o _strtime - Copy Time
o time.h


ΓòÉΓòÉΓòÉ 6.254. _tmalloc - Reserve Tiled Storage Block ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#define __TILED__
#include <stdlib.h>  /* also defined in <malloc.h> */

void _tmalloc(size_t size);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _tmalloc function allocates tiled memory for an object of size size, the
value of which is indeterminate. If the size is less than 64K, then the memory
block is guaranteed not to cross a 64K boundary. Otherwise, the block will
begin on a 64K boundary.

Note:  Memory allocated by the _tmalloc function may only be freed using the
_tfree function.

The _tmalloc function returns a pointer to the allocated tiled memory. If not
enough storage is available, or if size is 0, then _tmalloc returns NULL.

Example of _tmalloc


ΓòÉΓòÉΓòÉ <hidden> Example of _tmalloc ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example used the _tmalloc function to allocate 100 bytes of tiled memory.

                                                                        *
************************************************************************/


#ifndef __TILED__
   #define __TILED__
#endif
#include <stdlib.h>

int main()
    {
    char *memoryPtr;

    if ((memoryPtr = _tmalloc(100)) != NULL)
       {
       printf("Successfully allocated 100 bytes of tiled memory.\n");
       _tfree(memoryPtr);
       }
    else
       printf("Unable to allocate tiled object.\n");

/********  If the program is successful, the output should be:  ******

          Successfully allocated 100 bytes of tiled memory.

*********************************************************************/
    }


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _debug_malloc - Reserve Storage Blocks
o malloc  - Reserve Storage Block
o _msize - Return Number of Bytes Allocated
o _tcalloc - Reserve Tiled Storage Block
o _trealloc - Reallocate Tiled Storage Block
o _tfree - Free Tiled Storage Block
o stdlib.h


ΓòÉΓòÉΓòÉ 6.255. tmpfile  - Create Temporary File ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

FILE *tmpfile(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The tmpfile function creates a temporary binary file.  The file is
automatically removed when it is closed or when the program is terminated.

The tmpfile function opens the temporary file in wb+ mode.

The tmpfile function returns a stream pointer, if successful. If it cannot open
the file, it returns a NULL pointer. On normal termination (exit), these
temporary files are removed.

Example of tmpfile


ΓòÉΓòÉΓòÉ <hidden> Example of tmpfile ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example creates a temporary file and if successful, writes tmpstring to
it.  At program termination, the file is removed.

                                                                        *
************************************************************************/

#include <stdio.h>

FILE *stream;
char tmpstring[ ] = "This is the string to be temporarily written";

int main(void)

{
   if((stream = tmpfile( )) == NULL)
      perror("Cannot make a temporary file");
   else
      fprintf(stream, "%s", tmpstring);
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fopen  - Open Files
o tmpnam  - Produce Temporary File Name
o _tempnam - Produce Temporary File Name
o _rmtmp - Remove Temporary Files
o stdio.h


ΓòÉΓòÉΓòÉ 6.256. tmpnam  - Produce Temporary File Name ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

char *tmpnam(char *string);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The tmpnam function produces a valid file name that is not the same as the name
of any existing file. It stores this name in string.  If string is NULL, tmpnam
leaves the result in an internal static buffer.  Any subsequent calls destroy
this value.  If string is not NULL, it must point to an array of at least
L_tmpnam bytes.  The value of L_tmpnam is defined in <stdio.h>.

The tmpnam function returns a pointer to the name, unless it cannot create a
unique name; in which case, it returns NULL.

The tmpnam function produces a different name each time it is called within a
module up to at least TMP_MAX (a value of at least 25) names.  Note that files
created using names returned by tmpnam are not automatically discarded at the
end of the program. Files can be removed by the remove function.

Example of tmpnam


ΓòÉΓòÉΓòÉ <hidden> Example of tmpnam ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example calls tmpnam to produce a valid file name.

                                                                        *
************************************************************************/

#include <stdio.h>

int main(void)
{
   char *name1;
   if ((name1 = tmpnam(NULL)) !=NULL)
      printf("%s can be used as a file name.\n", name1);
   else printf("Cannot create a unique file name\n");

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fopen  - Open Files
o remove  - Delete File
o _tempnam - Produce Temporary File Name
o stdio.h


ΓòÉΓòÉΓòÉ 6.257. _toascii - _tolower - _toupper - Convert Character ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <ctype.h>
int _toascii(int c);

int _tolower(int c);

int _toupper(int c);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _toascii, _tolower, and _toupper macros convert a single character as
described below.

The _toascii macro sets all but the low-order 7 bits of c to 0 so that the
converted value represents a character in the ASCII character set.  If c
already represents an ASCII character, c is unchanged.

Important  Only use the _tolower macro when you know that c is uppercase. The
           result of _tolower is undefined if c is not an uppercase letter.

Only use the _toupper macro when you know that c is lowercase. The result of
_toupper is undefined if c is not a lowercase letter.

Note:  These are all macros, but _tolower and _toupper also have function
versions because the macro versions do not correctly handle arguments with side
effects.  Function declarations of _tolower and _toupper are given in
<stdlib.h>. The function versions are part of the standard library, and are
defined in the SAA standard. For portability, use the functions instead of the
macros.

The _toascii, _tolower, and _toupper macros return the possibly converted
character c.  There is no error return.

Example of _toascii - _tolower - _toupper


ΓòÉΓòÉΓòÉ <hidden> Example of _toascii &ndask. _tolower - _toupper ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example prints four sets of characters.  The first set is the ASCII
characters having graphic images, which range from 0x21 through 0x7e. The
second set takes integers 0x7f21 through 0x7f7e and applies the _toascii macro
to them, yielding the same set of printable characters. The third set is the
characters with all lowercase letters converted to uppercase.  The fourth set
is the characters with all uppercase letters converted to lowercase.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <ctype.h>

int main(void)
{
   int ch;

   printf("Characters 0x01 to 0x03,
                   and integers 0x7f01 to 0x7f03 mapped to\n");
   printf("ASCII by _toascii() both yield
            the same graphic characters.\n\n");

   for (ch = 0x01; ch <= 0x03; ch++)
   {
      printf("char 0x%.4X: %c    ", ch, ch);
      printf("char _toascii(0x%.4X): %c\n",
               ch+0x7f00, ch+0x7f00);
   }

   printf("\nCharacters A, B and C converted
                 to lower case and\n");
   printf("Characters a, b and c converted
           to upper case.\n\n");

   for (ch = 0x41; ch <= 0x43; ch++)  {
      printf("_tolower(%c) = %c   ", ch, _tolower(ch) );
      printf("_toupper(%c) = %c\n",
                  ch+0x20, _toupper(ch+0x20) );
   }

    return 0;

/**********  The output should be similar to:  **************

   Characters 0x01 to 0x03, and integers 0x7f01 to 0x7f03
   mapped to ASCII by _/toascii() both yield the same
   graphic characters.

   char 0x0001: 
    char _toascii(0x7F01): 

   char 0x0002:     char _toascii(0x7F02): 
   char 0x0003:     char _toascii(0x7F03): 

   Characters A, B and C converted to lower case and
   Characters a, b and c converted to upper case.

   _tolower(A) = a   _toupper(a) = A
   _tolower(B) = b   _toupper(b) = B
   _tolower(C) = c   _toupper(c) = C
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o isalnum to isxdigit  - Test Integer Value
o _isascii - Test Integer Values
o _iscsym - _iscsymf - Test Integer
o tolower - toupper  - Convert Character Case
o ctype.h


ΓòÉΓòÉΓòÉ 6.258. tolower - toupper  - Convert Character Case ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <ctype.h>

int tolower(int c);   /* Convert c to lowercase if appropriate */

int toupper(int c);   /* Convert c to uppercase if appropriate */


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The tolower function returns a lowercase c if c represents an uppercase letter;
otherwise, c is returned.  c is unchanged.

The toupper function returns an uppercase c if c represents a lowercase letter;
otherwise, c is returned. c is unchanged.

Example of tolower - toupper


ΓòÉΓòÉΓòÉ <hidden> Example of tolower - toupper ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses the toupper and tolower functions to modify characters
between code 0 and code 7f.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <ctype.h>

int main(void)
{
   int ch;

   for (ch = 0; ch <= 0x7f; ch++)
   {
      printf("toupper=%#04x\n", toupper(ch));
      printf("tolower=%#04x\n", tolower(ch));
      putchar('\n');
      }
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o isalnum to isxdigit  - Test Integer Value
o _isascii - Test Integer Values
o _iscsym - _iscsymf - Test Integer
o _toascii - _tolower - _toupper - Convert Character
o ctype.h


ΓòÉΓòÉΓòÉ 6.259. _trealloc - Reallocate Tiled Storage Block ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#define __TILED__
#include <stdlib.h>  /* also defined in <malloc.h> */

void _trealloc(void *ptr, size_t size);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _trealloc function changes the size of the tiled memory pointed to ptr to
the specified size, in bytes. The contents of the tiled memory are unchanged up
to the smaller of the new and old sizes. Any new tiled memory that is allocated
is uninitialized.

Note:  The _trealloc function reallocates tiled memory that has been allocated
by the _tmalloc, _tcalloc or _trealloc functions. If the memory was not
allocated by one of these functions or was previously freed, a message appears
and the program ends.

The _trealloc function returns a pointer to the reallocated tiled memory. If
not enough storage is available or size is 0, then _trealloc returns NULL and
the original block does not change.

Example of _trealloc


ΓòÉΓòÉΓòÉ <hidden> Example of _trealloc ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses _trealloc to reallocate a block of tiled memory that was
previously allocated by _tmalloc.

                                                                        *
************************************************************************/


#ifndef __TILED__
   #define __TILED__
#endif
#include <stdlib.h>

int main()
    {
    char *memoryPtr;

    if ((memoryPtr = _tmalloc(100)) != NULL)
       {
       printf("Successfully allocated 100 bytes of tiled memory.\n");
       }
    else
       {
       printf("Unable to allocate tiled object.\n");
       return 1;
       }

    if ((memoryPtr = _trealloc(memoryPtr,1000)) != NULL)
       {
       printf("Successfully reallocated 1000 bytes of tiled memory.\n");
       _tfree(memoryPtr);
       }
    else
       {
       printf("Unable to allocate tiled object.\n");
       return 1;
       }

    if ((memoryPtr = _tmalloc(100)) != NULL)

/********  If the program is successful, the output should be:  *****

          Successfully reallocated 100 bytes of tiled memory.

********************************************************************/

    }


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _debug_calloc - Reserve and Initialize Storage
o _msize - Return Number of Bytes Allocated
o realloc  - Change Reserved Storage Block Size
o _tcalloc - Reserve Tiled Storage Block
o _tmalloc - Reserve Tiled Storage Block
o _tfree - Free Tiled Storage Block
o stdlib.h


ΓòÉΓòÉΓòÉ 6.260. _tzset - Assign Values to Locale Information ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <time.h>

void _tzset(void);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _tzset function uses the environment variable TZ to change the time zone
and daylight saving time (DST) zone values of your current locale. These values
are used by the gmtime and localtime functions to make corrections from
Coordinated Universal Time (formerly GMT) to local time.

To use _tzset, set the TZ variable to the appropriate values. (For the possible
values for TZ, see the chapter on runtime environment variables in the
Programming Guide) Then call _tzset to incorporate the changes in the time zone
information into your current locale.

To set TZ from within a program, use the _putenv function before calling
_tzset.

Note:  The time and date functions begin at 00:00 Coordinated Universal Time,
January 1, 1970. :enote.

There is no return value.

Example of _tzset


ΓòÉΓòÉΓòÉ <hidden> Example of _tzset ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example uses the _putenv and _tzset functions to set the time zone to
Central Time.

                                                                        *
************************************************************************/

#include <time.h>
#include <stdio.h>

int main(void)
{
   time_t currentTime;
   struct tm  * ts;

   /* Get the current time */
   (void)time(¤tTime);

   printf( "The GMT time is %s\n", asctime(gmtime(¤tTime)) );

   ts = localtime(¤tTime);

   if (ts->tm_isdst > 0)   /* check if Daylight Saving Time is in effect */
   {
      printf("The local time is %s", asctime(ts));
      printf("Daylight Saving Time is in effect.\n");
   }
   else
   {
      printf("The local time is %s",asctime(ts));
      printf("Daylight Saving Time is not in effect.\n\n");
   }

   printf("**** Changing to Central Time **** \n\n");
   _putenv("TZ=CST6CDT");
   _tzset();

   ts = localtime(¤tTime);

   if (ts->tm_isdst > 0)   /* check if Daylight Saving Time is in effect */
   {
      printf("The local time is %s",asctime(ts));
      printf("Daylight Saving Time is in effect.\n");
   }
   else
   {
      printf("The local time is %s",asctime(ts));
      printf("Daylight Saving Time is not in effect.\n");
   }

   /*  Possible output could be:

       The GMT time is Thu Sep  3 11:55:04 1991

       The local time is Thu Sep  3 07:55:04 1991
       Daylight Saving Time is in effect.

       **** Changing to Central Time ****

       The local time is Thu Sep  3 06:55:04 1991
       Daylight Saving Time is in effect.      */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o asctime  - Convert Time
o _ftime - Store Current Time
o gmtime  - Convert Time
o localtime  - Convert Time
o mktime  - Convert Local Time
o _putenv - Modify Environment Variables
o time  - Determine Current Time
o time.h


ΓòÉΓòÉΓòÉ 6.261. _ultoa - Convert Unsigned Long Integer to String ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

char *_ultoa(unsigned long value, char *string, int radix);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _ultoa function converts the digits of the given unsigned long value to a
null-terminated character string and stores the result in string. No overflow
checking is performed. The radix argument specifies the base of value; it must
be in the range of 2 through 36.

Note:  The space allocated for string must be large enough to hold the returned
string. The function can return up to 33 bytes, including the null character
(\0).

The _ultoa function returns a pointer to string. There is no error return
value.

Example of _ultoa


ΓòÉΓòÉΓòÉ <hidden> Example of _ultoa ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example converts the digits of the value 255 to decimal, binary and
hexadecimal representations:

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
    char buffer[10];
    char *p;

    p = _ultoa(255UL, buffer, 10);
    printf("The result of _ultoa(255) with radix of 10 is %s\n", p);

    p = _ultoa(255UL, buffer, 2);
    printf("The result of _ultoa(255) with radix of 2 is %s\n", p);

    p = _ultoa(255UL, buffer, 16);
    printf("The result of _ultoa(255) with radix of 16 is %s\n", p);

    return 0;

    /* The expected output is:

       The result of _ultoa(255) with radix of 10 is 255
       The result of _ultoa(255) with radix of 2 is 11111111
       The result of _ultoa(255) with radix of 16 is ff      */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _ecvt - Convert Floating-Point to Character
o _fcvt - Convert Floating-Point to String
o _gcvt - Convert Floating-Point to String
o _itoa - Convert Integer to String
o _ltoa - Convert Long Integer to String
o stdlib.h


ΓòÉΓòÉΓòÉ 6.262. _umask - Sets File Mask of Current Process ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <io.h>
#include <sys\stat.h>

int _umask(int pmode);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _umask function sets the file permission mask of the executing process
environment to the mode specified by pmode. The file permission mask modifies
the permission setting of new files created by _creat, _open, or _sopen.

If a bit in the mask is 1, the corresponding bit in the requested permission
value of the file is set to 0 (disallowed).  If a bit in the mask is 0, the
corresponding bit is left unchanged.  The permission setting for a new file is
not set until the file is closed for the first time.

The _umask function returns the previous value of pmode.  A return value of -1
indicates that the value used for pmode was not valid, and errno is set to
EINVAL.

The variable pmode contains one or both of the constants S_WRITE and S_IREAD,
defined in <sys\stat.h>. The possible values for pmode are:

Value                   Meaning
S_IREAD                 No effect
S_IWRITE                Writing not permitted
S_IREAD | S_IWRITE      Writing not permitted.

If the write bit is set in the mask, any new files will be read-only. You
cannot give write-only permission, meaning that setting the read bit has no
effect.

Example of _umask


ΓòÉΓòÉΓòÉ <hidden> Example of _umask ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example sets the permission mask to create a write-only file.

                                                                        *
************************************************************************/

#include <sys\stat.h>
#include <io.h>
#include <stdio.h>

int main(void)
{
   int oldMask;

   oldMask = _umask(S_IWRITE);
   printf("\nDefault system startup mask is %d.\n",oldMask);
   return 0;

/******************  The expected output is:  ***************************

      Default system startup mask is 0.
*/

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _chmod - Change File Permission Setting
o _creat - Create New File
o _open - Open File
o _sopen - Open Shared File
o io.h
o sys\stat.h
o sys\types.h


ΓòÉΓòÉΓòÉ 6.263. ungetc  - Push Character onto Input Stream ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>

int ungetc(int c, FILE *stream);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The ungetc function pushes the unsigned character c back onto the given input
stream.  However, only one sequential ungetc is guaranteed to be pushed back
onto the input stream if you call ungetc consecutively. The stream must be open
for reading.  A subsequent read operation on the stream starts with c.  You
cannot push EOF back on the stream using ungetc.

Characters placed on the stream by ungetc will be erased if a fseek, fsetpos,
rewind, or fflush function is called before the character is read from the
stream.

The ungetc function returns the integer argument c converted to an unsigned
char or EOF if c cannot be pushed back.

Example of ungetc


ΓòÉΓòÉΓòÉ <hidden> Example of ungetc ΓòÉΓòÉΓòÉ

/************************************************************************
*
In this example, the while statement reads decimal digits from an input data
stream by using arithmetic statements to compose the numeric values of the
numbers as it reads them.  When a nondigit character appears before the end of
the file, ungetc replaces it in the input stream so that later input functions
can process it.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <ctype.h>

int main(void)
{
   FILE *stream;
   int ch;
   unsigned int result = 0;
   .
   .
   .
   while ((ch = getc(stream)) != EOF && isdigit(ch))
      result = result * 10 + ch - '0';
   if (ch != EOF)
      ungetc(ch,stream);
         /* Put the nondigit character back */
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o getc  - Read a Character
o fflush  - Write Buffer to File
o fseek  - Reposition File Position
o fsetpos  - Set File Position
o putc - putchar  - Write a Character
o rewind  - Adjust Current File Position
o _ungetch - Push Character Back to Keyboard
o stdio.h


ΓòÉΓòÉΓòÉ 6.264. _ungetch - Push Character Back to Keyboard ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <conio.h>

int _ungetch(int c);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _ungetch function pushes the character c back to the keyboard, causing c to
be the next character read. The _ungetch function fails if called more than
once before the next read operation. The character c cannot be the EOF
character.

If successful, the _ungetch function returns the character c. A return value of
EOF indicates an error.

Example of _ungetch


ΓòÉΓòÉΓòÉ <hidden> Example of _ungetch ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example uses _getch to read a string delimited by the character 'x'.  It
then calls _ungetch to return the delimiter to the keyboard buffer. Other input
routines can then process the delimiter.

                                                                        *
************************************************************************/

#include <conio.h>
#include <stdio.h>

int main(void)
{
   int ch;

   _cprintf("\nType in some letters.");
   printf("\n");
   _cprintf("If you type in an 'x', the program ends.\n");
   printf("\n");

   for(;;)
   {
      ch = _getch();

      if (ch == 'x')
      {
         _ungetch(ch);
         break;
      }
      _putch(ch);
   }

   ch=_getch();

   printf("\n");
   _cprintf("\nThe last character was '%c'.", ch);

   return 0;

/**************  The output should be similar to:  **********************

   Type in some letters.
   If you type in an 'x', the program ends.

   One Two Three Four Five Si

   The last character was 'x'.
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _cscanf - Read Data from Keyboard
o _getch - _getche - Read Character from Keyboard
o ungetc  - Push Character onto Input Stream
o conio.h


ΓòÉΓòÉΓòÉ 6.265. _unlink - Delete File ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdio.h>  /* also defined in <io.h> */

int _unlink(const char *pathname);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _unlink function deletes the file specified by pathname.

For portability, you can use the SAA remove function.

The _unlink function returns the value 0 if the file is successfully deleted. A
return value of -1 indicates an error, and errno is set to one of the following
values:

Value          Meaning
EACCESS        The path name specifies a read-only file or a directory.
EISOPEN        The file is open.
ENOENT         An incorrect path name was specified, or the file or path name
               was not found.

Example of _unlink


ΓòÉΓòÉΓòÉ <hidden> Example of _unlink ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example deletes the file tmpfile from the system or prints an error
message if unable to delete it.

                                                                        *
************************************************************************/

#include <stdio.h>

int main(void)
{
    if (_unlink("tmpfile") == -1)
        perror("Cannot delete tmpfile");
    else
        printf("tmpfile has been successfully deleted\n");

    return 0;

/*****************  The output should be similar to:  *******************

   tmpfile has been successfully deleted
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o remove  - Delete File
o _rmtmp - Remove Temporary Files
o stdio.h


ΓòÉΓòÉΓòÉ 6.266. _utime - Set Modification Time ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <sys\utime.h>
#include <sys\types.h>

int _utime(char *pathname, struct utimbuf *times);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _utime function sets the modification time for the file specified by
pathname.  The process must have write access to the file;  otherwise, the time
cannot be changed.

Although the utimbuf structure contains a field for access time, only the
modification time is set in the OS/2 operating system. If times is a NULL
pointer, the modification time is set to the current time.  Otherwise, times
must point to a structure of type utimbuf, defined in <sys\utime.h>.  The
modification time is set from the modtime field in this structure.

Note:  The _utime function accepts only even numbers of seconds. If you enter
       an odd number of seconds, the function rounds it down.

The _utime function returns the value 0 if the file modification time was
changed.  A return value of -1 indicates an error, and errno is set to one of
the following values:

Value          Meaning
EACCESS        The path name specifies a directory or read-only file.
EMFILE         There are too many open files.  The file must be opened to
               change its modification time.
ENOENT         The file path name was not found, or the file name was
               incorrectly specified.

Example of _utime


ΓòÉΓòÉΓòÉ <hidden> Example of _utime ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example sets the last modification time of file \TMP\DATA to the current
time.  It prints an error message if it cannot.

                                                                        *
************************************************************************/

#include <sys\types.h>
#include <sys\utime.h>
#include <sys\stat.h>
#include <stdio.h>

int main(void)
{
    struct utimbuf ubuf;
    struct stat statbuf;
    /* seconds to current date from 1970 Jan 1 */
    ubuf.modtime = 946702799;
    /*  Sat Dec 31 23:59:59 1999  */

    /* changing file modification time  */
    if (_utime("\\tmp\\data", &ubuf ) == -1)
    {
       perror("_utime failed");
       _exit(-1);
    }

    /* display the modification time  */
    if (_stat("\\tmp\\data", &statbuf) == 0)
        printf("The file modification time is %s\n",
                 ctime(&statbuf.st_mtime));
    else
        printf("File could not be found\n");

    return 0;

/***********  The output should be similar to:  ************

   The file modification time is
   Fri Dec 31 23:59:58 1999
*/
}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _fstat - Information about Open File
o _stat - Get Information about File or Directory
o sys\utime.h
o sys\types.h


ΓòÉΓòÉΓòÉ 6.267. va_arg - va_end - va_start - Access Function Arguments ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdarg.h>

var_type va_arg(va_list arg_ptr, var_type);

void va_end(va_list arg_ptr);

void va_start(va_list arg_ptr, variable_name);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The va_arg, va_end, and va_start macros access the arguments to a function when
it takes a fixed number of required arguments and a variable number of optional
arguments.  You declare required arguments as ordinary parameters to the
function and access the arguments through the parameter names.

The va_start macro initializes the arg_ptr pointer for subsequent calls to
va_arg and va_end.

The argument variable_name is the identifier of the rightmost named parameter
in the parameter list (preceding , ...).  Use the va_start macro before the
va_arg macro. Corresponding va_start and va_end macros must be in the same
function.

The va_arg macro retrieves a value of the given var_type from the location
given by arg_ptr and increases arg_ptr to point to the next argument in the
list.  The va_arg macro can retrieve arguments from the list any number of
times within the function. The var_type argument must be one of int, long,
double, struct, union, or pointer, or a typedef of one of these types.

The va_end macro is needed to indicate the end of parameter scanning.

The va_arg macro returns the current argument. The va_end and va_start macros
do not return a value.

Example of va_arg - va_end - va_start


ΓòÉΓòÉΓòÉ <hidden> Example of va_arg - va_end - va_start ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example passes a variable number of arguments to a function, stores each
argument in an array, and prints each argument.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdarg.h>

int vout(int max, ...);

int main(void)
{
   vout(3, "Sat", "Sun", "Mon");
   printf("\n");
   vout(5, "Mon", "Tues", "Wed", "Thurs", "Fri");
}

int vout(int max, ...)
{
   va_list arg_ptr;
   int args = 0;
   char *days[7];

   va_start(arg_ptr, max);
   while(args < max)
   {
      days[args] = va_arg(arg_ptr, char *);
      printf("Day:  %s  \n", days[args++]);
      }
   va_end(arg_ptr);
}

/******************  Output should be similar to:  ****************

Day:  Sat
Day:  Sun
Day:  Mon

Day:  Mon
Day:  Tues
Day:  Wed
Day:  Thurs
Day:  Fri
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o vfprintf  - Print Argument Data
o vprintf  - Print Argument Data
o vsprintf  - Print Argument Data
o stdarg.h


ΓòÉΓòÉΓòÉ 6.268. vfprintf  - Print Argument Data ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdarg.h>
#include <stdio.h>

int vfprintf(FILE *stream, const char *format, va_list arg_ptr);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA, Extension

The vfprintf function is similar to fprintf, except that arg_ptr points to a
list of arguments whose number can vary from call to call in the program. These
arguments should be initialized by va_start for each call. In contrast, fprintf
can have a list of arguments, but the number of arguments in that list is fixed
when you compile the program. For a specification of the format string, see
printf.

In extended mode, vfprintf also converts floating-point values of NaN and
infinity to the strings "NAN" or "nan" and "INFINITY" or "infinity". The case
and sign of the string is determined by the format specifiers.  See Infinity
and NaN Support for more information on infinity and NaN values.

If there is no error, vfprintf returns the number of characters written to
stream. If an error occurs, the function returns a negative value.

Example of vfprintf


ΓòÉΓòÉΓòÉ <hidden> Example of vfprintf ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example prints out a variable number of strings to the file myfile.

                                                                        *
************************************************************************/

#include <stdarg.h>
#include <stdio.h>

void vout(FILE *stream, char *fmt, ...);
char fmt1 [] = "%s  %s  %s\n";

int main(void)
{
   FILE *stream;
   stream = fopen("myfile.dat", "w");

   vout(stream, fmt1, "Sat", "Sun", "Mon");
}

void vout(FILE *stream, char *fmt, ...)

{
   va_list arg_ptr;

   va_start(arg_ptr, fmt);
   vfprintf(stream, fmt, arg_ptr);
   va_end(arg_ptr);
}

/******************  Output should be similar to:  ****************

Sat  Sun  Mon
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fprintf  - Write Formatted Data
o printf  - Formatted Print
o sprintf  - Formatted Print to Buffer
o va_arg - va_end - va_start - Access Function Arguments
o vprintf  - Print Argument Data
o vsprintf  - Print Argument Data
o Infinity and NaN Support
o stdarg.h
o stdio.h


ΓòÉΓòÉΓòÉ 6.269. vprintf  - Print Argument Data ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdarg.h>
#include <stdio.h>

int vprintf(const char *format, va_list arg_ptr);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA, Extension

The vprintf function is similar to printf, except that arg_ptr points to a list
of arguments whose number can vary from call to call in the program. These
arguments should be initialized by va_start for each call. In contrast, printf
can have a list of arguments, but the number of arguments in that list is fixed
when you compile the program. For a specification of the format string, see
printf.

In extended mode, vprintf also converts floating-point values of NaN and
infinity to the strings "NAN" or "nan" and "INFINITY" or "infinity". The case
and sign of the string is determined by the format specifiers.  See Infinity
and NaN Support for more information on infinity and NaN values.

If there is no error, vprintf returns the number of characters written to
stdout.  If an error occurs, this function returns a negative value.

Example of vprintf


ΓòÉΓòÉΓòÉ <hidden> Example of vprintf ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example prints out a variable number of strings to stdout.

                                                                        *
************************************************************************/

#include <stdarg.h>
#include <stdio.h>

void vout(char *fmt, ...);
char fmt1 [] = "%s  %s  %s   %s   %s \n";

int main(void)
{
   FILE *stream;
   stream = fopen("myfile.dat", "w");

   vout(fmt1, "Mon", "Tues", "Wed", "Thurs", "Fri");
}

void vout(char *fmt, ...)
{
   va_list arg_ptr;

   va_start(arg_ptr, fmt);
   vprintf(fmt, arg_ptr);
   va_end(arg_ptr);
}

/******************  Output should be similar to:  ****************

Mon  Tues  Wed   Thurs   Fri
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fprintf  - Write Formatted Data
o printf  - Formatted Print
o sprintf  - Formatted Print to Buffer
o va_arg - va_end - va_start - Access Function Arguments
o vfprintf  - Print Argument Data
o vsprintf  - Print Argument Data
o Infinity and NaN Support
o stdarg.h
o stdio.h


ΓòÉΓòÉΓòÉ 6.270. vsprintf  - Print Argument Data ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdarg.h>
#include <stdio.h>

int vsprintf(char *target-string, const char *format, va_list arg_ptr);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA, Extension

The vsprintf function is similar to sprintf except that arg_ptr points to a
list of arguments whose number can vary from call to call in the program.  In
contrast, sprintf can have a list of arguments, but the number of arguments in
that list is fixed when you compile the program. For a specification of the
format string, see printf.

In extended mode, vsprintf also converts floating-point values of NaN and
infinity to the strings "NAN" or "nan" and "INFINITY" or "infinity". The case
and sign of the string is determined by the format specifiers.  See Infinity
and NaN Support for more information on infinity and NaN values.

If there is no error, vsprintf returns the number of characters written to
target-string. If an error occurs, this function returns a negative value.

Example of vsprintf


ΓòÉΓòÉΓòÉ <hidden> Example of vsprintf ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example assigns a variable number of strings to string and prints the
resultant string.

                                                                        *
************************************************************************/

#include <stdarg.h>
#include <stdio.h>

void vout(char *string, char *fmt, ...);
char fmt1 [] = "%s  %s  %s\n";

int main(void)
{
   char string[100];

   vout(string, fmt1, "Sat", "Sun", "Mon");
   printf("The string is:  %s\n", string);
}

void vout(char *string, char *fmt, ...)
{
   va_list arg_ptr;

   va_start(arg_ptr, fmt);
   vsprintf(string, fmt, arg_ptr);
   va_end(arg_ptr);
}

/******************  Output should be similar to:  ****************

The string is:  Sat  Sun  Mon
*/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fprintf  - Write Formatted Data
o printf  - Formatted Print
o sprintf  - Formatted Print to Buffer
o va_arg - va_end - va_start - Access Function Arguments
o vfprintf  - Print Argument Data
o vprintf  - Print Argument Data
o Infinity and NaN Support
o stdarg.h
o stdio.h


ΓòÉΓòÉΓòÉ 6.271. _wait - Wait for Child Process ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <process.h>

int _wait (int *stat_loc);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _wait function delays a parent process until one of the immediate child
processes stops.  If all the child processes stop before _wait is called,
control returns immediately to the parent function.

If stat_loc is NULL, the _wait function does not use it.  If it is not NULL,
_wait places information about the return status and the return code ot the
child process that ended in the location to which stat_loc points.

If the child process ended normally, with a call to the OS/2 DosExit function,
the lowest-order byte of stat_loc is 0, and the next higher-order byte contains
the lowest-order byte of the argument passed to DosExit by the child process.
The value of this byte depends on how the child process caused the system to
call DosExit.

If the child process called exit, _exit, or return from main, the byte contains
the lowest-order byte of the argument the child process passed to exit, _exit,
or return.  The value of the byte is undefined if the child process caused a
DosExit call simply by reaching the end of main.

If the child process ended abnormally, the lowest-order byte of stat_loc
contains the return status code from the OS/2 DosWaitChild function, and the
next higher-order byte is 0. See the Toolkit online Programming Reference for
details about the DosWaitChild return status codes.

If _wait returns after a normal end of a child process, it returns the process
identifier of the child process to the parent process. A return value of -1
indicates an error, and errno is set to one of the following values:

Value          Meaning
ECHILD         There were no child processes or they all ended before the call
               to _wait. This value indicates that no child processes exist for
               the particular process.
EINTR          Unexpected end of a child process.

Example of _wait


ΓòÉΓòÉΓòÉ <hidden> Example of _wait ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example creates a new process called CHILD.EXE, specifying P_NOWAIT when
the child process is called. The parent process calls _wait and waits for the
child process to stop running. The parent process then displays the return
information of the child process in hexadecimal.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <process.h>

int stat_child;

int main(void)
{
    int pid;

    _spawnl(P_NOWAIT,"child2.exe", "child2.exe", NULL);

    if ( (pid=_wait(&stat_child)) == -1 )
        perror(NULL);       /* Display error status message, if any */
    else
        printf("child process %d just ran.\n",pid);

    /* Display the word returned when child ended. */
    printf("return information was 0x%X\n",stat_child);

    return 0;


/* If the source for child2.exe is:                                    */
/*                                                                     */
/*  #include <stdio.h>                                                 */

/*  int main(void)                                                     */
/*  {                                                                  */
/*      puts("child2.exe is an executable file");                      */
/*  }                                                                  */
/*                                                                     */
/*  Then the ouput should be similar to:              */

/* child process 24 just ran.                         */
/* return information was 0x0                         */

}


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _cwait - Wait for Child Process
o _execl - _execvp - Load and Run Child Process
o exit  - End Program
o _exit - End Process
o _spawnl -_spawnvpe -Start and Run Child Processes
o process.h


ΓòÉΓòÉΓòÉ 6.272. wcscat  - Append wchar_t Strings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <wcstr.h>

wchar_t *wcscat(wchar_t *string1, const wchar_t *string2);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: SAA

The wcscat function appends a copy of the string pointed to by string2 to the
end of the string pointed to by string1.

The wcscat function operates on null-terminated wchar_t strings. The string
arguments to this function should contain a wchar_t null character marking the
end of the string. Boundary checking is not performed.

The wcscat function returns the value of string1.

Example of wcscat


ΓòÉΓòÉΓòÉ <hidden> Example of wcscat ΓòÉΓòÉΓòÉ

/*************************************************************************
*
This example creates the wide character string "computer program" using wcscat.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <wcstr.h>

#define SIZE 40


int main(void)
{
  wchar_t buffer1[SIZE] = L"computer";
  wchar_t * string      = L" program";
  wchar_t * ptr;

  ptr = wcscat( buffer1, string );
  printf( "buffer1 = %ls\n", buffer1 );

}

/************************************************************************
*

/****************  Output should be similar to:  ******************

buffer1 = computer program
*/

                                                                        *
************************************************************************/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strcat  - Concatenate Strings
o strncat  - Concatenate Strings
o wcsncat  - Concatenate wchar_t Strings
o wcstr.h


ΓòÉΓòÉΓòÉ 6.273. wcschr  - Search wchar_t String for Given wchar_t ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <wcstr.h>

wchar_t  *wcschr(const wchar_t *string1, wchar_t character);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: SAA

The wcschr function searches string for the occurrence of character. The
character may be a wchar_t null character (\0);  the wchar_t null character at
the end of string is included in the search.

The wcschr function operates on null-terminated wchar_t strings. The string
argument to this function should contain a wchar_t null character marking the
end of the string.

The wcschr function returns a pointer to the first occurrence of character in
string. If the character is not found, a NULL pointer is returned.

Example of wcschr


ΓòÉΓòÉΓòÉ <hidden> Example of wcschr ΓòÉΓòÉΓòÉ

/*************************************************************************
*
This example finds the first occurrence of the character p in the wide
character string "computer program".

                                                                        *
************************************************************************/

#include <stdio.h>
#include <wcstr.h>

#define SIZE 40

int main(void)
{
  wchar_t buffer1[SIZE] = L"computer program";
  wchar_t * ptr;
  wchar_t ch = L'p';

  ptr = wcschr( buffer1, ch );
  printf( "The first occurrence of %lc in '%ls' is '%ls'\n",
                          ch, buffer1, ptr );

}

/************************************************************************
*

/****************  Output should be similar to:  ******************

The first occurrence of p in 'computer program' is 'puter program'
*/

                                                                        *
************************************************************************/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strchr  - Search for Character
o strcspn  - Compare Strings
o strpbrk  - Find Characters in String
o strrchr  - Find Last Occurrence of Character in String
o strspn  - Search Strings
o wcscspn  - Find Offset of First wchar_t Match
o wcspbrk  - Locate wchar_t Characters in String
o wcsrchr  - Locate wchar_t Character in String
o wcsspn  - Search wchar_t Characters in String
o wcswcs  - Locate wchar_t Substring in wchar_t String
o wcstr.h


ΓòÉΓòÉΓòÉ 6.274. wcscmp  - Compare wchar_t Strings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <wcstr.h>

int wcscmp(const wchar_t *string1, const wchar_t *string2);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: SAA

The wcscmp function compares two wchar_t strings.

The wcscmp function operates on null-terminated wchar_t strings. The string
arguments to this function should contain a wchar_t null character marking the
end of the string. Boundary checking is not performed when a string is added to
or copied.

The wcscmp function returns a value indicating the relationship between the two
strings, as follows:

Value               Meaning
Less than 0         string1 less than string2
0                   string1 identical to string2
Greater than 0      string1 greater than string2.

Example of wcscmp


ΓòÉΓòÉΓòÉ <hidden> Example of wcscmp ΓòÉΓòÉΓòÉ

/*************************************************************************
*

This example compares the wide character string string1 to string2 using
wcscmp.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <wcstr.h>

int main(void)
{
  int  result;
  wchar_t string1[] = L"abcdef";
  wchar_t string2[] = L"abcdefg";

  result = wcscmp( string1, string2 );

  if ( result == 0 )
    printf( "\"%ls\" is identical to \"%ls\"\n", string1, string2);
  else if ( result < 0 )
    printf( "\"%ls\" is less than \"%ls\"\n", string1, string2 );
  else
    printf( "\"%ls\" is greater than \"%ls\"\n", string1, string2);
}

/************************************************************************
*

/****************  Output should be similar to:  ******************

"abcdef" is less than "abcdefg"
*/

                                                                        *
************************************************************************/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strcmp  - Compare Strings
o strcmpi - Compare Strings
o stricmp - Compare Strings
o strnicmp - Compare Strings
o wcsncmp  - Compare wchar_t Strings
o wcstr.h


ΓòÉΓòÉΓòÉ 6.275. wcscpy  - Copy wchar_t Strings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <wcstr.h>

wchar_t *wcscpy(wchar_t *string1, const wchar_t *string2);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: SAA

The wcscpy function copies the contents of string2 (including the ending
wchar_t null character) into string1.

The wcscpy function operates on null-terminated wchar_t strings. The string
arguments to this function should contain a wchar_t null character marking the
end of the string. Boundary checking is not performed.

The wcscpy function returns the value of string1.

Example of wcscpy


ΓòÉΓòÉΓòÉ <hidden> Example of wcscpy ΓòÉΓòÉΓòÉ

/*************************************************************************
*
This example copies the contents of source to destination.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <wcstr.h>

#define SIZE    40

int main(void)
{
  wchar_t source[ SIZE ] = L"This is the source string";
  wchar_t destination[ SIZE ] = L"And this is the destination string";
  wchar_t * return_string;

  printf( "destination is originally = \"%ls\"\n", destination );
  return_string = wcscpy( destination, source );
  printf( "After wcscpy, destination becomes \"%ls\"\n", destination );
}

/************************************************************************
*

/****************  Output should be similar to:  ******************

destination is originally = "And this is the destination string"
After wcscpy, destination becomes "This is the source string"
*/

                                                                        *
************************************************************************/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strcpy  - Copy Strings
o strdup - Duplicate String
o strncpy  - Copy Strings
o wcsncpy  - Copy wchar_t Strings
o wcstr.h


ΓòÉΓòÉΓòÉ 6.276. wcscspn  - Find Offset of First wchar_t Match ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <wcstr.h> /* SAA extension to ANSI */

size_t wcscspn(const wchar_t *string1, const wchar_t *string2);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: SAA

The wcscspn function determines the number of wchar_t characters in the initial
segment of the string pointed to by string1 that do not appear in the string
pointed to by string2.

The wcscspn function operates on null-terminated wchar_t strings.  The string
arguments to this function should contain a wchar_t null character marking the
end of the string.

The wcscspn function returns the number of wchar_t characters in the segment.

Example of wcscspn


ΓòÉΓòÉΓòÉ <hidden> Example of wcscspn ΓòÉΓòÉΓòÉ

/*************************************************************************
*
This example uses wcscspn to find the first occurrence of any of the characters
a, x, l, or e in string.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <wcstr.h>

#define SIZE    40

int main(void)
{
  wchar_t string[ SIZE ] = L"This is the source string";
  wchar_t * substring = L"axle";

  printf( "The first %i characters in the string \"%ls\" are not in the "
          "string \"%ls\" \n", wcscspn( string, substring),
          string, substring );
}

/************************************************************************
*

/****************  Output should be similar to:  ******************

The first 10 characters in the string "This is the source string" are not
in the string "axle"
*/

                                                                        *
************************************************************************/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strcspn  - Compare Strings
o strspn  - Search Strings
o wcsspn  - Search wchar_t Characters in String
o wcswcs  - Locate wchar_t Substring in wchar_t String
o wcstr.h


ΓòÉΓòÉΓòÉ 6.277. wcslen  - Calculate Length of wchar_t String ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <wcstr.h>

size_t wcslen(const wchar_t *string);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: SAA

The wcslen function computes the number of wchar_t characters in the string
pointed to by string.

The wcslen function returns the number of wchar_t characters that precede the
terminating wchar_t null character.

Example of wcslen


ΓòÉΓòÉΓòÉ <hidden> Example of wcslen ΓòÉΓòÉΓòÉ

/*************************************************************************
*
This example computes the length of a wchar_t string.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <wcstr.h>

int main(void)
{
  wchar_t * string = L"abcdef";

  printf( "Length of \"%ls\" is %i\n", string, wcslen( string ));
}

/************************************************************************
*

/****************  Output should be similar to:  ******************

Length of "abcdef" is 6
*/

                                                                        *
************************************************************************/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o mblen  - Multibyte String Length
o strlen  - Determine String Length
o wcstr.h


ΓòÉΓòÉΓòÉ 6.278. wcsncat  - Concatenate wchar_t Strings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <wcstr.h>

wchar_t *wcsncat(wchar_t *string1, const wchar_t *string2, size_t count);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: SAA

The wcsncat function appends up to count wide characters from string2 to the
end of string1 and appends a wchar_t null character to the result.

The wcsncat function operates on null-terminated wchar_t strings. The string
arguments to this function should contain a wchar_t null character marking the
end of the string.

The wcsncat function returns string1.

Example of wcsncat


ΓòÉΓòÉΓòÉ <hidden> Example of wcsncat ΓòÉΓòÉΓòÉ

/*************************************************************************
*
This example demonstrates the difference between wcscat and wcsncat.  wcscat
appends the entire second string to the first whereas wcsncat appends only the
specified number of characters in the second string to the first.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <wcstr.h>

#define SIZE 40

int main(void)
{
  wchar_t buffer1[SIZE] = L"computer";
  wchar_t * ptr;

  /* Call wcscat with buffer1 and " program" */

  ptr = wcscat( buffer1, L" program" );
  printf( "wcscat : buffer1 = \"%ls\"\n", buffer1 );

  /* Reset buffer1 to contain just the string "computer" again */

  memset( buffer1, L'\0', sizeof( buffer1 ));
  ptr = wcscpy( buffer1, L"computer" );

  /* Call wcsncat with buffer1 and " program" */
  ptr = wcsncat( buffer1, L" program", 3 );
  printf( "wcsncat: buffer1 = \"%ls\"\n", buffer1 );
}

/************************************************************************
*

/****************  Output should be similar to:  ******************

wcscat : buffer1 = "computer program"
wcsncat: buffer1 = "computer pr"
*/

                                                                        *
************************************************************************/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strncat  - Concatenate Strings
o strcat  - Concatenate Strings
o wcscat  - Append wchar_t Strings
o wcstr.h


ΓòÉΓòÉΓòÉ 6.279. wcsncmp  - Compare wchar_t Strings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <wcstr.h>

int wcsncmp(const wchar_t *string1, const wchar_t *string2, size_t count);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: SAA

The wcsncmp function compares up to count wide characters in string1 to
string2.

The wcsncmp function operates on null-terminated wchar_t strings. The string
arguments to this function should contain a wchar_t null character marking the
end of the string.

The wcsncmp function returns a value indicating the relationship between the
two strings, as follows:

Value               Meaning
Less than 0         string1 less than string2
0                   string1 identical to string2
Greater than 0      string1 greater than string2.

Example of wcsmcmp


ΓòÉΓòÉΓòÉ <hidden> Example of wcsncmp ΓòÉΓòÉΓòÉ

/*************************************************************************
*
This example demonstrates the difference between wcscmp and wcsncmp.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <wcstr.h>

#define SIZE 10

int main(void)
{
  int  result;
  int  index = 3;
  wchar_t buffer1[SIZE] = L"abcdefg";
  wchar_t buffer2[SIZE] = L"abcfg";
  void print_result( int, wchar_t *, wchar_t * );

  result = wcscmp( buffer1, buffer2 );
  printf( "Comparison of each character\n" );
  printf( "  wcscmp: " );
  print_result( result, buffer1, buffer2 );

  result = wcsncmp( buffer1, buffer2, index);
  printf( "\nComparison of only the first %i characters\n", index );
  printf( "  wcsncmp: " );
  print_result( result, buffer1, buffer2 );
}

void print_result( int res, wchar_t * p_buffer1, wchar_t * p_buffer2 )
{
  if ( res == 0 )
    printf( "\"%ls\" is identical to \"%ls\"\n", p_buffer1, p_buffer2);
  else if ( res < 0 )
    printf( "\"%ls\" is less than \"%ls\"\n", p_buffer1, p_buffer2 );
  else
    printf( "\"%ls\" is greater than \"%ls\"\n", p_buffer1, p_buffer2 );
}

/************************************************************************
*

/****************  Output should be similar to:  ******************

Comparison of each character
  wcscmp: "abcdefg" is less than "abcfg"

Comparison of only the first 3 characters
  wcsncmp: "abcdefg" is identical to "abcfg"
*/

                                                                        *
************************************************************************/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strncmp  - Compare Strings
o strcmp  - Compare Strings
o strcoll  - Compare Strings
o strcmpi - Compare Strings
o stricmp - Compare Strings
o strnicmp - Compare Strings
o wcscmp  - Compare wchar_t Strings
o wcstr.h


ΓòÉΓòÉΓòÉ 6.280. wcsncpy  - Copy wchar_t Strings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <wcstr.h>

wchar_t *wcsncpy(wchar_t *string1, const wchar_t *string2, size_t count);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: SAA

The wcsncpy function copies up to count wide characters from string2 to
string1. If string2 is shorter than count characters, string1 is padded out to
count characters with wchar_t null characters.

The wcsncpy function operates on null-terminated wchar_t strings. The string
arguments to this function should contain a wchar_t null character marking the
end of the string.

The wcsncpy function returns string1.

Example of wcsncpy


ΓòÉΓòÉΓòÉ <hidden> Example of wcsncpy ΓòÉΓòÉΓòÉ

/*************************************************************************
*
This example demonstrates the difference between wcscpy and wcsncpy.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <wcstr.h>

#define SIZE    40

int main(void)
{
  wchar_t source[ SIZE ] = L"123456789";
  wchar_t source1[ SIZE ] = L"123456789";
  wchar_t destination[ SIZE ] = L"abcdefg";
  wchar_t destination1[ SIZE ] = L"abcdefg";
  wchar_t * return_string;
  int    index = 5;

  /* This is how wcscpy works */
  printf( "destination is originally = '%ls'\n", destination );
  return_string = wcscpy( destination, source );
  printf( "After wcscpy, destination becomes '%ls'\n\n", destination );

  /* This is how wcsncpy works */
  printf( "destination1 is originally = '%ls'\n", destination1 );
  return_string = wcsncpy( destination1, source1, index );
  printf( "After wcsncpy, destination1 becomes '%ls'\n", destination1 );
}

/************************************************************************
*

/****************  Output should be similar to:  ******************

destination is originally = 'abcdefg'
After wcscpy, destination becomes '123456789'

destination1 is originally = 'abcdefg'
After wcsncpy, destination1 becomes '12345fg'
*/

                                                                        *
************************************************************************/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strcpy  - Copy Strings
o strncpy  - Copy Strings
o wcscpy  - Copy wchar_t Strings
o wcstr.h



ΓòÉΓòÉΓòÉ 6.281. wcspbrk  - Locate wchar_t Characters in String ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <wcstr.h>

wchar_t *wcspbrk(const wchar_t *string1, const wchar_t *string2);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: SAA

The wcspbrk function locates the first occurrence in the string pointed to by
string1 of any character from the string pointed to by string2.

The wcspbrk function returns a pointer to the character, or NULL if no wchar_t
from string2 occurs in string1.

Example of wcscpbrk


ΓòÉΓòÉΓòÉ <hidden> Example of wcspbrk ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example returns a pointer to the first occurrence in the array string of
either a or b.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <wcstr.h>

int main(void)
{
  wchar_t * result;
  wchar_t * string = L"The Blue Danube";
  wchar_t *chars = L"ab";

  result = wcspbrk( string, chars);
   printf("The first occurrence of any of the characters \"%ls\" in "
          "\"%ls\" is \"%ls\"\n", chars, string, result);

}

/************************************************************************
*

/****************  Output should be similar to:  ******************

The first occurrence of any of the characters "ab" in "The Blue Danube"
is "anube"
*/

                                                                        *
************************************************************************/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strchr  - Search for Character
o strcspn  - Compare Strings
o strpbrk  - Find Characters in String
o strrchr  - Find Last Occurrence of Character in String
o strspn  - Search Strings
o wcschr  - Search wchar_t String for Given wchar_t
o wcscspn  - Find Offset of First wchar_t Match
o wcsncmp  - Compare wchar_t Strings
o wcsrchr  - Locate wchar_t Character in String
o wcsspn  - Search wchar_t Characters in String
o wcswcs  - Locate wchar_t Substring in wchar_t String
o wcstr.h


ΓòÉΓòÉΓòÉ 6.282. wcsrchr  - Locate wchar_t Character in String ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <wcstr.h>

wchar_t *wcsrchr(const wchar_t *string, wchar_t character);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: SAA

The wcsrchr function locates the last occurrence of character in the string
pointed to by string.  The terminating wchar_t null character is considered to
be part of the string.

The wcsrchr function returns a pointer to the character, or a NULL pointer if
character does not occur in the string.

Example of wcsrchr


ΓòÉΓòÉΓòÉ <hidden> Example of wcsrchr ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example compares the use of wcschr and wcsrchr.  It searches the string
for the first and last occurrence of p in the wide character string.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <wcstr.h>

#define SIZE 40

int main(void)
{
  wchar_t buf[SIZE] = L"computer program";
  wchar_t * ptr;
  int    ch = 'p';

  /* This illustrates wcschr */
  ptr = wcschr( buf, ch );
  printf( "The first occurrence of %c in '%ls' is '%ls'\n", ch, buf, ptr );

  /* This illustrates wscrchr */
  ptr = wcsrchr( buf, ch );
  printf( "The last occurrence of %c in '%ls' is '%ls'\n",  ch, buf, ptr );
}

/************************************************************************
*

/****************  Output should be similar to:  ******************

The first occurrence of p in 'computer program' is 'puter program'
The last occurrence of p in 'computer program' is 'program'
*/

                                                                        *
************************************************************************/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strchr  - Search for Character
o strcspn  - Compare Strings
o strpbrk  - Find Characters in String
o strrchr  - Find Last Occurrence of Character in String
o strspn  - Search Strings
o wcschr  - Search wchar_t String for Given wchar_t
o wcscspn  - Find Offset of First wchar_t Match
o wcsspn  - Search wchar_t Characters in String
o wcswcs  - Locate wchar_t Substring in wchar_t String
o wcspbrk  - Locate wchar_t Characters in String
o wcstr.h


ΓòÉΓòÉΓòÉ 6.283. wcsspn  - Search wchar_t Characters in String ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <wcstr.h>

size_t wcsspn(const wchar_t *string1, const wchar_t *string2);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: SAA

The wcsspn function computes the number of wchar_t characters in the initial
segment of the string pointed to by string1, which consists entirely of wchar_t
characters from the string pointed to by string2.

The wcsspn function returns the number of wchar_t characters in the segment.

Example of wcsspn


ΓòÉΓòÉΓòÉ <hidden> Example of wcsspn ΓòÉΓòÉΓòÉ

/************************************************************************
*
This example finds the first occurrence in the array string of a character that
is neither an a, b, nor c.  Because the string in this example is cabbage,
wcsspn returns 5, the index of the segment of cabbage before a character that
is not an a, b, or c.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <wcstr.h>

int main(void)
{
  wchar_t * string = L"cabbage";
  wchar_t * source = L"abc";
  int index;

  index = wcsspn( string, L"abc" );
  printf( "The first %d characters of \"%ls\" are found in \"%ls\"\n",
              index, string, source );
}

/************************************************************************
*

/****************  Output should be similar to:  ******************

The first 5 characters of "cabbage" are found in "abc"
*/

                                                                        *
************************************************************************/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strchr  - Search for Character
o strcspn  - Compare Strings
o strpbrk  - Find Characters in String
o strrchr  - Find Last Occurrence of Character in String
o strspn  - Search Strings
o wcschr  - Search wchar_t String for Given wchar_t
o wcscspn  - Find Offset of First wchar_t Match
o wcsrchr  - Locate wchar_t Character in String
o wcsspn  - Search wchar_t Characters in String
o wcswcs  - Locate wchar_t Substring in wchar_t String
o wcspbrk  - Locate wchar_t Characters in String
o wcstr.h


ΓòÉΓòÉΓòÉ 6.284. wcstombs  - Convert wchar_t String to Multibyte Character String ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

size_t wcstombs(char *dest, const wchar_t *string, size_t count);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The wcstombs function converts the wchar_t string pointed to by string into the
multibyte array pointed to by dest.  The converted string begins in the initial
shift state.  The conversion stops after count bytes in dest are filled up or a
wchar_t null character is encountered.

The wcstombs function returns the length in bytes of the multibyte character
string, not including a terminating null character.  The value (size_t)-1 is
returned if an invalid multibyte character is encountered.

Example of wcstombs


ΓòÉΓòÉΓòÉ <hidden> Example of wcstombs ΓòÉΓòÉΓòÉ

/*************************************************************************
*
In this example, a wchar_t string is converted to a char string twice.  The
first call converts the entire string, while the second call only converts
three characters. The results are printed each time.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#define SIZE 20

int main(void)
{
  char dest[SIZE];
  wchar_t * dptr = L"string";
  size_t count = SIZE;
  size_t length;

  length = wcstombs( dest, dptr, count );
  printf( "%d characters were converted.\n", length );
  printf( "The converted string is \"%s\"\n\n", dest );

  /* Reset the destination buffer */
  memset( dest, '\0', sizeof(dest));

  /* Now convert only 3 characters */
  length = wcstombs( dest, dptr, 3 );
  printf( "%d characters were converted.\n", length );
  printf( "The converted string is \"%s\"\n", dest );
}

/************************************************************************
*

/****************  Output should be similar to:  ******************

6 characters were converted.
The converted string is "string"

3 characters were converted.
The converted string is "str"
*/

                                                                        *
************************************************************************/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o mbstowcs  - Convert Multibyte Characters to wchar_t Characters
o wcslen  - Calculate Length of wchar_t String
o wctomb  - Convert wchar_t Character to Multibyte Character
o stdlib.h


ΓòÉΓòÉΓòÉ 6.285. wcswcs  - Locate wchar_t Substring in wchar_t String ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <wcstr.h>

wchar_t *wcswcs(const wchar_t *string1, const wchar_t *string2);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: SAA

The wcswcs function locates the first occurrence in the string pointed to by
string1 of the sequence of wchar_t characters (excluding the terminating
wchar_t null character) in the string pointed to by string2.

The wcswcs function returns a pointer to the located string or NULL if the
string is not found.  If string2 points to a string with zero length, the
function returns string1.

Example of wcswcs


ΓòÉΓòÉΓòÉ <hidden> Example of wcswcs ΓòÉΓòÉΓòÉ

/*************************************************************************
*
This example finds the first occurrence of the wide character string pr in
buffer1.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <wcstr.h>

#define SIZE 40

int main(void)
{
  wchar_t buffer1[SIZE] = L"computer program";
  wchar_t * ptr;
  wchar_t * wch = L"pr";

  ptr = wcswcs( buffer1, wch );
  printf( "The first occurrence of %ls in '%ls' is '%ls'\n",
                          wch, buffer1, ptr );
}

/************************************************************************
*

/****************  Output should be similar to:  ******************

The first occurrence of pr in 'computer program' is 'program'
*/

                                                                        *
************************************************************************/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o strchr  - Search for Character
o strcspn  - Compare Strings
o strpbrk  - Find Characters in String
o strrchr  - Find Last Occurrence of Character in String
o strspn  - Search Strings
o wcschr  - Search wchar_t String for Given wchar_t
o wcscspn  - Find Offset of First wchar_t Match
o wcspbrk  - Locate wchar_t Characters in String
o wcsrchr  - Locate wchar_t Character in String
o wcsspn  - Search wchar_t Characters in String
o wcstr.h


ΓòÉΓòÉΓòÉ 6.286. wctomb  - Convert wchar_t Character to Multibyte Character ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <stdlib.h>

int wctomb(char *string, wchar_t character);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: ANSI, SAA

The wctomb function converts the wchar_t value of character into a multibyte
array pointed to by string.  If the value of character is 0, the function is
left in the initial shift state.  At most, wctomb stores MB_CUR_MAX characters
in string.

The wctomb function returns the length in bytes of the multibyte character.
The value -1 is returned if character is not a valid multibyte character.  If
string is a NULL pointer, the wctomb function returns nonzero if
shift-dependent encoding is used, or 0 otherwise.

Example of wctomb


ΓòÉΓòÉΓòÉ <hidden> Example of wctomb ΓòÉΓòÉΓòÉ

/*************************************************************************
*
This example converts the wide character c to a character.

                                                                        *
************************************************************************/

#include <stdio.h>
#include <stdlib.h>

#define SIZE 40

int main(void)
{
  static char  buffer[ SIZE ];
  wchar_t wch = L'c';
  int length;

  length = wctomb( buffer, wch );
  printf( "The number of bytes that comprise the multibyte "
             "character is %i\n", length );
  printf( "And the converted string is \"%s\"\n", buffer );
}

/************************************************************************
*

/****************  Output should be similar to:  ******************

The number of bytes that comprise the multibyte character is 1
And the converted string is "c"
*/

                                                                        *
************************************************************************/


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o mbtowc  - Convert Multibyte Character to wchar_t
o wcslen  - Calculate Length of wchar_t String
o wcstombs  - Convert wchar_t String to Multibyte Character String
o stdlib.h


ΓòÉΓòÉΓòÉ 6.287. _write - Writes from Buffer to File ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Format ΓòÉΓòÉΓòÉ

#include <io.h>

int _write(int handle, const void *buffer, unsigned int count);


ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ

Language Level: Extension

The _write function writes count bytes from buffer into the file associated
with handle. The write operation begins at the current position of the file
pointer associated with the given file. If the file is open for appending, the
operation begins at the end of the file. After the write operation, the file
pointer is increased by the number of bytes actually written.

If the given file was opened in text mode, each line feed character is replaced
with a carriage return/line feed pair in the output.  The replacement does not
affect the return value.

The _write function returns the number of bytes moved from the buffer to the
file. The return value may be positive but less than count. A return value of
-1 indicates an error, and errno is set to one of the following values:

Value          Meaning
EBADF          The file handle is not valid, or the file is not open for
               writing.
ENOSPC         No space is left on the device.
EOS2ERR        The call to the operating system was not successful.

Example of _write


ΓòÉΓòÉΓòÉ <hidden> Example of _write ΓòÉΓòÉΓòÉ

/************************************************************************
*

This example writes the contents of the character array buffer to the output
file whose handle is fh.

                                                                        *
************************************************************************/

#include <io.h>
#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>
#include <string.h>

int main(void)
   {
   int  fh;
   char buffer[20];

   memset(buffer,'a',20);  /* initialize storage  */

   printf("\nCreating sample.dat.\n");
   system("echo Sample Program > sample.dat");

   if (-1 == (fh = _open("sample.dat",O_RDWR | O_APPEND)))
      {
      perror("Unable to open sample.dat");
      return 1;
      }

   if (5 != _write(fh,buffer,5) )
      {
      perror("Unable to write to sample.dat");
      _close(fh);
      return 1;
      }

   printf("Successfully appended 5 characters.\n");

   _close(fh);
   return 0;

/******************  The expected output is:  ***************************

      Creating sample.dat.
      Successfully appended 5 characters.
*/
   }


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o _creat - Create New File
o fread  - Read Items
o fwrite  - Write Items
o _lseek - Move File Pointer
o _open - Open File
o _read - Read Into Buffer
o _sopen - Open Shared File
o _tell - Get Pointer Position
o io.h


ΓòÉΓòÉΓòÉ 7. Include Files ΓòÉΓòÉΓòÉ

The include files provided with the runtime library contain macro and constant
definitions, type definitions, and function declarations.  Some functions
require definitions and declarations from include files to work properly. The
inclusion of files is optional, as long as the necessary statements from the
files are coded directly into the source.

Note:  If the /Ms compiler option (use _System linkage) is specified, you must
include the appropriate header files with the declarations of the library
functions that you use.

This section describes the following include files, explains their contents,
and lists the functions that use the files.

o assert.h
o builtin.h
o conio.h
o ctype.h
o direct.h
o errno.h
o fcntl.h
o float.h
o io.h
o limits.h
o locale.h
o malloc.h
o math.h
o memory.h
o process.h
o search.h
o setjmp.h
o share.h
o signal.h
o stdarg.h
o stddef.h
o stdio.h
o stdlib.h
o string.h
o sys\stat.h
o sys\timeb.h
o sys\types.h
o sys\utime.h
o time.h
o wcstr.h


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o #include


ΓòÉΓòÉΓòÉ 7.1. assert.h ΓòÉΓòÉΓòÉ

The assert.h include file defines the assert macro.  You must include assert.h
when you use assert.

The definition of assert is in an #ifndef preprocessor block.  If you have not
defined the identifier NDEBUG through a #define directive or on the compiler
command line, the assert macro tests a given expression (the assertion).  If
the assertion is false, the system prints a message to stderr and an abort
signal is raised for the program.

If NDEBUG is defined, assert is defined to do nothing. You can suppress program
assertions by defining NDEBUG.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o #define
o #ifndef
o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.2. builtin.h ΓòÉΓòÉΓòÉ

The builtin.h include file contains function declarations for the following
built-in functions:

_alloca             _disable
_enable             _facos
_fasin              _fcos
_fcossin            _fpatan
_fptan              _fsin
_fsincos            _fyl2x
_fyl2xp1            _f2xm1
_getTIBvalue        _inp
_inpd               _inpw
_interrupt          _outp
_outpd              _outpw
__parmdwords

The builtin.h file also includes declaration for the following intrinsic
functions:

_clear87            _control87
_status87

The functions _clear87, _control87, and _status87 are also defined in float.h.
The function _alloca is also defined in stdlib.h and malloc.h. The functions
_inp, _inpd, _inpw, _outp, _outpd, and _outpw are also defined in conio.h.

The builtin.h file also includes a declaration for the type size_t, which is
also defined in stddef.h.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Intrinsic Functions
o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.3. conio.h ΓòÉΓòÉΓòÉ

The conio.h include file contains definitions for the functions that involve
screen and console input and output:

_cgets              _cprintf
_cputs              _cscanf
_getch              _getche
_inp                _inpd
_inpw               _kbhit
_outp               _outpd
_outpw              _putch
_ungetch


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o io.h
o stdio.h
o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.4. ctype.h ΓòÉΓòÉΓòÉ

The ctype.h include file defines functions used in character classification.
The functions defined in ctype.h are:

isalnum             isalpha
iscntrl             isdigit
isgraph             islower
isprint             ispunct
isspace             isupper
isxdigit            &tolower.
&toupper.

In extended mode, the ctype.h file also includes definitions for the following
C/C++Tools extensions:

_isascii            _iscsym
_iscsymf            _toascii
_tolower            _toupper

In the C/C++ Tools compiler, the ctype.h functions are all implemented as
macros.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.5. direct.h ΓòÉΓòÉΓòÉ

The direct.h include file contains definitions for functions that control
directories and drives. The functions defined in direct.h are:

_chdir              _chdrive
_getcwd             _getdcwd
_getdrive           _mkdir
_rmdir


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.6. errno.h ΓòÉΓòÉΓòÉ

The errno.h include file defines the macros EDOM and ERANGE, and a modifiable
lvalue having type int called errno. It also defines the global variable
_doserrno, which is determined by the OS/2 error code when an operating system
error occurs.

See Runtime Return Codes and Messages for a list of the runtime error messages
and the errno values associated with each message.

Note:  If you are going to test the value of errno after library function
calls, first set it to 0, because its value may not be reset during the call.

The definitions of errno and _doserrno are also provided in stdlib.h.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Runtime Return Codes and Messages
o stdlib.h
o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.7. fcntl.h ΓòÉΓòÉΓòÉ

The fcntl.h contains definitions for constants used by the _open and _sopen
functions. Definitions for these two functions are included in io.h. Additional
definitions for _sopen are provided in share.h.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o io.h
o share.h
o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.8. float.h ΓòÉΓòÉΓòÉ

The float.h include file contains definitions of constants that specify the
ranges of floating-point data types, for example, the maximum number of digits
for objects of type double or the minimum exponent for objects of type float.
In extended mode, float.h also defines the macros that represent infinity and
NaN (not-a-number) values, and contains the definitions for the following
functions that manipulate the floating-point control and status words, and for
the constants that they use:

_clear87            _control87
_fpreset            _status87


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Infinity and NaN Support
o Floating-Point Variables
o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.9. io.h ΓòÉΓòÉΓòÉ

The io.h include file contains definitions for the following file handle and
low-level input and output functions:

_access             _chmod
_chsize             _close
_creat              _dup
_dup2               __eof
_filelength         _isatty
_lseek              _open
_read               remove
rename              _setmode
_sopen              _tell
_umask              _unlink
_write

Two additional functions, _fstat and _stat, are defined in sys\stat.

Constants required by the _open and _sopen functions are provided in fcntl.h.
Additional constants used by _sopen are defined in share.h.

The _unlink function is also defined in stdio.h.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fcntl.h
o share.h
o sys\stat.h
o stdlib.h
o conio.h
o stdio.h
o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.10. limits.h ΓòÉΓòÉΓòÉ

The limits.h include file contains definitions of constants that specify the
ranges of integer and character data types, such as the maximum value for an
object of type char.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Characters
o Integers
o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.11. locale.h ΓòÉΓòÉΓòÉ

The locale.h include file contains declarations for the setlocale and
localeconv library functions. These functions are useful for changing the C
locale when you are creating applications for international markets.

locale.h also contains the declaration for the type struct lconv and the
following macro definitions:

NULL                LC_ALL
LC_COLLATE          LC_CTYPE
LC_MONETARY         LC_NUMERIC
LC_TIME             LC_C_TOD
LC_C                LC_C_FRANCE
LC_C_GERMANY        LC_C_ITALY
LC_C_JAPAN          LC_C_SPAIN
LC_C_UK             LC_C_USA

NULL is also defined in stddef.h on page stddef.h, stdio.h on page stdio.h,
stdlib.h on page stdlib.h, string.h on page string.h, time.h on page time.h,
and wcstr.h on page wcstr.h.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.12. malloc.h ΓòÉΓòÉΓòÉ

The malloc.h include file contains definitions for the following memory
allocation functions:

_alloca             calloc
_debug_calloc       _debug_free
_debug_malloc       _debug_heapmin
_debug_realloc      _dump_allocated
free                _heap_check
malloc              &mszize.
realloc

It also includes a definition for the type size_t.

The SAA definitions of calloc, free, malloc, and realloc are provided in
stdlib.h, as are _alloca and _heapmin.

The _debug_calloc, _debug_free, _debug_malloc, _debug_heapmin, _debug_realloc,
_dump_allocated, and _heap_check functions are also defined as standard
extensions in stdlib.h.

Note:  To use these functions, you must also define the __DEBUG_ALLOC__ macro.
See Debug Memory Management Functions for more information about these
functions.

The _tcalloc, _tfree, _tmalloc, _trealloc functions are also defined as
standard extensions in stdlib.h.

Note:

 1. To use these functions, you must also define the __TILED__ macro. See Tiled
    Memory Management Functions for more information about these functions.

 2. If you define __DEBUG_ALLOC__ and __TILED__ at the same time, the tiled
    memory functions are provided, and the debug memory features are disabled.

The malloc.h include file also defines a number of far and near pointer macros
to the corresponding SAA or standard library function. These macros are:

_fcalloc            _ffree
_fheapmin           _fmalloc
_frealloc           _ncalloc
_nfree              _nheapmin
_nmalloc            _nrealloc

These macros are also defined in stdlib.h.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o stdlib.h
o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.13. math.h ΓòÉΓòÉΓòÉ

The math.h include file contains function declarations for all the
floating-point math functions:

acos                asin
atan                atan2
bessel              ceil
cos                 cosh
erf                 erfc
exp                 fabs
floor               fmod
frexp               gamma
hypot               ldexp
log                 log10
modf                pow
sin                 sinh
sqrt                tan
tanh

Note:  bessel does not correspond to a single function but to the functions
       named _j0, _j1, _jn, _y0, _y1, and _yn.

The math.h file also includes definitions for the following C/C++ Tools
extensions:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé _atold          Γöé _cabs           Γöé _matherr         Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

The _atold function is also defined in stdlib.h.

The math.h include file defines the macros HUGE, _LHUGE, HUGE_VAL, and
_LHUGE_VAL, which expand to a positive double expression or to infinity.

You can define a macro _FP_INLINE to inline the functions sin, cos, tan, atan,
acos and asin. If you use _FP_INLINE to inline the functions, you cannot use
the functions defined in complex.h, or an error message is generated.

For all mathematical functions, a domain error occurs when an input argument is
outside the range of values allowed for that function.  In the event of a
domain error, errno is set to the value of EDOM.

A range error occurs if the result of the function cannot be represented in a
double value.  If the magnitude of the result is too large (overflow), the
function returns the positive or negative value of the macro HUGE_VAL, and sets
errno to ERANGE.  If the result is too small (underflow), the function returns
zero.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o stdlib.h
o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.14. memory.h ΓòÉΓòÉΓòÉ

The memory.h include file contains definitions for the following buffer
manipulation functions:

memccpy             memchr
memcmp              memcpy
memicmp             memmove
memset

The SAA definitions of these functions are provided in string.h.

The memory.h include file also defines a number of far and near pointer macros
to the corresponding SAA or standard library function.  These macros are:

_fmemccpy           _fmemchr
_fmemcmp            _fmemcpy
_fmemicmp           _fmemset

These macros are also defined in string.h.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o string.h
o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.15. process.h ΓòÉΓòÉΓòÉ

The process.h include file contains definitions for the process control
functions:

abort               _beginthread
_cwait              _endthread
_execl              _execle
_execlp             _execlpe
_execv              _execve
_execvp             _execvpe
exit                _exit
_getpid             _spawnl
_spawnle            _spawnlp
_spawnlpe           _spawnv
_spawnve            _spawnvp
_spawnvpe           system
_wait

The definitions of _beginthread and _endthread are also provided in stdlib.h,
as are SAA definitions of abort, exit, and system.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o stdlib.h
o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.16. search.h ΓòÉΓòÉΓòÉ

The search.h include file contains the definitions for the following search
functions:

bsearch             _lfind
_lsearch            qsort

It also defines the type size_t.

The SAA definitions for bsearch and qsort are provided in stdlib.h.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o stdlib.h
o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.17. setjmp.h ΓòÉΓòÉΓòÉ

The setjmp.h include file contains function declarations for the setjmp macro
and longjmp function.  It also defines a buffer type, jmp_buf, that the setjmp
macro and longjmp function use to save and restore the program state.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.18. share.h ΓòÉΓòÉΓòÉ

The share.h include file defines constants used by the following functions:

_creat              _fdopen
_open               _sopen

The definitions for the above functions are included in io.h. Additional
constants for _open and _sopen are provided in fcntl.h.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o fcntl.h
o io.h
o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.19. signal.h ΓòÉΓòÉΓòÉ

The signal.h include file defines the values for signals.  The signal and raise
functions are declared in signal.h.

signal.h also defines the following macros:

SIG_DFL             SIGILL
SIG_ERR             SIGINT
SIG_IGN             SIGSEGV
SIGABRT             SIGTERM
SIGFPE              SIGUSR1
SIGUSR2             SIGUSR3
signal.h also defines the type sig_atomic_t.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.20. stdarg.h ΓòÉΓòÉΓòÉ

The stdarg.h include file defines macros that allow you access to arguments in
functions with variable-length argument lists.  The macros are: va_arg,
va_start, and va_end. stdarg.h also defines the type va_list.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.21. stddef.h ΓòÉΓòÉΓòÉ

The stddef.h include file contains definitions of the commonly used pointers,
variables, and types, from typedef statements, as listed below:

ptrdiff_t        typedef for the type of the difference of two pointers
size_t           typedef for the type of the value returned by sizeof
wchar_t          typedef for a wide character constant.

stddef.h also defines the macros NULL and offsetof. NULL is a pointer that is
guaranteed not to point to a data object. NULL is also defined in locale.h. The
offsetof macro expands to the number of bytes between a structure member and
the start of the structure.  The offsetof macro has the form:

   offsetof(structure_type, member)

stddef.h also contains definitions of the global variables errno and _threadid.

The extended definition of errno is also included in stdlib.h, while the SAA
version is in errno.h.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o errno.h
o stdlib.h
o stdio.h
o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.22. stdio.h ΓòÉΓòÉΓòÉ

The stdio.h include file contains definitions of constants, macros, and types,
along with function declarations for stream input and output functions. The
stream I/O functions are:

clearerr            fclose
feof                ferror
fflush              fgetc
fgetpos             fgets
fopen               fprintf
fputc               fputs
fread               freopen
fscanf              fseek
fsetpos             ftell
fwrite              getc
getchar             gets
perror              printf
putc                putchar
puts                remove
rename              rewind
scanf               setbuf
setvbuf             sprintf
sscanf              tmpfile
tmpnam              ungetc
vfprintf            vprintf
vsprintf

In extended mode, stdio.h also contains definitions for the following
extensions:

_fcloseall          _fgetchar
_fileno             _flushall
_fputchar           _rmtmp
_set_crt_msg_handle _tempnam
_unlink

The _unlink function is also defined in io.h.

The stdio.h file also defines the macros listed below.  You can use these
constants in your programs, but you should not alter their values.

BUFSIZ
  Specifies the buffer size to be used by the setbuf library function when you
  are allocating buffers for stream I/O.  This value establishes the size of
  system-allocated buffers and is used with setbuf.
EOF
  The value returned by an I/O function when the end of the file (or in some
  cases, an error) is found.
FOPEN_MAX
  The number of files that can be opened simultaneously.
FILENAME_MAX
  The longest file name supported. If there is no reasonable limit,
  FILENAME_MAX will be the recommended size.
L_tmpnam
  The size of the longest temporary name that can be generated by the tmpnam
  function.
P_tmpdir
  Indicates the default directory to be used by the tempnam function.
TMP_MAX
  The minimum number of unique file names that can be generated by the tmpnam
  function.
NULL
  A pointer guaranteed not to point to a data object. NULL is also defined in
  locale.h.

The FILE structure type is defined in stdio.h.  Stream I/O functions use a
pointer to the FILE type to get access to a given stream.  The system uses the
information in the FILE structure to maintain the stream.  The C standard
streams stdin, stdout, and stderr are also defined in stdio.h.

The macros SEEK_CUR, SEEK_END, and SEEK_SET expand to integral constant
expressions and can be used as the third argument to fseek.

The macros _IOFBF, _IOLBF, and _IONBF expand to integral constant expressions
with distinct values suitable for use as the third argument to the setvbuf
function.

The type fpos_t is defined in stdio.h for use with fgetpos and fsetpos.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o stddef.h
o stdlib.h
o conio.h
o io.h
o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.23. stdlib.h ΓòÉΓòÉΓòÉ

The stdlib.h include file contains function declarations for the following
functions:

abort               abs
atexit              atof
atoi                atol
bsearch             calloc
div                 exit
free                getenv
labs                ldiv
malloc              mblen
mbstowcs            mbtowc
qsort               rand
realloc             srand
strtod              strtol
strtoul             system
wctomb              wcstombs

In extended mode, stdlib.h also contains definitions for the following standard
extensions:

_alloca             _atold
_beginthread        _debug_calloc
_debug_free         _debug_heapmin
_debug_malloc       _debug_realloc
_dump_allocated     _ecvt
_endthread          _exit
_fcvt               _freemod
_fullpath           _gcvt
_heapmin            _heap_check
_itoa               _loadmod
_lrotl              _lrotr
_ltoa               _makepath
max                 min
_onexit             __parmdwords
_putenv             _rotl
_rotr               _searchenv
_splitpath          strtold
_swab               _threadstore
_ultoa

Note:

 1. Note that you must also define the __DEBUG_ALLOC__ macro to use the
    _debug_calloc, _debug_free, _debug_malloc, _debug_realloc, _dump_allocated,
    _debug_heapmin, and _heap_check functions. For more information about these
    functions, see Debug Memory Management Functions.

 2. If you define __DEBUG_ALLOC__ and __TILED__ at the same time, the tiled
    memory functions are provided, and the debug memory features are disabled.

The stdlib.h file also contains definitions for the following macros:

split=yes.

NULL The NULL pointer value. The value of NULL is 0 when in extended mode;
  otherwise, its value is ((void*)0). NULL is also defined in locale.h.
EXIT_SUCCESS Expands to 0; used by the atexit function.
EXIT_FAILURE Expands to 8; used by the atexit function.
RAND_MAX Expands to an integer representing the largest number that the RAND
  function can return.
MB_CUR_MAX Expands to an integer representing the maximum number of bytes in a
  multibyte character for the current locale.

For more information on NULL and the types size_t and wchar_t, see stddef.h.

In extended mode, stdlib.h also defines the following global variables:

_doserrno           _environ
errno               onexit_t
_osmajor            _osminor
_osmode

The variable errno is also defined in stddef.h. The variable _doserrno and the
SAA definition of errno are provided in errno.h.

In addition, stdlib.h defines the following far and near pointer macros to the
corresponding standard library function:

_fcalloc            _ffree
_fmalloc            _fheapmin
_frealloc           _ncalloc
_nfree              _nmalloc
_nheapmin           _nrealloc

These macros are also defined in malloc.h.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o errno.h
o malloc.h
o stddef.h
o stdio.h
o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.24. string.h ΓòÉΓòÉΓòÉ

The string.h include file declares the string manipulation functions:

memchr              memcmp
memcpy              memmove
memset              strcat
strchr              strcmp
strcoll             strcpy
strcspn             strerror
strlen              strncat
strncmp             strncpy
strpbrk             strrchr
strspn              strstr
strtok              strxfrm

In extended mode, string.h also contains definitions for the following standard
extensions:

memccpy             memicmp
strcmpi             strdup
_strerror           stricmp
strlwr              strnicmp
strnset             strrev
strset              strupr

The memxxxx functions are also included in memory.h.

The string.h include file also defines the macro NULL and the type size_t.
These definitions are also provided in stddef.h. NULL is also defined in
locale.h.

string.h also defines the following far  and near pointer macros to the
corresponding standard library function:

_fmemccpy           _fmemchr
_fmemcmp            _fmemcpy
_fmemicmp           _fmemmove
_fmemset            _fstrcat
_fstrchr            _fstrcmp
_fstrcpy            _fstrcspn
_fstrdup            _fstricmp
_fstrlen            _fstrlwr
_fstrncat           _fstrncmp
_fstrncpy           _fstrnicmp
_fstrnset           _fstrpbrk
_fstrrchr           _fstrrev
_fstrset            _fstrspn
_fstrstr            _fstrtok
_fstrupr            _nstrdup

These macros are also defined in memory.h.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o stddef.h
o memory.h
o stdlib.h
o stdio.h
o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.25. sys\stat.h ΓòÉΓòÉΓòÉ

The sys\stat.h include file contains the definitions for the low-level
input/output functions _fstat and _stat. It also defines the structure stat and
the following types:

dev_t               ino_t
off_t               time_t

These types are also defined in sys\types.h.

Other low-level I/O functions are defined in io.h.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o io.h
o sys\types.h
o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.26. sys\timeb.h ΓòÉΓòÉΓòÉ

The sys\timeb.h include file contains the definition for the _ftime function
and also defines the type time_t and the structure timeb.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.27. sys\types.h ΓòÉΓòÉΓòÉ

The sys\types.h include file contains the definitions for the following types:

ino_t               time_t
dev_t               off_t

These types are also defined in sys\stat.h.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o sys\stat.h
o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.28. sys\utime.h ΓòÉΓòÉΓòÉ

The sys\utime.h include file contains the definitions for the _utime function,
the structure utimbuf, and the type time_t.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.29. time.h ΓòÉΓòÉΓòÉ

The time.h include file declares the time and date functions:

asctime             clock
ctime               difftime
gmtime              localtime
mktime              strftime
time

In extended mode, time.h also includes the definition for the standard
extensions _strdate, _strtime, and _tzset.

The time.h include file also provides:

o A structure tm containing the components of a calendar time.  See gmtime  -
  Convert Time for a list of the members of the tm structure.

o A macro CLOCKS_PER_SEC equal to the number per second of the value returned
  by the clock function.

o Types clock_t, time_t, and size_t.

o The NULL pointer value.

For more information on NULL and the type size_t, see stddef.h.

time.h also defines the global variables _daylight, _timezone, and _tzname.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o stddef.h
o Include Files
o #include


ΓòÉΓòÉΓòÉ 7.30. wcstr.h ΓòÉΓòÉΓòÉ

The wcstr.h include file declares the multibyte functions:

wcscat              wcschr
wcscmp              wcscpy
wcscspn             wcslen
wcsncat             wcsncmp
wcsncpy             wcspbrk
wcsspn              wcsrchr
wcswcs
wcstr.h also defines the types size_t, NULL, and wchar_t.


ΓòÉΓòÉΓòÉ <hidden> Related Information ΓòÉΓòÉΓòÉ

o Include Files
o #include