path: root/.vim/doc/crefvim.txt

*crefvim.txt*            C-Reference Manual for Vim 
                               Vim version 6.0


                                                       *crefvim* *C-Reference*
                              C-Reference for Vim
                            ======================
                                Version 1.0.3
                                27. Nov. 2004

                     (c) 2002-2004 by Christian Habermann
                   christian (at) habermann-net (point) de


                   "The GNU C Library Reference Manual" is
                       copyright (c) 1993 - 2002 by the
                        Free Software Foundation, Inc.


       See |crefvimdoc| for further information on the project CRefVim.
       See |crvdoc-copyright| for copyright and licenses.


      Table of  C o n t e n t s:

                       Introduction..................|crv-intro|
                      
          Chapter  I   LANGUAGE......................|crv-language|
                   I.1   Characters..................|crv-lngChar|
                   I.1.1   Allowed Characters........|crv-lngAllowedChar|
                   I.1.2   Comment...................|crv-lngComment|
                   I.1.3   Escape-Sequences..........|crv-lngEscSeq|
                  
                   I.2   Keywords....................|crv-keywords|
                   
                   I.3   Operators...................|crv-operators|
                   I.3.1   Overview..................|crv-opOverview|
                   I.3.2   Arithmetic................|crv-opArithmetic|
                   I.3.3   Logical...................|crv-opLogical|
                   I.3.4   Relational................|crv-opRelational|
                   I.3.5   Bitwise...................|crv-opBitwise|
                   I.3.6   Assignments...............|crv-opAssigns|
                   I.3.7   Others....................|crv-opOthers|
                   I.3.7.1   Size of.................|crv-opSizeOf|
                   I.3.7.2   Address of..............|crv-opAddress|
                   I.3.7.3   Contents of.............|crv-opContents| 
                   I.3.7.4   Conditional.............|crv-opConditional|
                   I.3.7.5   Series..................|crv-opSeries|
                   I.3.7.6   Type Cast...............|crv-opTypeCast| 
                   I.3.7.7   Struct/Union Selectors..|crv-opStructUnionSel| 
                   I.3.7.8   Array Selector..........|crv-opArraySel| 
                   I.3.7.9   Parentheses.............|crv-opParenth|
                   I.3.8   Precedence................|crv-opPrecedence|

                   I.4   Punctuators.................|crv-punctuators|
                   
                   I.5   Datatypes...................|crv-datatypes|
                   I.5.1   Overview..................|crv-dtOverview|
                   I.5.1.1   Type Specifiers.........|crv-dtTypeSpecifiers|
                   I.5.1.2   Type Grouping...........|crv-dtTypeGrouping|
                   I.5.2   Sizes and Ranges..........|crv-dtSizeRange|
                   I.5.2   Formats...................|crv-dtFormats|
                   I.5.2.1   Integer.................|crv-dtFormatsInt|
                   I.5.2.2   Floating-Point..........|crv-dtFormatsFloat|
                   I.5.2.2.1   Basics................|crv-dtFormatsFPBasics|
                   I.5.2.2.2   Types.................|crv-dtFormatsFPTypes|
                   I.5.3   void Type.................|crv-dtVoid|
                   I.5.4   Arrays....................|crv-dtArrays|
                   I.5.5   Structures................|crv-dtStructurs|
                   I.5.6   Unions....................|crv-dtUnions|
                   I.5.7   Bit-Fields................|crv-dtBitFields|
                   I.5.8   Enumerated Tags...........|crv-dtEnumerate|
                   I.5.9   Strings...................|crv-dtStrings|
                   I.5.10  Type Definitions..........|crv-dtTypeDef|
                   I.5.11  Storage Classes...........|crv-dtStorageClasses|
                   I.5.12  Qualifiers................|crv-dtQualifiers|
                   I.5.13  Pointers..................|crv-dtPointers|
                   I.5.13.1  Variables...............|crv-dtPtrVars|
                   I.5.13.2  Functions...............|crv-dtPtrFuncs|
                   I.5.13.3  Arithmetics.............|crv-dtPtrArithmetics|
                   I.5.14  Type Cast.................|crv-dtTypeCast|
                   I.5.14.1  Explicit................|crv-dtTypeCastExpl|
                   I.5.14.2  Implicit................|crv-dtTypeCastImpl|
                   I.5.15  Constants.................|crv-dtConstants|
                   I.5.15.1  Integer.................|crv-dtConstInt|
                   I.5.15.2  Floating-Point..........|crv-dtConstFloat|
                   I.5.15.3  Character...............|crv-dtConstChar|
                   
                   I.6   Statements..................|crv-statements|
                   I.6.1   if-else...................|crv-stIfElse|
                   I.6.2   switch....................|crv-stSwitch|
                   I.6.3   while Loop................|crv-stWhile|
                   I.6.4   do-while Loop.............|crv-stDoWhile|
                   I.6.5   for Loop..................|crv-stFor|
                   I.6.6   break.....................|crv-stBreak|
                   I.6.7   continue..................|crv-stContinue|
                   I.6.8   goto......................|crv-stGoto|
                   I.6.9   return....................|crv-stReturn|
                   I.6.10  Null Statement............|crv-stNull|
                   
                   I.7   Functions...................|crv-functions|
                   I.7.1   Definition................|crv-fuDefinition|
                   I.7.2   Protoype..................|crv-fuPrototype|
                   I.7.3   Conversion................|crv-fuConversion|
                   I.7.4   Storage Classes...........|crv-fuStorageClasses|
                   I.7.5   Specifier.................|crv-fuSpecifier|
                   I.7.6   main()....................|crv-fuMain|

                   I.8   Preprocessor................|crv-preprocessor|
                   I.8.1   Macros....................|crv-preMacros|
                   I.8.1.1   Definition #define......|crv-preMacDef|
                   I.8.1.2   Cancellation #undef.....|crv-preMacCancel|
                   I.8.1.3   # Operator..............|crv-preMac#Operator|
                   I.8.1.4   ## Operator.............|crv-preMac##Operator|
                   I.8.1.5   Predefined Macros.......|crv-preMacPredefined|
                   I.8.2   Conditional Compilation...|crv-preConditional|
                   I.8.2.1   defined Operator........|crv-preCondDefined|
                   I.8.2.2   #if Directive...........|crv-preCondIf|
                   I.8.2.3   #ifdef Directive........|crv-preCondIfdef|
                   I.8.2.4   #ifndef Directive.......|crv-preCondIfndef|
                   I.8.2.5   #else Directive.........|crv-preCondElse|
                   I.8.2.6   #elif Directive.........|crv-preCondElif|
                   I.8.2.7   #endif Directive........|crv-preCondEndif|
                   I.8.3   File Inclusion #include...|crv-preSourceInc|
                   I.8.4   Line Control #line........|crv-preLine|
                   I.8.5   Error Directive #error....|crv-preError|
                   I.8.6   Pragma Directive #pragma..|crv-prePragma|
                   I.8.7   Null Directive #..........|crv-preNull|
                   

          Chapter II   STANDARD C LIBRARY............|crv-stdCLib|
                  II.1   Standard Headers............|crv-libHeaders|
                  
                  II.2   <assert.h> Diagnostics......|crv-libAssertH|
                  
                  II.3   <complex.h> Complex Math....|crv-libComplexH|
                  II.3.1   Macros....................|crv-libCHMac|
                  II.3.2   Pragmas...................|crv-libCHPrag|
                  II.3.3   Trigonometric.............|crv-libCHTrig|
                  II.3.4   Hyperbolic................|crv-libCHHyper|
                  II.3.5   Exponential & Logarithmic.|crv-libCHExpLog|
                  II.3.6   Power & Absolute..........|crv-libCHPower|
                  II.3.7   Manipulating..............|crv-libCHMani|
                  
                  II.4   <ctype.h> Character.........|crv-libCtypeH|
                  II.4.1   Character Handling........|crv-libCharHandling|
                  II.4.2   Character Mapping.........|crv-libCharMapping|
                  
                  II.5   <errno.h> Error Codes.......|crv-libErrnoH|
                  
                  II.6   <fenv.h> FPU Status.........|crv-libFenvH|
                  II.6.1   Pragmas...................|crv-libFHPrag|
                  II.6.2   Exceptions................|crv-libFHExceptions|
                  II.6.3   Rounding..................|crv-libFHRounding|
                  II.6.4   Environment...............|crv-libFHEnv|

                  II.7   <float.h> Floating Point....|crv-libFloatH|
                  
                  II.8   <inttypes.h> Absolute Value.|crv-libInttypesH|
                  
                  II.9   <iso646.h> Alternatives.....|crv-libIso646H|

                  II.10  <limits.h> Limits of Int....|crv-libLimitsH|
                  II.10.1  Range of Integer Types....|crv-libLHRange|
                  II.10.2  Width of Type.............|crv-libLHWidth|
                  II.10.3  Conversion and Properties.|crv-libLHConv|

                  II.11  <local.h> Localization......|crv-libLocalH|
                  II.11.1  Categories................|crv-libLocHCat|
                  II.11.2  Standard Locales..........|crv-libLocHLoc|
                  II.11.3  Information Structure.....|crv-libLocHInfo|
                  II.11.4  Functions.................|crv-libLocHFunc|

                  II.12  <math.h> Mathematics........|crv-libMathH|
                  II.12.1  Error Conditions..........|crv-libMHErr|
                  II.12.2  Classification Macros.....|crv-libMHClass|
                  II.12.3  Comparison Macros.........|crv-libMHCmp|
                  II.12.4  Trigonometric.............|crv-libMHTrig|
                  II.12.5  Hyperbolic................|crv-libMHHyper|
                  II.12.6  Exponential & Logarithmic.|crv-libMHExpLog|
                  II.12.7  Power & Absolute..........|crv-libMHPower|
                  II.12.8  Error & Gamma.............|crv-libMHErrGam|
                  II.12.9  Nearest Integer...........|crv-libMHNear|
                  II.12.10 Remainder.................|crv-libMHRem|
                  II.12.11 Manipulating..............|crv-libMHMani|
                  II.12.12 Miscellaneous.............|crv-libMHMisc|

                  II.13  <setjmp.h> Nonlocal Jumps...|crv-libSetjmpH|
                  
                  II.14  <signal.h> Signal Handling..|crv-libSignalH|
                  II.14.1  Types.....................|crv-libSHTyp|
                  II.14.2  Signals...................|crv-libSHSig|
                  II.14.3  Functions.................|crv-libSHFunc|
                  
                  II.15  <stdarg.h> Arguments........|crv-libStdargH|
                  
                  II.16  <stdbool.h> Boolean Type....|crv-libStdboolH|

                  II.17  <stddef.h> Definitions......|crv-libStddefH|

                  II.18  <stdint.h> Integer Type.....|crv-libStdintH|
                  II.18.1  Integer Types.............|crv-libSdHType|
                  II.18.1.1  Exact-Width.............|crv-libSdHTExact|
                  II.18.1.2  Minimum-Width...........|crv-libSdHTMin|
                  II.18.1.3  Fastest Minimum-Width...|crv-libSdHTFast|
                  II.18.1.4  Greatest-Width..........|crv-libSdHTGreat|
                  II.18.1.5  Hold Pointer............|crv-libSdHTPtr|
                  II.18.2  Limits....................|crv-libSdHTLim|
                  II.18.2.1  Exact-Width.............|crv-libSdHLExact|
                  II.18.2.2  Minimum-Width...........|crv-libSdHLMin|
                  II.18.2.3  Fastest Minimum-Width...|crv-libSdHLFast|
                  II.18.2.4  Greatest-Width..........|crv-libSdHLGreat|
                  II.18.2.5  Others..................|crv-libSdHLOther|
                  II.18.2.6  Hold Pointer............|crv-libSdHLPtr|
                  II.18.3  Macros....................|crv-libSdHMac|

                  II.19  <stdio.h> Input/Output......|crv-libStdioH|
                  II.19.1  Types.....................|crv-libSIOHType|
                  II.19.2  Macros....................|crv-libSIOHMac|
                  II.19.3  Streams and Files.........|crv-libSIOHStrmFile|
                  II.19.4  File Operations...........|crv-libSIOHFOp|
                  II.19.5  File Access...............|crv-libSIOHFAcc|
                  II.19.6  Formatted Input/Output....|crv-libSIOHIO|
                  II.19.6.1  Format Control..........|crv-libSIOHIOFormat|
                  II.19.6.1.1  Output, printf()......|crv-libSIOHIOFout|
                  II.19.6.1.2  Input, scanf()........|crv-libSIOHIOFin|
                  II.19.6.2  Functions...............|crv-libSIOHIOFunc|
                  II.19.7  Character Input/Output....|crv-libSIOHCIO|
                  II.19.8  Direct Input/Output.......|crv-libSIOHDIO|
                  II.19.9  File Positioning..........|crv-libSIOHFPos|
                  II.19.10 Error Handling............|crv-libSIOHErr|

                  II.20  <stdlib.h> Utilities........|crv-libStdlibH|
                  II.20.1  Types.....................|crv-libSLHType|
                  II.20.2  Macros....................|crv-libSLHMac|
                  II.20.3  Numeric Conversion........|crv-libSLHnum|
                  II.20.4  Pseudo-Random.............|crv-libSLHrand|
                  II.20.5  Memory Management.........|crv-libSLHmem|
                  II.20.6  Communication.............|crv-libSLHcom|
                  II.20.7  Searching and Sorting.....|crv-libSLHsearch|
                  II.20.8  Integer Arithmetic........|crv-libSLHintarith|
                  II.20.9  Multibyte/Wide Character..|crv-libSLHmulchar|
                  II.20.10 Multibyte/Wide String.....|crv-libSLHmulstrng|

                  II.21  <string.h> String...........|crv-libStringH|
                  II.21.1  Types.....................|crv-libSRHType|
                  II.21.2  Macros....................|crv-libSRHMac|
                  II.21.3  Copying...................|crv-libSRHCopy|
                  II.21.4  Concatenation.............|crv-libSRHConcat|
                  II.21.5  Comparison................|crv-libSRHCmp|
                  II.21.6  Search....................|crv-libSRHSearch|
                  II.21.7  Miscellaneous.............|crv-libSRHMisc|

                  II.22  <tgmath.h> Type-Generic.....|crv-libTgmathH|
                  
                  II.23  <time.h> Date and Time......|crv-libTimeH|
                  II.23.1  Types.....................|crv-libTHType|
                  II.23.2  Macros....................|crv-libTHMac|
                  II.23.3  Time Manipulation.........|crv-libTHMani|
                  II.23.4  Time Conversion...........|crv-libTHConv|

                  II.24  <wchar.h> Wide Utilities....|crv-libWcharH|
                  II.24.1  Types.....................|crv-libWCHType|
                  II.24.2  Macros....................|crv-libWCHMac|
                  II.24.3  Formatted Input/Output....|crv-libWCHIO|
                  II.24.4  Character Input/Output....|crv-libWCHCIO|
                  II.24.5  String Utilities..........|crv-libWCHStrng|
                  II.24.5.1  Numeric Conversions.....|crv-libWCHNum|
                  II.24.5.2  Copying.................|crv-libWCHCopy|
                  II.24.5.3  Concatenation...........|crv-libWCHConcat|
                  II.24.5.4  Comparison..............|crv-libWCHCmp|
                  II.24.5.5  Search..................|crv-libWCHSearch|
                  II.24.5.6  Miscellaneous...........|crv-libWCHMisc|
                  II.24.6  Time Conversions..........|crv-libWCHTimeConv|
                  II.24.7  Character Conversions.....|crv-libWCHCharConv|
                  
                  II.25  <wctype.h> Wide Character...|crv-libWctypeH|
                  II.25.1  Types.....................|crv-libWTHType|
                  II.25.2  Macros....................|crv-libWTHMac|
                  II.25.3  Classification............|crv-libWTHClass|
                  II.25.3.1  Wide Character..........|crv-libWTHCwide|
                  II.25.3.2  Extensible Wide Char....|crv-libWTHCextens|
                  II.25.4  Mapping...................|crv-libWTHMap|
                  II.25.4.1  Wide Character..........|crv-libWTHMwide|
                  II.25.4.2  Extensible Wide Char....|crv-libWTHMextens|


          Appendix A   GLOSSARY............................|crv-glossary|
                   B   BIBLIOGRAPHY........................|crv-bibliography|
                   C   COPYRIGHT & LICENSES................|crvdoc-copyright|
                   C.1   GNU General Public License........|crvdoc-licGPL|
                   C.2   GNU Free Documentation License....|crvdoc-licFDL|
                   C.3   GNU Lesser General Public License.|crvdoc-licLGPL|
                   C.4   Free Software Needs Free
                         Documentation.....................|crvdoc-licFreeDoc|
                   D   AUTHOR..............................|crvdoc-author|
                   E   CREDITS.............................|crvdoc-credits|
                   F   HISTORY.............................|crvdoc-history|


Happy viming...


==============================================================================
Introduction                                                       *crv-intro*
==============================================================================


This document is a C-reference manual. It is NOT a tutorial on how to write
C programs. It is simply a quick reference to the standard C programming 
language and its standard library functions.
The language description is based on the standard ISO/IEC 9899:1999(E), second
edition. But this reference does not contain all information from this
standard, it tries to reflect only the most important information.

DISCLAIMER: All efforts have been taken to make sure that all information
            in this document is correct, but no guarantee is implied or 
            intended.

This C-reference manual is designed to be best viewed with Vim and syntax-
highlighting enabled. Furthermore when using Vim it's possible to navigate 
through this document by tags. Vim is a very powerful text-editor available
for close to all platforms. 

This C-reference is divided into two chapters and an appendix. The first
chapter deals mainly with the language. The second chapter shows the
functions of the standard C library. The appendix includes a glossary and
other items of interest. 





==============================================================================
Chapter I  LANGUAGE                                             *crv-language*
==============================================================================



==============================================================================
I.1  Characters                                                  *crv-lngChar*


------------------------------------------------------------------------------
I.1.1  Allowed Characters                                 *crv-lngAllowedChar*

In a C source code the following characters are allowed:

  Digits:     0...9
  Letters:    a-z A-Z
  Others:     ! " # & ' + - * / % , . : ; < = > ? \ ^ _ | ~ 
              parentheses ( )
              brackets    [ ]
              braces      { }
              space, tabulator, form feed

  Trigraphs:  ??=  #     ??)  ]     ??!  |                      *crv-trigraph*
              ??(  [     ??'  ^     ??>  }
              ??/  \     ??<  {     ??-  ~ 
              If a trigraph sequence is found in the source code it is 
              replaced with the corresponding single character. This allows
              to enter some special symbols on platforms not providing these
              symbols.


------------------------------------------------------------------------------
I.1.2  Comment                                                *crv-lngComment*

There are two types of comments:
  - block comment $/*...*/$
  - line comment $//$

Block Comment:                                           *crv-lngBlockComment*
  A block comment starts with $/*$ and ends with $*/$. All characters between
  start and end are treated as comment. Nesting is not allowed.
  
Line Comment:                                             *crv-lngLineComment*
  A line comment starts with $//$ and ends at the next new-line character 
  (new-line character is not included).



------------------------------------------------------------------------------
I.1.3  Escape-Sequences                                        *crv-lngEscSeq*


 Escape Sequence |       Name      |      Meaning
 ----------------+-----------------+------------------------------------------
      \'         |                 | single quote '
      \"         |                 | double quote "
      \?         |                 | question mark ?
      \\         |                 | backslash \
                 |                 |
      \a         | Alert           | produces an audible or visible alert
      \b         | Backspace       | moves cursor back one position
      \f         | Form Feed       | moves cursor to start of next page
      \n         | New Line        | moves cursor to start of next line
      \r         | Carriage Return | moves cursor to start of current line
      \t         | horiz. tabulator| moves cursor to next horiz. tab. position
      \v         | vert. tabulator | moves cursor to next vert. tab. position
                 |                 |
 \0octal-digits  |                 | octal character
 \xhex-digits    |                 | hexadecimal character
                 |                 |
      \0         | null character  | character with the value 0
                 |                 |
      \<cr>      |                 | concatenates actual line with next one 
                 |                 | (backslash immediately followed by a 
                 |                 | new-line)



==============================================================================
I.2  Keywords                                                   *crv-keywords*

Keywords are words with a special meaning in C. They must not be used for any 
other purposes. Keywords are case sensitive.


   Keyword      |  Description
 ---------------+----------------------------
  $ auto       $|   storage-class specifier
  $ break      $|   statement
  $ case       $|   label
  $ char       $|   type
  $ const      $|   type qualifier
  $ continue   $|   statement
  $ default    $|   label
  $ do         $|   statement
  $ double     $|   type
  $ else       $|   statement
  $ enum       $|   type
  $ extern     $|   storage-class specifier
  $ float      $|   type
  $ for        $|   statement
  $ goto       $|   statement
  $ if         $|   statement
  $ inline     $|   function specifier
  $ int        $|   type
  $ long       $|   type
  $ register   $|   storage-class specifier
  $ restrict   $|   type qualifier
  $ return     $|   statement
  $ short      $|   type
  $ signed     $|   type
  $ sizeof     $|   operator
  $ static     $|   storage-class specifier
  $ struct     $|   specifier
  $ switch     $|   statement
  $ typedef    $|   declaration
  $ union      $|   specifier
  $ unsigned   $|   type
  $ void       $|   type
  $ volatile   $|   type qualifier
  $ while      $|   statement
  $ _Bool      $|   type
  $ _Complex   $|   type
  $ _Imaginary $|   type




==============================================================================
I.3  Operators                                                 *crv-operators*


------------------------------------------------------------------------------
I.3.1  Overview                                               *crv-opOverview*


  Operator     |  Usage          |   Description
 --------------+-----------------+-------------------------------------------
               |                 |
                                                            |crv-opArithmetic|
Arithmetic~
$ +$[unary]    |$+operand       $| positive sign, same like$operand$
$ -$[unary]    |$-operand       $| negation of$operand$
               |                 |
$ +$[binary]   |$expr1 + expr2  $| addition
$ -$[binary]   |$expr1 - expr2  $| substraction
$ / $          |$expr1 / expr2  $| division
$ * $          |$expr1 * expr2  $| multiplication
$ % $          |$expr1 % expr2  $| modulo
$ --$[postfix] |$operand--      $|$operand$before decrementing by 1
$ --$[prefix]  |$--operand      $|$operand$after decrementing by 1
$ ++$[postfix] |$operand++      $|$operand$before incrementing by 1
$ ++$[prefix]  |$++operand      $|$operand$after incrementing by 1 
               |                 |
                                                               |crv-opLogical|
Logical~
$ && $         |$expr1 && expr2 $| logical AND
$ || $         |$expr1 || expr2 $| logical OR
$ !  $         |$!expr1         $| logical NOT
               |                 |
                                                            |crv-opRelational|
Relational~
$ ==$          |$expr1 == expr2 $| compare for equal
$ !=$          |$expr1 != expr2 $| compare for not equal
$ > $          |$expr1 >  expr2 $| compare for "greater than"
$ < $          |$expr1 <  expr2 $| compare for "less than"
$ >=$          |$expr1 >= expr2 $| compare for "greater than or equal"
$ <=$          |$expr1 <= expr2 $| compare for "less than or equal"
               |                 |
                                                               |crv-opBitwise|
Bitwise~
$ &  $         |$expr1 & expr2  $| bitwise AND
$ |  $         |$expr1 | expr2  $| bitwise OR
$ ^  $         |$expr1 ^ expr2  $| bitwise XOR
$ << $         |$expr1 << expr2 $| shift bits to left
$ >> $         |$expr1 >> expr2 $| shift bits to right
$ ~  $         |$~expr1         $| one's complement
               |                 |
                                                               |crv-opAssigns|
Assignment~
$ =  $         |$expr1  = expr2 $| assignment
$ *= $         |$expr1 *= expr2 $|$expr1 = expr1 * expr2 $
$ /= $         |$expr1 /= expr2 $|$expr1 = expr1 / expr2 $ 
$ %= $         |$expr1 %= expr2 $|$expr1 = expr1 % expr2 $ 
$ += $         |$expr1 += expr2 $|$expr1 = expr1 + expr2 $ 
$ -= $         |$expr1 -= expr2 $|$expr1 = expr1 - expr2 $ 
$ <<=$         |$expr1 <<= expr2$|$expr1 = expr1 << expr2 $ 
$ >>=$         |$expr1 >>= expr2$|$expr1 = expr1 >> expr2 $ 
$ &= $         |$expr1 &= expr2 $|$expr1 = expr1 & expr2 $ 
$ ^= $         |$expr1 ^= expr2 $|$expr1 = expr1 ^ expr2 $ 
$ |= $         |$expr1 |= expr2 $|$expr1 = expr1 | expr2 $ 
               |                 |
                                                                |crv-opOthers|
Others~
$ sizeof $     |$sizeof a       $| size of element$a$in bytes
$ &      $     |$&expr1         $| address of$expr1$
$ *     $      |$*expr1         $| contents of$expr1$, $expr1$is a pointer
$ ?:    $      |$a?expr1:expr2  $| conditional operator$a!=0:expr1 else expr2$
$ ,     $      |$expr1,expr2    $| comma operator
$(type-name)$  |$(float)expr1   $| explicit type cast
$ .     $      |$a.b            $| struct/union selector,$a$is struct/union
$ ->    $      |$a->b           $| struct/union selector,$a$is pointer to 
               |                 | struct/union
$ []    $      |$a[0]           $| array selector
$ ()    $      |$(a + b) * c    $| group operators or
               |$func()         $| declare functions
               |                 |
 --------------+-----------------+-------------------------------------------


The sections below give further information on operators.


------------------------------------------------------------------------------
I.3.2  Arithmetic                                           *crv-opArithmetic*

$+operand$                                                     *crv-opPosSign*
----------
positive sign

Examples: >
  a = +15;
  a = +b;
  func(3.12E+3);


$-operand$                                                     *crv-opNegSign*
----------
negative sign, negation

Examples: >
  a = -15;
  a = -a;


$expr1 + expr2$                                                    *crv-opAdd*
---------------
This adds the two expressions.

Examples: >
  a = b + c;
  a = b + 42;
  a = func(b + c);


$expr1 - expr2$                                                    *crv-opSub*
---------------
Substract$expr2$from$expr1$.

Examples: >
  a = b - c;
  a = b - 42;
  a = func(b - c);


$expr1 / expr2$                                                 *crv-opDivide*
---------------
Divide$expr1$by$expr2$.
If$expr2$is 0, behavior is undefined.

Examples: >
  a = b / c;
  a = b / 42;
  a = func(c / 3);


$expr1 * expr2$                                               *crv-opMultiply*
---------------
Multiply$expr1$by$expr2$.

Examples: >
  a = b * c;
  a = b * 42;
  a = func(c * 3);


$expr1 % expr2$                                                 *crv-opModulo*
---------------
Modulo operator. The result is the value of the remainder after
dividing$expr1$by$expr2$.
Both expressions must be integer types (char, short, int, long...,
signed or unsigned).
If$expr2$is 0, behavior is undefined.

Examples: >
  a = 0 % 3;         // result =  0
  a = 1 % 3;         // result =  1
  a = 2 % 3;         // result =  2
  a = 3 % 3;         // result =  0
  a = 4 % 3;         // result =  1
  a = 5 % 3;         // result =  2
  a = 6 % 3;         // result =  0
  a = 7 % 3;         // result =  1
  a = 7 % (-3);      // result =  1
  a = (-7) % 3;      // result = -1
  a = (-7) % (-3);   // result = -1

  a = b % c;
  func(a % c);


$operand--$                                                    *crv-opPostDec*
-----------
This is a postfix operation (unary operator after operand).
$operand$will be decremented by 1 AFTER the expression is
evaluated.
The value 1 of the appropriate type is subtracted.
So e.g. integer and float can be used as$operand$.

Example: >
  int   nA;
  float fA;
  
  nA = 3;
  printf("%d", nA--);   // output 3
  printf("%d", nA);     // output 2

  fA = 3.2f;
  fA--;
  printf("%f", fA);     // output 2.2


$--operand$                                                     *crv-opPreDec*
-----------
This is a prefix operation (unary operator before operand).
$operand$will be decremented by 1 BEFORE the expression is
evaluated.
The value 1 of the appropriate type is subtracted.
So e.g. integer and float can be used as$operand$.

Example: >
  int   nA;
  float fA;
  
  nA = 3;
  printf("%d", --nA);   // output 2
  printf("%d", nA);     // output 2
  
  fA = 3.2f;
  --fA;
  printf("%f", fA);     // output 2.2


$operand++$                                                    *crv-opPostInc*
-----------
This is a postfix operation (unary operator after operand).
$operand$will be incremented by 1 AFTER the expression is
evaluated.
The value 1 of the appropriate type is added. So e.g. 
integer and float can be used as$operand$.

Example: >
  int   nA;
  float fA;
  
  nA = 3;
  printf("%d", nA++);   // output 3
  printf("%d", nA);     // output 4
  
  fA = 3.2f;
  fA++;
  printf("%f", fA);     // output 4.2


$++operand$                                                       *crv-PreInc*
-----------
This is a prefix operation (unary operator before operand).
$operand$will be incremented by 1 BEFORE the expression is
evaluated.
The value 1 of the appropriate type is added. So e.g. 
integer and float can be used as$operand$.

Example: >
  int   nA;
  float fA;
  
  nA = 3;
  printf("%d", ++nA);   // output 4
  printf("%d", nA);     // output 4
  
  fA = 3.2f;
  ++fA;
  printf("%f", fA);     // output 4.2



------------------------------------------------------------------------------
I.3.3  Logical                                                 *crv-opLogical*

An expression is FALSE if its value is 0, else it is TRUE.

ATTENTION: This means TRUE is defined as unequal to 0. So never assume any
value for TRUE, TRUE's value depends on implementation.


$expr1 && expr2$                                                *crv-opLogAnd*
----------------
This is the logical AND.
The expression is TRUE if both$expr1$AND$expr2$are TRUE - else it is FALSE.
If$expr1$is equal 0,$expr2$is not evaluated.
The result has type$int$.

  $expr1$|$expr2$ || result
 --------+--------++--------
     0   |   0    ||   0
     0   |  >=1   ||   0
    >=1  |   0    ||   0
    >=1  |  >=1   ||  >=1


$expr1 || expr2$                                                 *crv-opLogOr*
----------------
This is the logical OR.
The expression is TRUE if either$expr1$OR$expr2$is TRUE - else it is FALSE.
If$expr1$is unequal 0,$expr2$is not evaluated.
The result has type$int$.

  $expr1$|$expr2$ || result
 --------+--------++--------
     0   |   0    ||   0
     0   |  >=1   ||  >=1
    >=1  |   0    ||  >=1
    >=1  |  >=1   ||  >=1


$!expr1$                                                        *crv-opLogNot*
--------
This is the logical NOT.
The expression is TRUE if$expr1$is FALSE. The expression is FALSE if$expr1$is 
TRUE.
The result has type$int$.

  $expr1$|| result
   ------++--------
     0   ||  >=1
    >=1  ||   0



------------------------------------------------------------------------------
I.3.4  Relational                                           *crv-opRelational*

$expr1 == expr2$                                              *crv-opRelEqual*
----------------
Equality operator. The result is 1 if operands are equal. The result is
0 if operands are unequal.
The result has type$int$.

Example: >
  int x, a, b;

  a = 1;
  b = 2;
  
  if (a == 1)
  {
    printf("a is equal to 1");
  }

  x = a == b;
  printf("%d", x);    // output is 0, since a != b

  
$expr1 != expr2$                                            *crv-opRelUnequal*
----------------
Unequality operator. The result is 1 if operands are unequal. The result is
0 if operands are equal.
The result has type$int$.

Example: >
  int x, a, b;

  a = 1;
  b = 2;
  
  if (a != b)
  {
    printf("a is unequal to b");
  }

  x = a != b;
  printf("%d", x);    // output is 1, since a != b


$expr1 > expr2$                                                  *crv-opRelGT*
---------------
"greater than" operator. The result is 1 if value of$expr1$is greater than
value of $expr2$, else result is 0.
The result has type$int$.

Example: >
  int x, a, b;

  a = 5;
  b = 2;
  
  if (a > b)
  {
    printf("a is greater than b");
  }

  x = a > b;
  printf("%d", x);    // output is 1, since a > b


$expr1 < expr2$                                                  *crv-opRelLT*
---------------
"less than" operator. The result is 1 if value of$expr1$is less than
value of$expr2$, else result is 0.
The result has type$int$.

Example: >
  int x, a, b;

  a = 1;
  b = 2;
  
  if (a < b)
  {
    printf("a is less than b");
  }

  x = a < b;
  printf("%d", x);    // output is 1, since a < b


$expr1 >= expr2$                                                *crv-opRelGTE*
----------------
"greater than or equal to" operator. The result is 1 if value of$expr1$is
greater than or equal to value of$expr2$, else result is 0.
The result has type$int$.

Example: >
  int x, a, b;

  a = 1;
  b = 1;
  
  if (a >= b)
  {
    printf("a is greater than or equal to b");
  }

  a = 1; b = 2;
  x = a >= b;
  printf("%d", x);    // output is 0, since a < b


$expr1 <= expr2$                                                *crv-opRelLTE*
----------------
"less than or equal to" operator. The result is 1 if value of$expr1$is
less than or equal to value of$expr2$, else result is 0.
The result has type$int$.

Example: >
  int x, a, b;

  a = 1;
  b = 2;
  
  if (a <= b)
  {
    printf("a is less than or equal to b");
  }

  x = a <= b;
  printf("%d", x);    // output is 1, since a <= b



------------------------------------------------------------------------------
I.3.5  Bitwise                                                 *crv-opBitwise*

$expr1 & expr2$                                                 *crv-opBitAnd*
---------------
Bitwise AND operator. This operator does a bitwise AND on the values
of$expr1$and$expr2$.
The result is a value the same size as the expressions.

     $expr1$ | $expr2$   ||  result
    n-th Bit | n-th Bit  || n-th Bit
   ----------+-----------++----------
        0    |     0     ||   0
        0    |     1     ||   0
        1    |     0     ||   0
        1    |     1     ||   1

Example: >
  int a, b;

  b = 0x81;
  a = b & 0xF0;  
                // value of a is: 0x80

 
$expr1 | expr2$                                                  *crv-opBitOr*
---------------
Bitwise OR operator. This operator does a bitwise OR on the values
of$expr1$and$expr2$.
The result is a value the same size as the expressions.

     $expr1$ | $expr2$   ||  result
    n-th Bit | n-th Bit  || n-th Bit
   ----------+-----------++----------
        0    |     0     ||   0
        0    |     1     ||   1
        1    |     0     ||   1
        1    |     1     ||   1

Example: >
  int a, b;

  b = 0x81;
  a = b | 0xF0;  
                // value of a is: 0xF1


$expr1 ^ expr2$                                                 *crv-opBitXor*
---------------
Bitwise XOR operator. This operator does a bitwise XOR on the values
of$expr1$and$expr2$.
The result is a value the same size as the expressions.

     $expr1$ | $expr2$   ||  result
    n-th Bit | n-th Bit  || n-th Bit
   ----------+-----------++----------
        0    |     0     ||   0
        0    |     1     ||   1
        1    |     0     ||   1
        1    |     1     ||   0

Example: >
  int a, b;

  b = 0x81;
  a = b ^ 0xF0;
                // value of a is: 0x71


$expr1 << expr2$                                          *crv-opBitLeftShift*
----------------
Bitwise left-shift operator. The result is$expr1$left-shifted$expr2$bit 
positions, vacated bits are filled with 0.

IF$expr1$is an unsigned type the value of the result is:
   $expr1$* 2^($expr2$) modulo (1 + maximum value representable in resulting
                                type)
ELSE
    IF$expr1$is a signed type and has a nonnegative value and
   $expr1$* 2^($expr2$) is representable in the result type then the
    result is:
       $expr1$* 2^($expr2$)
    ELSE
        behavior is undefined

Both expressions must be integer types (char, short, int, long...,
signed or unsigned).
The result has the type of$expr1$.
If the value of$expr2$is negative or is greater than or equal to the
width of$expr1$, the behavior is implementation specific.

Example: >
  int a, b, c;

  a = 3;
  b = 2;
  c = a << b;
                // value of c is 12


$expr1 >> expr2$                                         *crv-opBitRightShift*
----------------
Bitwise right-shift operator. The result is$expr1$right-shifted$expr2$
bit positions.

If$expr1$has an unsigned type or if$expr1$has a signed type and a nonnegative
value, the result is:
  $expr1$/ 2^($expr2$)

If$expr1$has a signed type and a negative value, the result is implementation
specific. Many compilers set vacated bits to 1.

Example: >
  int a, b, c;

  a = 17;
  b = 2;
  c = a >> b;
                // value of c is 4


$~expr1$                                                      *crv-opBitCompl*
--------
Bitwise one's complement. A bit in the result is set if the corresponding bit
in$expr1$is not set. A bit in the result is cleared if the corresponding bit
in$expr1$is set. 

The expression must has an integer type (char, short, int, long...,
signed or unsigned). The result has the type of$expr1$.

Example: >
  int a, b;

  a = 0xF0;
  b = ~a;
            // value of b is 0x0F



------------------------------------------------------------------------------
I.3.6  Assignments                                             *crv-opAssigns*


$expr1 = expr2$                                               *crv-opAsAssign*
---------------
The value of$expr2$is assigned to$expr1$.

Example: >
  int a, b;

  a = 2;
  b = 3;
  b = a * b;


$expr1 *= expr2$                                                 *crv-opAsMul*
----------------
Assign$expr1$the value of$expr1$multiplied by$expr2$.

Same as: $expr1 = expr1 * expr2$

see |crv-opMultiply|

Example: >
  int a, b;

  a = 2;
  b = 3;
  a *= b;
          // a has value 6


$expr1 /= expr2$                                                 *crv-opAsDiv*
----------------
Assign$expr1$the value of$expr1$divided by$expr2$.

Same as: $expr1 = expr1 / expr2$

see |crv-opDivide|

Example: >
  int a, b;

  a = 6;
  b = 3;
  a /= b;
          // a has value 2


$expr1 %= expr2$                                              *crv-opAsModulo*
----------------
Assign$expr1$the remainder after dividing$expr1$by$expr2$.

Same as: $expr1 = expr1 % expr2$

see |crv-opModulo|

Example: >
  int a, b;

  a = 6;
  b = 3;
  a %= b;
          // a has value 0


$expr1 += expr2$                                                 *crv-opAsAdd*
----------------
Assign$expr1$the value of the sum of$expr1$and$expr2$.

Same as: $expr1 = expr1 + expr2$ 

see |crv-opAdd|

Example: >
  int a, b;

  a = 6;
  b = 3;
  a += b;
          // a has value 9



$expr1 -= expr2$                                                 *crv-opAsSub*
----------------
Assign$expr1$the value of$expr2$substracted by$expr1$.

Same as: $expr1 = expr1 - expr2$ 

see |crv-opSub|

Example: >
  int a, b;

  a = 6;
  b = 4;
  a -= b;
          // a has value 2


$expr1 <<= expr2$                                          *crv-opAsLeftShift*
-----------------
Assign$expr1$the value of$expr1$left-shifted by$expr2$bit positions.

Same as: $expr1 = expr1 << expr2$ 

see |crv-opBitLeftShift|

Example: >
  int a, b;

  a = 6;
  b = 2;
  a <<= b;
          // a has value 24


$expr1 >>= expr2$                                          *op-opAsRightShift*
-----------------
Assign$expr1$the value of$expr1$right-shifted by$expr2$bit positions.

Same as: $expr1 = expr1 >> expr2$ 

see |crv-opBitRightShift|

Example: >
  int a, b;

  a = 6;
  b = 1;
  a >>= b;
          // a has value 3


$expr1 &= expr2$                                                  *opAsBitAnd*
----------------
Assign$expr1$the value of the bitwise AND of$expr1$and$expr2$.

Same as: $expr1 = expr1 & expr2$ 

see |crv-opBitAnd|

Example: >
  int a, b;

  a = 0x81;
  b = 0x0F;
  a &= b;
          // a has value 0x01


$expr1 ^= expr2$                                                  *opAsBitXor*
----------------
Assign$expr1$the value of the bitwise XOR of$expr1$and$expr2$.

Same as: $expr1 = expr1 ^ expr2$ 

see |crv-opBitXor|

Example: >
  int a, b;

  a = 0x81;
  b = 0x0F;
  a &= b;
          // a has value 0x01


$expr1 |= expr2$                                                   *opAsBitOr*
----------------
Assign$expr1$the value of the bitwise OR of$expr1$and$expr2$.

Same as: $expr1 = expr1 | expr2$ 

see |crv-opBitOr|

Example: >
  int a, b;

  a = 0x81;
  b = 0x0F;
  a |= b;
          // a has value 0x8F



------------------------------------------------------------------------------
I.3.7  Others                                                   *crv-opOthers*

I.3.7.1  Size of                                                *crv-opSizeOf*
----------------
Operator: $sizeof$                                                *crv-sizeof*
Declaration:
   $size_t sizeof expression$
  or
   $size_t sizeof (type-name)$

The$sizeof$operator yields the size of its operand (number of bytes).
The operand is either an expression or a name of a type. The name of type
must be in parenthesis.
The result has type$size_t$which is an unsigned integer type (unsigned int,
unsigned long,.... implementation specific).

The result for$char$,$unsigned char$,$signed char$or a typedef of them is 1.
For arrays the result is the total number of bytes used by the object.
For structures or unions the result is the total number of bytes in the
object including pad-bytes added by the compiler for alignment.

Examples: >
  char a[7];
  printf("%d", sizeof a );      // prints 7
  printf("%d", sizeof a[0] );   // prints 1

  printf("%d", sizeof(float) ); // prints 4

  --------
  
  struct Test {
    char  ch;
    float f;
  } tst;
  
  printf("%d", sizeof(tst) );         // print 8 (impl. specific)
  printf("%d", sizeof(struct Test) ); // print 8 (impl. specific)
 


I.3.7.2  Address of                                             *crv-opAddress*
-------------------
Syntax: $&operand$

The$&$operator returns the address of its operand. If the operand has type
"type" the result has type "pointer to type".

Operand can be:
  - a data type that is not register nor bit-fields
  - function designator
  - the result of$[]$operator
  - the result of$*$operator
 

Example: >
   int a, *ptr;
   
   a = 3;
   ptr = &a;    // assign address of a to prt

   printf("a: value = %d, address = %p", a, ptr);


I.3.7.3  Contents of                                           *crv-opContents*
--------------------
Syntax: $*operand$

The$*$operator refers to the value of the object a pointer points to.
The operand must be a pointer type.
If the operand has type "pointer to type" the result has type "type".

Example: >
   int a, b, *ptr;
   
   ptr  = &a;   // assign address of a to prt
   *ptr = 5     // set value of object ptr points to to 5 (object is a)
   b = *ptr;    // assign value of object pointer ptr points to to b
   

I.3.7.4  Conditional                                       *crv-opConditional*
--------------------
Syntax: $expr1 ? expr2 : expr3$
       
At first$expr1$is evaluated. If$expr1$is unequal 0,$expr2$is evaluated.
If$expr1$is equal 0,$expr3$is evaluated.

The result of the conditional operator is either the value of$expr2$or$expr3$,
whichever is evaluated. The type of the result is:
  - If$expr2$and$expr3$have the same type, the result has that type.
  - If$expr2$and$expr3$have different types, the result has the type
    that would be determined by the usual arithmetic conversions, were they
    applied to$expr2$and$expr3$.
    
Example: >
    int a, b, max;

    a = 2;
    b = 5;

    max = a > b ? a : b;   // get maximum of a and b
    
    a == 2 ? FuncA() : FuncB();   // call FuncA() if a == 2, else call FuncB()


I.3.7.5  Series                                                 *crv-opSeries*
---------------
Syntax: $expr1, expr2$

The comma operator$,$ allows to put two separate expressions where one is
required.
At first$expr1$is evaluated. Then$expr2$is evaluated. The result of the
comma operator has the value and type of$expr2$.

It is allowed to nest expressions.

Example: >
    int i, j, k;

    for (i=0, j=15, k=2; i < 5; i++, j--)
    {
      ....
    }

    func(3, (i=3, i+6), k);   // second parameter has value 9 and type int



I.3.7.6  Type Cast                                            *crv-opTypeCast*
------------------
Syntax: $(type-name)expr1$

The type cast operator converts the value of$expr1$to$type-name$.

Examples: >
    int   a, b;
    float f;

    a =  5;
    b = 10;
    
    f = a / b;  
              // f has value 0, integer division

    f = (float)a / (float)b;
              // f has value 0.5


I.3.7.7  Struct/Union Selectors                         *crv-opStructUnionSel*
-------------------------------
- Struct/Union: $expr1.identifier$
The$.$operator selects a member of a structure or union.
$expr1$has the type of a structure or union.


- Pointer to Struct/Union: $expr1->identifier$
The$->$operator selects a member of a structure or union.
$expr1$has the type of "pointer to structure" or 
"pointer to union".

Examples: >
    struct Example {
      int   element1;
      float element2;
    } expl;

    struct Example *ptr;
    
    ptr = &expl;
    
    expl.element1 = 2;
    ptr->element2 = 42.0f;


I.3.7.8  Array Selector                                       *crv-opArraySel*
-----------------------
Syntax: $expr1[expr2]...[exprN]$

Selects an element of an array. First element has index 0.

Examples: >
    int a[3]    = {1,2,3};
    int b[2][3] = { {1,2,3}, {4,5,6}};

    printf("%d\n", b[1][0]);  // output 4

    a[2] = 0;    // array a contains {1,2,0}


I.3.7.9  Parentheses                                           *crv-opParenth*
--------------------
Operator:$()$

The parentheses-operator is used for:

- group expressions
  $a = (b + 2) * c$

- declare functions
  $a = func(b, c + 1)$

- explicit type-cast (see |crv-opTypeCast|)

- statements like 
   $if (...)$
   $for (...)$
   $while(...)$
    ....


------------------------------------------------------------------------------
I.3.8  Precedence                                           *crv-opPrecedence*
  
The precedence defines which operator is done before other ones
(e.g.$a + b * c$: at first the multiplication is done then the addition). 
The following table shows the order of precedence, operators at the top have 
highest precedence.


  Operator                              | Associativity
 ---------------------------------------+---------------- 
$ () [] -> .                           $| left to right
$ ! ~ ++ -- + - (type-name) * & sizeof $| right to left   (unary operators)
$ * / %                                $| left to right
$ + -                                  $| left to right
$ << >>                                $| left to right
$ < <= > >=                            $| left to right
$ == !=                                $| left to right
$ &                                    $| left to right
$ ^                                    $| left to right
$ |                                    $| left to right
$ &&                                   $| left to right
$ ||                                   $| left to right
$ ?:                                   $| right to left
$ = += -= /= *= %= >>= <<= &= |= ^=    $| right to left
$ ,                                    $| left to right


If operators have the same order of precedence, the associativity defines 
the order in which operators are done:
E.g.
  $ a - b - c$
is done as
   $(a - b) - c$
(from left to right)


NOTE: Precedence and associativity define which operator is done before 
other ones. But the order of evaluation of subexpressions is unspecified, 
except from function-call$()$,$&&$,$||$,$?:$and$,$. The order in which side 
effects take place is unspecified too.

  Example:
 $a = b + c * d;$

  Because of the precedence a compiler has to calculate$c*d$and has
  to add$b$and has to assign the result of that whole expression to$a$.
  This is defined in the C standard. But a compiler is free to take e.g.
  $b$and save it, then take$c$and then$d$and do$c*d$, add the saved value
  of$b$and assign result to$a$. Or do any other order of evaluating the
  subexpressions.
  There are just a few operators that force compilers to a specified 
  sequence of evaluating subexpressions (see paragraph above).

  But of course the order of evaluating subexpressions can be relevant:
  Example: >
    int a = 4;
    int b;
    
    b = ((a=2) * (a*=3));  // b either 12 or 24? 
                           // a either 2 or 6? compiler specific
<                          
    If the compiler takes first the expression$(a=2)$and then$(a*=3)$the
    result will be 12. But if the compiler takes first$(a*=3)$and then
   $(a=2)$the result will be 24.

  NOTE: Never ever write code that depends on the order of evaluating
        expressions.




==============================================================================
I.4  Punctuators                                             *crv-punctuators*

Punctuators are special characters, they are not operands or identifiers.
They have their own semantic and syntactic.

 Punctuator  |       Example          |            Description
 ------------+------------------------+---------------------------------------
$   < >     $| <stdio.h>              | header name
$   [ ]     $| n = a[3];              | array delimiter
$   ( )     $| func(a, b);            | function parameter list or
             |                        | expression grouping
$   { }     $| char ch[2]={'a', 'b'}; | function body, initializer list,
             |                        | compound statement
$    *      $| int *ptr;              | pointer declaration
$    #      $| #include               | preprocessor directive
$    ,      $| char ch[2]={'a', 'b'}; | argument list separator
$    :      $| label:                 | label
$    ;      $| a = b + c;             | end of statement
$   ...     $| func(int a, ...)       | variable length of argument list
$    =      $| int n = 2;             | declaration initializer
$   ' '     $| char ch = 'a';         | character constant
$   " "     $| char ch[] = "abc";     | string constant or header file name




==============================================================================
I.5  Datatypes                                                 *crv-datatypes*


------------------------------------------------------------------------------
I.5.1  Overview                                               *crv-dtOverview*

I.5.1.1  Type Specifiers                                *crv-dtTypeSpecifiers* 
------------------------
To specify a datatype in standard C the following type-specifiers are 
allowed:

    $void      $
    $char      $                                                     *crv-char*
    $short     $                                                    *crv-short*
    $int       $                                                      *crv-int*
    $long      $                                                     *crv-long*
    $float     $                                                    *crv-float*
    $double    $                                                   *crv-double*
    $signed    $                                                   *crv-signed*
    $unsigned  $                                                 *crv-unsigned*
    $_Bool     $                                                    *crv-_Bool*
    $_Complex  $                                                 *crv-_Complex*
    $_Imaginary$                                               *crv-_Imaginary*
    $struct    $
    $union     $
    $enum      $
    $typedef-name$


Type specifiers can be combined, the whole set of possible type specifiers is
viewed in the table below. Specifiers given in the same row have the same
meaning.


      Type Specifier      |               Description
 =========================+==================================================
$void                    $| empty or NULL value
 -------------------------+--------------------------------------------------
$char                    $| store member of basic character set
$signed char             $|
 -------------------------+--------------------------------------------------
$unsigned char           $| same as char, but unsigned values only
 -------------------------+--------------------------------------------------
$short                   $| defines a short signed integer
$short int               $|
$signed short            $|
$signed short int        $|
 -------------------------+--------------------------------------------------
$unsigned short          $| same as short, but unsigned values only
$unsigned short int      $|
 -------------------------+--------------------------------------------------
$int                     $| defines a signed integer
$signed                  $|
$signed int              $|
 -------------------------+--------------------------------------------------
$unsigned                $| same as int, but unsigned values only
$unsigned int            $|
 -------------------------+--------------------------------------------------
$long                    $| defines a long signed integer
$long int                $|
$signed long             $|
$signed long int         $|
 -------------------------+--------------------------------------------------
$unsigned long           $| same as long, but unsigned values only
$unsigned long int       $|
 -------------------------+--------------------------------------------------
$long long               $| defines a long long signed integer
$long long int           $|
$signed long long        $|
$signed long long int    $|
 -------------------------+--------------------------------------------------
$unsigned long long      $| same as long long, but unsigned values only
$unsigned long long int  $|
 -------------------------+--------------------------------------------------
$float                   $| defines a floating-point number
 -------------------------+--------------------------------------------------
$double                  $| defines a more accurate floating-point number
                          | than float
 -------------------------+--------------------------------------------------
$long double             $| defines a more accurate floating-point number 
                          | than double
 -------------------------+--------------------------------------------------
$_Bool                   $| defines a Bool-integer (0 or 1 only)
 -------------------------+--------------------------------------------------
$float _Complex          $| defines a complex number with floating
 -------------------------+--------------------------------------------------
$double _Complex         $| defines a complex number more accurate
                          | than the float type
 -------------------------+--------------------------------------------------
$long double _Complex    $| defines a complex number more accurate than
                          | the double type
 -------------------------+--------------------------------------------------
$float _Imaginary        $| defines an imaginary number with floating
 -------------------------+--------------------------------------------------
$double _Imaginary       $| defines an imaginary number more accurate
                          | than the float type
 -------------------------+--------------------------------------------------
$long double _Imaginary  $| defines an imaginary number more accurate than
                          | the double type
 -------------------------+--------------------------------------------------
$struct                  $| defines a set of elements that have possibly 
                          | different datatypes (unlike an array)
 -------------------------+--------------------------------------------------
$union                   $| defines a set of elements that have possibly
                          | different datatypes and use the same overlapping
                          | memory (total size is size of biggest element)
 -------------------------+--------------------------------------------------
$enum                    $| defines a set of named integer constant values
 -------------------------+--------------------------------------------------
$typedef-name            $| a new named type defined with the$typedef$
                          | keyword, the new type is a synonym for one of the
                          | types listed above
 =========================+==================================================

                          

I.5.1.2  Type Grouping                                    *crv-dtTypeGrouping*
----------------------

The types can be grouped in this way:


                                    TYPE
                                      |
                   -------------------+-----------+-------------
                  |                               |             |
                  |                               |             |
        ------- SCALAR -----                  AGGREGATE       $void$
       |                    |                     |
       |                    |                     +------------- 
       |                    |                     |             |
   - ARITHMETIC ---     $pointers$              ARRAY       STRUCTURE
  |                |                              |             |
  |                |                              |             |
INTEGER      - FLOATING -+-----------          $array$     -$struct$-
  |         |            |           |                    |          |
  |         |            |           |                    |          |
  |        REAL       COMPLEX     IMAGINARY            $union    bit-field$
  |         |            |           |
  |         |            |     $_Imaginary$(1)
  |         |            |           |
  |         |            |           +-------+---------
  |         |            |           |       |         |
  |         |            |         $float  double  long double$
  |         |            |
  |         |            |
  |         |        $_Complex$(1)
  |         |            |
  |         |            +-------+---------
  |         |            |       |         |
  |         |          $float  double  long double$
  |         |
  |         |
  |         +-------+--------- 
  |         |       |         |
  |       $float  double  long double$
  |
  |
  +-----------------+---------------+---------   
  |                 |               |         |
$char             short           enum      _Bool$
$signed/unsigned  int                              $
$                 long                             $
$                 long long                        $
$                 signed/unsigned                  $
      

      (1): implementation of these datatypes is not required


The basic types are type char, signed/unsigned integer types and floating
types. 




------------------------------------------------------------------------------
I.5.2  Sizes and Ranges                                      *crv-dtSizeRange*


The C standard defines the basic types as having a "at least" size.

      Type   |                 Size/Range
 ============+===================================================
$char       $| large enough to store any member of the basic 
             | character set
 ------------+---------------------------------------------------
$short      $| same as int or smaller range
 ------------+---------------------------------------------------
$int        $| has the natural size suggested by the architecture
             | of the execution environment 
 ------------+---------------------------------------------------
$long       $| same as int or greater range
 ------------+---------------------------------------------------
$long long  $| same as long or greater range
 ------------+---------------------------------------------------
$float      $| IEEE-754 floating-point standard, single format
 ------------+--------------------------------------------------
$double     $| IEEE-754 floating-point standard, double format
 ------------+---------------------------------------------------
$long double$| shall have more precision than double and at
             | least the range of double
 ------------+---------------------------------------------------
$_Bool      $| large enough to store values 0 and 1
 ============+===================================================



Common - but not guaranteed - values are:


     Type    |                        Size/Range
             |    16-bit Architecture            32-bit Architecture
 ============+================================================================
$char       $|                          8 bit
             |                         0...255
             |                       -128...127
 ------------+----------------------------------------------------------------
$short      $|                         16 bit         
             |                       0...65535      
             |                    -32768...32767 
 ------------+----------------------------------------------------------------
$int        $|       16 bit              |              32 bit
             |      0...65535            |        0...4,294,967,295
             |   -32768...32767          |  -2,147,483,648...2,147,483,647
 ------------+----------------------------------------------------------------
$long       $|                         32 bit            
             |                     0...4,294,967,295 
             |               -2,147,483,648...2,147,483,647  
 ------------+----------------------------------------------------------------
$long long  $|                         64 bit                        
             |             0...18,446,744,073,709,551,615
             |   -9,223,372,036,854,775,808...9,223,372,036,854,775,807    
 ------------+----------------------------------------------------------------
$float      $|                         32 bit
             | magnitudes:         1.175494351e-38...3.402823466e+38
             | significant digits: >= 6
             | given x, next is:   x * (1 + 1.192092896e-7)
 ------------+----------------------------------------------------------------
$double     $|                         64 bits
             | magnitudes: 2.2250738585072014e-308...1.7976931348623158e+308
             | significant digits: >= 15
             | given x, next is:   x * (1 + 2.2204460492503131e-16)
 ------------+----------------------------------------------------------------
$long double$|                  96 bits, 80 bits used
             | magnitudes: 3.36210314311209351e-4932 1.18973149535723177e+4932
             | significant digits: >= 18
             | given x, next is:   x * (1 + 1.08420217248550443e-19)
 ------------+----------------------------------------------------------------
$_Bool      $|         16 bit            |             32 bit
             |          0, 1             |              0, 1
 ============+================================================================




------------------------------------------------------------------------------
I.5.2  Formats                                                 *crv-dtFormats*

I.5.2.1  Integer                                            *crv-dtFormatsInt*
----------------

Integer values are represented as binary numbers (base 2).

The range of unsinged integer types is 0...2^(N-1), whereas N is the size
of the integer type (8, 16, 32, 64 bit...).

Value = bitN*2^(N-1) + ... + bit3*2^3 + bit2*2^2 + bit1*2^1 + bit0*2^0

N is the most significant bit, 0 the least significant.

For signed integer values one bit is used as sign, commonly the most 
significant bit.
If sign bit is 0, the representation is the same as for unsigned integer.
If sign bit is 1, a negative value is represented. There are three 
possibilities to represent a negative value:

  - Sign-Magnitude                                         *crv-signMagnitude*
    --------------
    Sign bit 0: the rest is a positive number
    Sign bit 1: the rest is a negative number
    E.g.:
         0000 1001 = +9
         1000 1001 = -9
         
    Attributs:
      +0 and -0 exists
      Range: -2^(N-1) - 1 ... 2^(N-1) - 1  (e.g. 8bit: -127 ... +127)
      adding, subtracting, dividing, multiplying needs extra logic
      conversion from positive to negative values and vice versa is simple

  - One's Complement                                      *crv-onesComplement*
    ----------------
    The negative value is obtained by inverting all bits of the corresponding
    positive value.
    The most significant bit is the sign bit. Positive values have sign bit 0,
    negative values have sign bit 1.

    Attributs:
      +0 and -0 exists
      Range: -2^(N-1) - 1 ... 2^(N-1) - 1  (e.g. 8bit: -127 ... +127)
      conversion from positive to negative values and vice versa is simple
      adding can be done directly, subtracting can be converted to adding
      multiplication needs extra logic for sign
      
  - Two's Complement                                      *crv-twosComplement*
    ----------------
    The negative value is obtained by inverting all bits of the corresponding
    positive value and adding 1.
    The most significant bit is the sign bit. Positive values have sign bit 0,
    negative values have sign bit 1.

    Attributs:
      only one 0 exists
      Range: -2^(N-1) ... 2^(N-1) - 1, asymetric (e.g. 8bit: -128 ... +127)
      adding and multiplying is straight forward
      sign extension when promoting is simple (repeat sign bit on the left)

Which method is used to represent negative values is implementation specific,
commonly the two's complement is used.


Beneath decimal numbers (base 10), octal (base 8) and hexadecimal (base 16)
numbers can be used in standard C.

Octal numbers start with a 0 (zero), hexadecimal start with a 0x (zero x).
Opposed to decimal numbers, conversions from and to binary is easier with
octal and hexadecimal numbers.
Octal groups 3 bits, one digit has range 0...7.
Hexadecimal groups 4 bits, one digit has range 0...9, A...F.

Examples:
       Bit
        15 14 13 12 11 10  9  8  |  7  6  5  4  3  2  1  0
        --------------------------------------------------
         1  1  1  0  1  0  0  1     0  1  0  1  1  0  0  1
           |        |        |           |        |
octal:   1 |   6    |   4    |    5      |   3    |   1     = 0164531


       Bit
        15 14 13 12 11 10  9  8  |  7  6  5  4  3  2  1  0
        --------------------------------------------------
         1  1  1  0  1  0  0  1     0  1  0  1  1  0  0  1
                    |            |             |
hex:          E     |     9      |      5      |    9       = 0xE959




I.5.2.2  Floating-Point                                   *crv-dtFormatsFloat*
-----------------------

I.5.2.2.1  Basics                                      *crv-dtFormatsFPBasics*
-----------------
In standard C floating values are represented as described in the floating-
point standard IEC 60559 (previously IEEE-754). 
NOTE: The standard does not define bit-positions!

Generally a floating pointer number consists of four parts:
  - sign
  - mantissa
  - radix
  - exponent
  
      ---------------------------------------------- ~
     |  value = sign * mantissa * radix^(exponent)  |~
      ---------------------------------------------- ~

The sign is +1 or -1. The mantissa holds the significant digits of a 
floating-point number and is always positive. 
The exponent indicates the positive or negative power of the radix. To
be able to get positive and negative exponents a bias is added to the 
actual exponent.

A number can be expressed in many different ways, e.g.:
  3.0:   3.0 * 10^0
        0.03 * 10^2
         300 * 10^(-2)
           .....

To maximize the quantity of representable numbers, floating-point numbers
are typically stored in a normalized form.
A normalized floating-point number has a mantissa that's leftmost digit
is non-zero. To normalize the mantissa is shifted left until the leftmost
digit is non-zero, the exponent is reduced by the number of shifts.
The normalized form of the number 3.0 would be:
       3.0 * 10^0
A mantissa of a floating-point number fulfils the following equation:

                  1/radix <= mantissa < 1~

If this equation is not fulfilled, the floating-point number is called
denormalized.

For bias 2 an optimization is available and exploited: for normalized
floating-point numbers the leftmost bit of the mantissa is always 1.
This bit don't need to be stored explicitly. We can assume it to be 1 so that
we get an extra bit to increase resolution (e.g. for float we have a 23 bit
mantissa, but a 24 bit resolution).


Special Values:                                        *crv-dtFormatsFPValues*
---------------
There are some special values explained below.

  Zero:                                                  *crv-dtFormatsFPZero*
  -----
    All exponent and mantissa bits are set to 0. The sign bit can be set or
    cleared, so that +0 and -0 is possible. Both are treated as 0.0.
  
    Note: There is no way to represent the value 0.0 in the format described
    above. Because of normalization the leading digit must be unequal 0.
  
  Infinity:                                          *crv-dtFormatsFPInfinity*
  ---------
    Infinity is signaled by all bits of exponent set and all bits of mantissa
    cleared. The sign bit denotes +infinity and -infinity.
    Infinity allows to handle overflows.
    
  NaN (Not a Number):                                     *crv-dtFormatsFPNaN*
  -------------------
    NaN is used to signal that the value is not a real number. NaN is denoted
    by all exponent bits set and the mantissa != 0.
    There are two types of NaN: Signalling NaN and Quiet NaN
    Both indicates that something went wrong.
    
    Signalling NaN:
      The most significant mantissa bit cleared denotes a signalling NaN.
      A signalling NaN denotes an invalid operation (e.g. division by zero).

    Quiet NaN:
      The most significant mantissa bit set denotes a quiet NaN.
      A quiet NaN is set, if the result of an operation is not mathematically
      defined.

  Denormalized:                                       *crv-dtFormatsFPSDenorm*
  -------------
    If the exponent is 0 and the mantissa is unequal 0, then the value is a
    denormalized number. A denormalized number has no assumed 1 in the
    mantissa.



Special Operations:                                        *crv-dtFormatsFPOp*
-------------------

            Operation       |  Result
   -------------------------+------------
             n / +-infinity |     0
              +-nonzero / 0 | +-infinity
    +-infinity * +-infinity | +-infinity
        infinity + infinity |   infinity
        infinity - infinity |    NaN
    +-infinity / +-infinity |    NaN
             +-infinity * 0 |    NaN
                  +-0 / +-0 |    NaN

                  

I.5.2.2.2  Types                                        *crv-dtFormatsFPTypes*
----------------
Below commonly used floating-point formats are described. The bit positions
are not defined in standards, neither in standard C nor in IEEE-754.

The radix is 2, so that the formula to get the value of a floating-point 
number is:

          ------------------------------------------ ~
         |  value = sign * mantissa * 2^(exponent)  |~
          ------------------------------------------ ~

Float:                                                  *crv-dtFormatsFPFloat*
------
  Radix:      2
  Sign:       1 bit,  = 0 positive, = 1 negative
  Exponent:   8 bit,  bias 127
  Mantissa:   23 bit, 24 bit resolution
  Total Size: 32 bit
  Range:      1.175494351e-38...3.402823466e+38
  Precision:  >= 6 (number of digital digits of precision)
              (see also |crv-dtSizeRange|)
  
  Bit:  31  30      23  22                     0
         s   eeeeeeee    mmmmmmmmmmmmmmmmmmmmmmm

         s: signe
         e: exponent
         m: mantissa

  Examples: 
             s eeeeeeee  mmmmmmmmmmmmmmmmmmmmmmm
    0.75  =  0 01111110  10000000000000000000000
                         |___________
                                     |
             e = 126 - 127 = -1      |
             m = 1 (assume MSB 1) + 1/(2^1)
               = 1.5
             value = 1.5 * 2^(-1) = 0.75

             s eeeeeeee  mmmmmmmmmmmmmmmmmmmmmmm
   12.75  =  0 10000010  10011000000000000000000
                         |  ||____________________________
                         |  |____________________         |
                         |___________            |        |
                                     |           |        |
             e = 130 - 127 = 3       |           |        |
             m = 1 (assume MSB 1) + 1/(2^1) + 1/(2^4) + 1/(2^5)
               = 1.59375
             value = 1.59375 * 2^3 = 12.75

   denormalized:
                     s eeeeeeee  mmmmmmmmmmmmmmmmmmmmmmm
   1.46936...e-39 =  0 0000000   01000000000000000000000
                                  |________
                                           |
             e = 0 - 127 = -127            |
             m = 0 (no assumed MSB 1) + 1/(2^2)
               = 0.25
            value = 0.25 * 2^(-127) = 1.4693679385278594e-39
            
Double:                                                *crv-dtFormatsFPDouble*
-------
  Radix:      2
  Sign:       1 bit,  = 0 positive, = 1 negative
  Exponent:   11 bit, bias 1023
  Mantissa:   52 bit, 53 bit resolution
  Total Size: 64 bit
  Range:      2.2250738585072014e-308...1.7976931348623158e+308
  Precision:  >= 15 (number of digital digits of precision)
              (see also |crv-dtSizeRange|)

  Bit:  63  62         52  51                     0
         s   eeeeeeeeeee    mmmmmmmm...mmmmmmmmmmmm

         s: signe
         e: exponent
         m: mantissa


Long Double:                                          *crv-dtFormatsFPLDouble*
------------
  Radix:      2
  Sign:       1 bit,  = 0 positive, = 1 negative
  Exponent:   15 bit, bias 16383
  Mantissa:   64 bit, 64 bit resolution(!), no assumed 1 in MSB
  Total Size: 92 bit, 80 bit used
  Range:      3.36210314311209351e-4932...1.18973149535723177e+4932
  Precision:  >= 18 (number of digital digits of precision)
              (see also |crv-dtSizeRange|)

  Bit:  79  78             64  63                     0
         s   eeeeeeeeeeeeeee    mmmmmmmm...mmmmmmmmmmmm

         s: signe
         e: exponent
         m: mantissa


------------------------------------------------------------------------------
I.5.3  void Type                                                  *crv-dtVoid*
                                                                    *crv-void*
The$void$type specifies an empty or NULL type. This is used to:
  - signify that a function does not return a value
  - specify a function prototype with no arguments
  - indicate a generic pointer
    A generic pointer can point to any object type. No type cast is
    necessary.

Examples:
  - function with no return value >
    void Func(int n)
    {
      ...
    }
<    
  - function with no arguments >
    int Func (void)
    {
      ...
    }
<
  - generic pointer >
    int  i;
    long l;
    void *ptr;

    ptr = &i;
    ptr = &l;
<



------------------------------------------------------------------------------
I.5.4  Arrays                                                   *crv-dtArrays*

Syntax:
$storage-class-specifier type-specifier declarator[constant-expression$or$*];$

$storage-class-specifier$,$constant-expression$and$*$are optional

Arrays are used to group data types of the same type. An array can be of any 
data type, except$void$.

When addressing an index within this array, indexing starts at 0 and ends
at array-size(in elements) - 1.

An array has only one dimension. To get a multidemsional array an array of
array(s) can be declared.
The elements of arrays are stored in increasing addresses so that the
rightmost subscript varies most rapidly.
Example:   $int n[2][3];$
            the elements are stored in this sequence:
            n[0][0], n[0][1], n[0][2],  n[1][0], n[1][1], n[1][2]

            It can be initialized with:
           $int n[2][3] = { {0, 1, 2}, {3, 4, 5} };$


Complete Array Type Declaration                      *crv-dtCompleteArrayDecl*
-------------------------------

A complete array type declaration is a declaration of an array with known 
size. The number of elements an array stores is specified at declaration. 

E.g.: $int array[2];$

The number of elements must be a constant value of >= 1 or a$*$.

If a$*$is specified then the array type is a variable-length array type of 
unspecified size, which can be used only in declarations with function 
prototype scope.


Incomplete Array Type Declaration                  *drv-dtIncompleteArrayDecl*
---------------------------------

It is possible to declare an array of unknown size by omitting the size-
information at declaration. This sort of array declaration is called 
incomplete array declaration. The size of an incomplete array declaration must
be specified elsewhere, so that the array type itself is complete.

Incomplete array type declaration is useful for:
 - When initializing at declaration. E.g.: >
     char name1[] = "bert";     // end of string (0x00) is added automatically
     char name2[] = {'b', 'e', 'r', 't', '\0'};
<
   The size of both arrays is 5 bytes. The initialization does complete the
   array type.

 - To reference to an external defined array with known size: >
     extern array[];

     int main(void)
     {
       array[0] = 42;
       ....
     }
<
   To work with this array, its size must be known of course.

 - For function parameter incomplete array type declaration can be used in the
   function's declaration. E.g. >
     void func(int array[])
     {
       array[0] = 2;
     }
<
     A pointer must be passed to this function!


Initialization of Arrays                                     *drv-dtArrayInit*
------------------------

Arrays can be initialized at definition time. It is allowed to initialized
less or all elements of a array. If less are initialized the remaining
elements are set to 0 automatically.
 
   Initialize all elements of the array, e.g.:
    $int a[2] = {1, 2};$
    
   Initialize the first elements, the rest is set to 0:
    $int a[5] = {1, 2, 3};$
   Not allowed is to initialize more elements as the array can store:
    $int a[5] = {1, 2, 3, 4, 5, 6}; // ERROR at compilation time$

   Initialize multidimensional arrays:
    $int b[2][3] = { {0, 1, 2}, {3, 4, 5} };$

   Initialize incomplete arrays:
    $char name1[] = "bert";     // end-of-string (0x00) is added$
    $char name2[] = {'b', 'e', 'r', 't', '\0'};$

   Attention when assigning strings to arrays: 
   The end-of-string (0x00) is added only if the string fits into array:
     $char ch[3] = "abc" // no end-of-string (0x00) is added here!$
     $char ch[4] = "abc" // end-of-string is added$
     $char ch[]  = "abc" // end-of-string is added, array gets dimension of 4$



------------------------------------------------------------------------------
I.5.5  Structures                                            *crv-dtStructurs*
                                                                  *crv-struct*
Syntax:
 $struct$structur-name${$
   $variables,...$
 $}$structur-variable,...$;$


Structures are used to group heterogenous data. The elements (members) of a 
structure can be of different data types (opposed to arrays). All data types
are allowed, except$void$type.
The member names must be unique within a structure, but the same names can be
used in nested structures.
A structure cannot contain instances of themselves, but can have pointers
to instances of themselves as members.

The members are stored sequentially in increasing addresses. The first member
is at the starting address of a structure. But a compiler is free to add 
pad-bytes for alignment. So the total size of a structure may differ from the
sum of member-sizes. 
A pointer to a structure points to the starting address of the structure,
there the first member is stored.

To access a member of a structure, the structure selector$.$is used. To access
a member of a structure a pointer points to$->$is used.

A structure can be passed by value to functions and returned by value by
functions. Allowed operators with structures are$=$and$sizeof$.


Declaration                                                  *crv-dtStructDef*
-----------
To declare a structure the 'structur-variable' is omitted, e.g.: >
  struct myStruct {
    int  n;
    char *name;
    long counter;
  };
No variable is generated here, it's the declaration of a structure with 
name myStruct. To get an object do:
$ struct myStruct ms;$


Definition                                                  *crv-dtStructDecl*
----------
A definition can be done in several ways:

  - If a structure is declared already, a definition is done this way:
     $struct Person pers;$
    perss is the object generated

  - Declaration and definition can be done both, e.g.: >
      struct Person {
        int  age;
        char *name;
      } pers1;
<   An object pers1 is generated. 'structur-variable' can be a comma-
    separated list of variables, e.g.: >
      struct Person {
        int  age;
        char *name;
      } pers1, pers2, pers3;
<   The objects pers1, pers2 and pers3 are generated.

    Further definitions can be done via:
     $struct Person pers4;$
    because a 'structure-name' was specified above.
    
  - Only definition, no 'struct-name' specified, e.g.: >
      struct {
        int  age;
        char *name;
      } pers1;
<   An object pers1 is generated.


Initialization                                              *crv-dtStructInit*
--------------
Structures can be initialized at definition time. It is allowed to initialized
less or all members of a structure. If less are initialized the remaining
elements are set to 0 automatically.

Examples: >
  struct Person {
    int age;
    char *name;
  } pers1      = {42, "Sting"};
<or >
  struct Person pers2 = {42, "Sting"};
  

Accessing                                                 *crv-dtStructAccess*
---------
A member of a structure can be accessed via$.$,e.g.: >
  myStruct.age = 42;
  myStruct.anotherStruct.n = 3;

A member of a structure a pointer points to can be accessed via$->$, e.g.: >
  myStructPtr->age = 42;
  myStructPtr->anotherStruct.n = 3;


------------------------------------------------------------------------------
I.5.6  Unions                                                   *crv-dtUnions*
                                                                   *crv-union*
Syntax:
 $union$union-name${$
   $variables,...$
 $}$union-variable,...$;$


A union is used to store objects of different data types at the same location
in memory. All members of a union have offset 0 to the start address of the
union. Enough space is allocated only for the largest member in the union.

For members all data types are allowed, except$void$type. The member names 
must be unique within a union, but the same names can be used in nested 
unions. A union cannot contain instances of themselves, but can have pointers
to instances of themselves as members.

A pointer to a union points to the starting address of the union.

To access a member of a union, the union selector$.$is used. To access a 
member of a union a pointer points to$->$is used.

A union can be passed by value to functions and returned by value by
functions. Allowed operators with unions are$=$and$sizeof$.


Declaration                                                   *crv-dtUnionDef*
-----------
To declare a union the 'union-variable' is omitted, e.g.: >
  union Integers {
    char  c;
    short s;
    int   n;
    long  l;
  };
No variable is generated here, it's the declaration of a union with name 
Integers. To get an object do:
$ union Integers ints;$


Definition                                                   *crv-dtUnionDecl*
----------
A definition can be done in several ways:

  - If a union is declared already, a definition is done this way:
     $union Integers ints;$
    ints is the object generated

  - Declaration and definition can be done both, e.g.: >
      union Integers {
        char  c;
        short s;
        int   n;
        long  l;
      } ints1;
<   An object ints1 is generated. 'union-variable' can be a comma-
    separated list of variables, e.g.: >
      union Integers {
        char  c;
        short s;
        int   n;
        long  l;
      } ints1, ints2, ints3;
<   The objects ints1, ints2 and ints3 are generated.

    Forther definitions can be done via:
     $union Integers ints;$
    because a 'union-name' was specified above.
    
  - Only definition, no 'union-name' specified, e.g.: >
      union {
        char  c;
        short s;
        int   n;
        long  l;
      } ints1;
<   An object ints1 is generated.


Initialization                                               *crv-dtUnionInit*
--------------
Unions can be initialized at definition time, but only the first member can 
be given an initializer.

Examples: >
  union Integers {
        char  c;
        short s;
        int   n;
        long  l;
  } ints1  = {'a'};
<or >
  union Integers ints2 = {'a'};
  

Accessing                                                  *crv-dtUnionAccess*
---------
A member of a union can be accessed via$.$,e.g.: >
  myUnion.age = 42;
  myUnion.anotherUnion.n = 3;

A member of a union a pointer points to can be accessed via$->$, e.g.: >
  myUnionPtr->age = 42;
  myUnionPtr->anotherUnion.n = 3;



------------------------------------------------------------------------------
I.5.7  Bit-Fields                                            *crv-dtBitFields*

Syntax:
 $type-specifier identifier:constant-expression$

A member of a structure or union can be declared to consist of a specified
number of bits. Such a member is called a bit-field.
A bit-field can be of type$_Bool$,$signed int$,$unsigned int$or of some other
implementation specific type. The specified number of bits for a bit-field
must be small enough to be stored in its type.

Sequences of bit-fields are packed as tightly as possible, they are assigned 
from low-order to high-order bit.
If in a sequence of bit-fields a further bit-field is specified, and this
bit-field does not fit into the remaining bits, it's implementation-specific
whether this bit-field is put into the next unit or overlaps adjacent units.

A bit-field can be closed in two ways:
 - specify a data-type !=$bit-field$, a following bit-field will be started
   in a new unit at low-order bit
 - specify a bit-field with size 0, a following bit-field will be started
   in a new unit at low-order bit

For padding it is possible to declare a bit-field without identifier 
(e.g. :10).

Pointers to bit-field are not possible.

Examples: >
  struct BitField {
    unsigned int a:2;
    unsigned int  :3;  // leave 3 bits free
    unsigned int b:4;
    unsigned int  :0;  // force to start new unit

    unsigned int c:4:
    unsigned int c:1;

    long lng;

    unsigned int d:2;  // start a new unit since the previous type is
                       // not a bit-field
  };
<
  also possible would be >
  struct BitField {
    unsigend int a:2,
                  :3,  // leave 3 bits free
                 b:4,
                  :0,  // force to start new unit

                 c:4,
                 c:1;

    long lng;

    int d:2;  // start a new unit since the previous type is
              // not a bit-field
  };
 

Accessing a bit-field is done this way: >
  struct BitField {
    unsigend int a:2,
                 b:3;
  } bf;

  bf.a = 3;
  bf.b = 0;



------------------------------------------------------------------------------
I.5.8  Enumerated Tags                                       *crv-dtEnumerate*
                                                                    *crv-enum*
Syntax:
  $enum identifier{enumerator-list} declarator;$


An enumeration type is a user-defined integer type. The possible values of
this type are defined in the$enumerator-list$. The elements of this list are
symbolic representations of constant integers.
Each element of the$enumerator-list$gets the value of the previous plus 1. 
The first element gets the value 0. Alternatively values can be assigned to 
the elements.

All this could be achieved by using$#define$too. The advantage of enumeration
types is that debuggers can view values of enumeration type objects
symbolically.


Examples: 
 $enum color {red, yellow, green};$

   $color$is a new integer type that can have the values$red$(=0),$yellow$(=1)
    and$green$(=2).

Assignment can be done this way: >
  color col;
  col = red;

To assign values to the constants do:
 $enum color {red=10, yellow, green=20, white};$

   $color$is a new integer type that can have the values$red$(=10),$yellow$
    (=11),$green$(=20) and$white$(=21).



------------------------------------------------------------------------------
I.5.9  Strings                                                 *crv-dtStrings*

In C a string is an array of characters encapsulated in double quotes. At
the end of the string an end-of-string (0x00} is appended.

Example: >
  char strng[] = "this is a string";



------------------------------------------------------------------------------
I.5.10  Type Definitions                                       *crv-dtTypeDef*

A type definition is used to define a type synonym for a data type.
Type definitions are just aliases. The compiler replaces a type definition 
by its assigned type.

Type definitions can apply to variables or functions.

Type definitions provide:
  - It is possible to replace a lengthy and/or confusing type definition 
    by an expressive one.
  - Type definitions can simplify the process of changing the type of
    variables. Example:
     $typedef short coordinate;$
    If you notice that$short$is too small for your needs, simply change it: 
     $typedef long coordinate;$
    and all variables of the type$coordinate$will have the new type$long$.

Example for data type: >
  typedef int * pointerToInt;

  pointerToInt iPtr;  // is identical to: int *iPtr;

Example for function: >
  typedef int calculate(int a, int b);  // function returns int, and gets
                                        // two ints
  calculate sum;                // declarate functions
  calculate dif;

  int sum(int a, int b)         // definition: parameters and return type
  {                             // must be according to the typedef
    return a + b;
  }

  int dif(int a, int b)
  {
    return a - b;
  }



------------------------------------------------------------------------------
I.5.11  Storage Classes                                 *crv-dtStorageClasses*

A storage class defines the scope and lifetime of a variable or function.
                                         see |crv-gloScope|, |crv-gloLifetime|
                                      
  Storage Class |
    Specifier   | Description
 ---------------+------------------------------------------------------------
  $ auto       $| default, local variable has local lifetime
  $ static     $| local variable, but maintained during program execution
  $ extern     $| indicates that a variable is defined outside of the current
                | file, no variable is created by this
  $ register   $| request to access variable as fast as possible (normally 
                | this means to store an object in a CPU register)
  $ typedef    $| creates an alias name for a basic or derived data type
    none, in    | a global variable is defined
    file scope  |



$auto$                                                              *crv-auto*
------
The$auto$class specifies a local variable with local lifetime. The storage of
a variable is created upon entry to the block defining the variable, and is 
destroyed when exiting the block. 

The contents of a new defined$auto$object is undefined.

This class can only be declared at the beginning of a block { ... }.
If no storage class if given, this is the default.

Example: >
  int main(void)
  {
    int a;               // auto can be omitted, it's the default
    auto int b;
    auto long c = 10L;   // initializer can be used

    ....
  }
  

$static$                                                          *crv-static*
--------
The$static$class specifies that an object is maintained during the whole 
program execution, but it's accessable only within its scope (block or file).
Several objects with the same identifier can co-exist, as long as they have
different scopes.

A$static$object can be declared anywhere a declaration is allowed.

The contents of a new$static$object is initialized, arithmetic members are
set to 0, pointer members are set to NULL. If an initializer is given, the
object is initialized only once at program start. Its contents is preserved
after leaving object's scope.

Example: >
  int TestFunction ()
  {
    static int b;          // initialized with 0 automatically
    static long c = 10L;   // initializer can be used

    if (c == 10L)
    {
      b++;
      c++;
    }
    ....      // next time calling b will be 1 and c will be 11
  }


$register$                                                      *crv-register*
----------
The$register$class suggests the compiler to minimize access time for
a variable. Normally this means to assign the value to a register.
The compiler is free to do so or not.
The lifetime is the same as for$auto$.

The$register$class is the only storage class specifier that can
be used for function parameters too.

Example: >
  int TestFunction (register int a)
  {
    register int b;
    ... 
  }


$extern$                                                          *crv-extern*
--------
Using$extern$in a declaration brings the named object into the current scope,
the object must be a global one. This is used to access objects that are 
defined out of the current file (linkage ->|crv-gloLinkage|).

No new variable is generated, it is just a link to an existing one.

Example: >
 File 1:                     File 2:
 -------                     -------
  int globVar2 = 42;         extern int globVar2;
  
  int main(void)             void TestFunc(void)
  {                          {
    ....                       globVar2 = 3;
  }                            ...
                             }


$typedef$                                                        *crv-typedef*
---------
The$typedef$is used to create an alias for a basic or derived (array, struct,
union) data type.
Actually$typedef$isn't a real storage class, but in standard C it is defined
to be one.
No new variable is generated.
For further information see |crv-dtTypeDef|.


Global Variable
---------------
A global variable is defined when the definition is within file scope and
no storage class specifier is given.

A global object is initialized, arithmetic members are set to 0, pointer 
members are set to null pointer, in unions the first named member is
initialized according to this rules. An initializer can be given.

To access a global variable from outside of its scope, declare this
variable with$extern$class in the new scope.

Example: >
 File 1:                     File 2:
 -------                     -------
  int globVar;               extern int globVar2;
  
  int globVar2 = 42;
  
  int main(void)             void TestFunc(void)
  {                          {
    ....                       globVar2 = 3;
  }                            ...
                             }


------------------------------------------------------------------------------
I.5.12  Qualifiers                                          *crv-dtQualifiers*

The type qualifiers allow to set further attributes of data types.

  Type Qualifier |  Description
 ----------------+------------------------------------------------------------
  $ const       $| no write access to a variable
  $ restrict    $| only for pointers: gives compiler better possibilities for
                 | optimizations
  $ volatile    $| disable compiler optimization for a variable



$const$                                                            *crv-const*
-------
The$const$type qualifier is used to qualify an object as not modifiable. This
means no write access is allowed to this object after initialization.
The$const$qualifier can be used for any data type and together with$volatile$.

When$const$is used to qualify an aggregate type (array, struct, union) all
members are$const$. When$const$is used to qualify a member of an aggregate
only that member is$const$.

NOTE: Attempting to change a$const$object using a pointer to a non-$const$ 
object causes unpredictable behavior.

Example: >
  const a = 5;       // a = 5 and a is not modifiable

  const struct Test {
    int  b;
    char *title;
  } test;            // all members of test are const

  const int *ptr;   // pointer to a constant integer type
                    // pointer is allowed to change, contents not

  int *const ptr;   // constant pointer; pointer is not allowed to change
                    // contents is allowed to change
                    
  const int *const ptr;  // both pointer and contents are not allowed
                         // to change
                         

$restrict$                                                      *crv-restrict*
----------
The$restrict$qualifier can only be used for pointers. It indicates that the
compiler is allowed to make optimizations when dealing with this pointer.

Normally compilers can do very less optimizations to pointers because the
compiler cannot determine whether or not two pointers point to the same
object. So the compiler must suppress various optimizations.

The user guarantees that none of the$restrict$qualified pointers do 
point to the same object. So the compiler can do further optimizations
for these pointers.


$volatile$                                                      *crv-volatile*
----------
The$volatile$qualifier indicates that the value of an object can possibly be 
changed outside of compiler's control (e.g. changes done by other processes, 
hardware registers of mikrocontrollers,...). The$volatile$qualifier forces 
the compiler to take this into account. The compiler must access the object
always from memory and most optimizations can't be done.

The$volatile$qualifier can be used for any data type and together with$const$
qualifier.
When$volatile$is used to qualify an aggregate type (array, struct, union) all
members are$volatile$. When$volatile$is used to qualify a member of an 
aggregate only that member is$volatile$.

Example: >
  volatile int a;

  int main(void)
  {
    ....
  }
  

Hint: When type casting a volatile variable, the volatile qualifier will be
      lost if it is omitted in the type cast operator.
 
Example: >
  volatile int ptrA;
  long ptrB;

  ...

  ptrA = (int *)ptrB;             // ATTENTION: after this, ptrA is no
                                  //            longer volatile!

  ptrA = (volatile int *)ptrB;    // ptrA is still volatile

  




------------------------------------------------------------------------------
I.5.13  Pointers                                              *crv-dtPointers*

A pointer contains the address of a variable of stated type, function or 
memory area. 

A pointer can have a special value indicating that the pointer points to
nowhere. Such a pointer is called null pointer, its value is NULL.
A pointer of type$void$can be used to point to an object of any type.
A pointer can point to pointers.

A pointer is declared using the$*$punctuator. The operator$*$is used to
dereference a pointer in order to have access to the contents of the object
the pointer points to.


I.5.13.1  Variables                                            *crv-dtPtrVars*
-------------------
To assign the address of a variable to a pointer the address operator$&$is
used. To dereference the$*$operator is used.

Example simple pointer: >
  int n = 3;
  int *ptr;    // define pointer of type int

  ptr  = &n;   // pointer points to n
  *ptr = 4;    // assign object pointer points to value 4 (=> n=4)

Example pointer to pointer: >
  int n = 3;
  int *ptr1;    // pointer to int
  int **ptr2;   // pointer to pointer to int

  ptr1 = &n;    // pointer ptr1 points to int n
  ptr2 = &ptr1; // pointer ptr2 points to pointer to int n
  **ptr2 = 4;   // dereference pointer to pointer and assign 4 (n = 4)

A pointer can be set to a fix address this way (not standard C): >
  int *ptr;

  ptr = (int *)42000;


Pointer and Arrays
------------------
Example pointer to array: >
  int n[2];
  int *ptr;
  
  ptr = &n[0];
  ptr = n;     // is equivalent to ptr = &n[0]
  
Example array of pointers: >
  int *ptrs[3];     // array of pointers to int
  int n1 = 1, n2 = 2, n3 = 3;

  ptrs[0] = &n1;
  ptrs[1] = &n2;
  ptrs[2] = ptrs[0];


Pointer to String
-----------------
A sequence of characters encapsulated with double quotes is a pointer to
const character.
Example: >
  char *ptr;

  ptr = "string";



I.5.13.2  Functions                                           *crv-dtPtrFuncs*
-------------------
A pointer can point to a function and the function can be called via pointer.

A function pointer is defined in a similar way as a function prototype, the
function name is replaced with$(*pointer-name)$.

Example: >
  int (*funcPtr)(int a, int b);   // define a function pointer "funcPtr"

  funcPtr = anyFunction;          // assign function to pointer

  c = funcPtr(2, 3);              // call via function pointer


Example: >
  int sum(int a, int b)
  {
    return a + b;
  }


  int (*funcPtr)(int a, int b);   // define a function pointer

  int main(void)
  {
    int a;

    funcPtr = sum;       // assign function to pointer

    a = funcPtr(2, 3);   // same as a = sum(2, 3);
    
    printf("%d\n", a);   // 5 is printed
  }


Example, call function at absolut address: >

  // call a function of type  int Func(int nNumOf)
  // located at address 0x42000
  
  // typedefs make usage of function pointers a little bit clearer
  
  typedef  int (*FuncPtr)( int nNumOf );

  
  int main(void)
  {
    FuncPtr  func1;

    ...

    func1  = (FuncPtr)0x42000;    // assign address to function pointer

    result = func1( n );          // call function func1 points to
  }




I.5.13.3  Arithmetics                                   *crv-dtPtrArithmetics*
---------------------

Some operators are allowed to be used on pointers.


Relational Operators
--------------------
The relational operators$==$,$!=$,$>$,$<$,$>=$,$<=$are allowed if both
operands are pointers of the same type and both pointers point to an element
of the same array or to the first element after that array.

The operators$==$and$!=$are allowed in any case if one of the operands is a 
null pointer (NULL).


Negation
--------
The logic negation$!$is allowed.
The negation of a null pointer (value NULL) is an integer value 1. The
negation of a pointer not equal NULL is an integer value 0.


Increasing and Decreasing
-------------------------
Increasing or decreasing of pointers of type$void$is not allowed, because the
size of the object a$void$pointer points to is unknown.

For other pointer types it is allowed to add / subtract an integer value. 
If an integer value N is added to a pointer the pointer points to the Nth 
element located after the element the pointer pointed to before adding.
If an integer value N is subtracted from a pointer the pointer points to the 
Nth element located before the element the pointer pointed to before
subtracting.

Allowed operations: >
    pointer + integer-value
    pointer - integer-value
    pointer++
    pointer--
    ++pointer
    --pointer
   

Subtraction
-----------
Pointers can be subtracted. Both pointers must not be of type$void$.
Both pointers must be of the same type and must point to an element of the
same array or to the first element after that array.

The operation$pointer1 - pointer2$returns the number of elements separating 
them (negative value if pointer1 < pointer2).


Assignments
-----------
Assignments of pointers are of course allowed. The pointers must be of the
same type (if needed a type cast is to be done).

Compound assignments are allowed as long as the requirements for increasing,
decreasing and subtracting are fulfilled.

Allowed assignments: >
    pointer1  = pointer2    
    pointer  += integer-value
    pointer  -= integer-value
    pointer1 -= pointer2

------------------------------------------------------------------------------
I.5.14  Type Cast                                             *crv-dtTypeCast*

Type cast is an operation that converts the type of an operand into another
type. There are two types of casts, explicit and implicit.


I.5.14.1  Explicit                                        *crv-dtTypeCastExpl*
------------------
The explicit type cast is done with the type cast operator$(type-name)$.
Example: >
    int main(void)
    {
      int   nVar = 42;
      float fVar;

      fVar = (float)nVar;
    }


I.5.14.2  Implicit                                        *crv-dtTypeCastImpl*
------------------
Implicit type casts are done by the compiler according to well defined rules.

A compiler does an implicit type cast:
  - When two or more operands of different types appear in an expression.
  - When arguments are passed to a function that do not conform to the 
    parameters declared in a function prototype. 


When a floating-type operand is converted to an integer, the fractional part
is discarded.


 - If either operand is not of arithmetic type, no conversion is performed.
 
 - If either operand has type$long double$, the other operand is converted 
   to$long double$.

 - Otherwise, if either operand has type$double$, the other operand is 
   converted to$double$.
   
  - Otherwise, if either operand has type$float$, the other operand is 
    converted to$float$. 
    
  - Otherwise the following rules apply: 

    - If both operands have signed integer types or both operands have
      unsigned integer types the operand with the type of lesser rank
      is converted to the type of the operand with greater rank.

    - Otherwise, if the operand that has unsigned integer type has rank
      greater or equal to the rank of the other operand, then the operand with
      signed integer type is converted to the type of the operand with
      unsigned integer type.

    - Otherwise, if the type of the operand with signed integer type can
      represent all of the values of the type of the operand with unsigned
      integer type, then the operand with unsigned integer type is converted
      to the type of the operand with signed integer type.

    - Otherwise, both operands are converted to the unsigned integer type
      corresponding to the type of the operand with signed integer type.


Ranking is $long long$>$long$>$int$>$short$>$char$>$bit-field$
            no matter whether singed or unsigned



------------------------------------------------------------------------------
I.5.15  Constants                                            *crv-dtConstants*

Beneath$enum$there are three categories of constants in C, they are described
below.


I.5.15.1  Integer                                             *crv-dtConstInt*
-----------------

An integer constant can be specified in decimal, hexadecimal or octal. A 
suffix can be added to specify a constant's type.

Decimal~
To specify a decimal constant, the first digit must be a 1...9. For the
following digits the characters 0...9 are allowed.

Hexadecimal~
To specify a hexadecimal constant, a prefix 0x or 0X must be in front of the 
hexadecimal number. For hex-numbers the characters 0...9, a-f and A-F are
allowed.

Octal~
To specify an octal constant the first digit must be a 0 (zero). For the
following digits the characters 0...7 are allowed.


Type~
The type of an integer constant is the first of the corresponding list
in which its value can be represented:

               |                        |  octal or hexadecimal
    Suffix     |    decimal constant    |        constant
 ==============+========================+========================
     none      |$int                   $|$int$
               |$long int              $|$unsigned int$
               |$long long int         $|$long int$
               |$                      $|$unsigned long int$ 
               |                        |$long long int$
               |                        |$unsigned long long int$ 
  -------------+------------------------+------------------------
    $u$or$U$   |$unsigned int$          |$unsigned int$
               |$unsigned long int$     |$unsigned long int$
               |$unsigned long long int$|$unsigned long long int$
  -------------+------------------------+------------------------
    $l$or$L$   |$long int$              |$long int$
               |$long long int$         |$unsigned long int$
               |                        |$long long int$
               |                        |$unsigned long long int$
  -------------+------------------------+------------------------
   both$u$or$U$|$unsigned long int$     |$unsigned long int$
   and$l$or$L$ |$unsigned long long int$|$unsigned long long int$ 
  -------------+------------------------+------------------------
   $ll$or$LL$  |$long long int$         |$long long int$
               |                        |$unsigned long long int$ 
  -------------+------------------------+------------------------
  both$u$or$U$ |                        |
  and$ll$or$LL$|$unsigned long long int$|$unsigned long long int$ 
  -------------+------------------------+------------------------


I.5.15.2  Floating-Point                                    *crv-dtConstFloat*
------------------------
A floating constant has a significant part that may be followed by an exponent
part and a suffix that specifies its type.

If a floating constant has no suffix, its type is$double$. If suffix is$f$or
$F$it has type$float$. If suffix is$l$or$L$its type is$long double$.

     Example  |  Value  |  Type
   -----------+---------+-------------
      .0      | 0.00000 | double
      1.      | 1.00000 | double
      2.23    | 2.23000 | double
      2e2     | 200.000 | double
      2.e2    | 200.000 | double
      2.0e2   | 200.000 | double
      2.0e+2  | 200.000 | double
      2.0e-2  | 0.02000 | double
      3.4f    | 3.40000 | float
      3.4l    | 3.40000 | long double



I.5.15.3  Character                                          *crv-dtConstChar*
-------------------
A character constant is any character from the source character set enclosed 
in apostrophes.
See escape sequences (-> |crv-lngEscSeq|) for special characters.

Examples: >
  char a;
  
  a = 'd';
  a = '\x2F';



==============================================================================
I.6  Statements                                               *crv-statements*


------------------------------------------------------------------------------
I.6.1  if-else                                                  *crv-stIfElse*
                                                           *crv-if* *crv-else*
Syntax: $if (expr1)$
         $  statement1$
        $else$
         $ statement2$


If$expr1$is not equal to 0,$statement1$is done. If$expr1$is equal to 0,
$statement2$is done. The$else$-part is optional.


------------------------------------------------------------------------------
I.6.2  switch                                                   *crv-stSwitch*
                                         *crv-switch* *crv-case* *crv-default*
Syntax: $switch (expr1) {$
        $  case constant-expression1:$
        $    statement1$
        $  ...$
        $  default:$
        $    statementN$
        $}$


Both$case$and$default$-part are optional.

If$expr1$is equal to one of the$constant-expressions$in the$case$labels,
the according $statement$is executed. The$default$-part is entered, 
if$expr1$is not equal to one of the$constant-expressions$of the$case$labels.

If a$statement$is done, the following$statements$are done until the end of 
the$switch$statement is reached or a$break$is done.

There can be several$case$labels, but only one$default$label. The order is
arbitrary.



------------------------------------------------------------------------------
I.6.3  while Loop                                                *crv-stWhile*
                                                                   *crv-while*
Syntax: $while (expr1)$
        $  statement$


The$while$statement provides an iterative loop. 
The loop body ($statement$) is executed as long as$expr1$is true (!=0). If
$expr1$is false (=0) the loop is finished. 
The expression$expr1$is evaluated before$statement$is executed.


------------------------------------------------------------------------------
I.6.4  do-while Loop                                           *crv-stDoWhile*
                                                                      *crv-do*
Syntax: $do$
        $  statement$
        $while (expr1);$


The$do-while$statement provides an iterative loop. 
The loop body ($statement$) is executed as long as$expr1$is true (!=0). If
$expr1$is false (=0) the loop is finished. 
The expression$expr1$is evaluated after$statement$is executed (opposed to
$while$-loop).


------------------------------------------------------------------------------
I.6.5  for Loop                                                    *crv-stFor*
                                                                     *crv-for*
Syntax: $for (expr1; expr2; expr3)$
        $  statement$

The expressions$expr1$,$expr2$and$expr3$are optional.


The$for$statement provides an iterative loop. 

$expr1$: This expression is evaluated once before the first execution of the 
         loop body. Usually this is used to initialize variables used in the 
         loop body (e.g. loop counter).

$expr2$: The loop body ($statement$) is executed as long as$expr2$is true 
        (!=0). If$expr2$is false (=0) the loop is finished.
        If$expr2$is omitted, the expression is always true (infinite loop).

$expr3$: This expression is evaluated after each iteration.

The expression$expr2$is evaluated before$statement$is executed.


------------------------------------------------------------------------------
I.6.6  break                                                     *crv-stBreak*
                                                                   *crv-break*
Syntax: $break;$


The$break$statement is used to immediately terminate the execution of the
enclosing$switch$,$for$,$while$or$do-while$statement.


------------------------------------------------------------------------------
I.6.7  continue                                               *crv-stContinue*
                                                                *crv-continue*
Syntax: $continue;$


The$continue$statement is used to immediately jump to the end of the 
enclosing$for$,$while$or$do-while$statement.


------------------------------------------------------------------------------
I.6.8  goto                                                       *crv-stGoto*
                                                                    *crv-goto*
Syntax: $goto identifier;$


The$goto$statement causes an unconditional jump to a labeled statement
that is specified by$identifier$. The labeled statement must be in the scope
of the function containing the$goto$statement.

A$goto$statement is not allowed to jump past any declaration of objects.
Apart from this jumping into other blocks is allowed.


------------------------------------------------------------------------------
I.6.9  return                                                   *crv-stReturn*
                                                                  *crv-return*
Syntax: $return expr1;$

$expr1$is optional


The$return$statement terminates execution of the current function and returns
control to its caller. If present,$expr1$is evaluated and its value is 
returned to the calling function. If the type of$expr1$is not the same as
the type of the function, implicit type cast is done.

A$return$statement can appear anywhere in a function, several$return$
statements are allowed.

For functions of type$void$either a return without$expr1$must be given or
no$return$statement ($return;$and the enclosing$}$of the function are treated
as the same).


------------------------------------------------------------------------------
I.6.10  Null Statement                                            *crv-stNull*

Syntax: $;$


A null statement performs no operation. A null statement is used in situations
where the grammar of C requires a statement, but the program needs no 
operation.

Usage:
  - supply an empty loop body
    Example: >
      char *strngPtr;

      while (*stngPtr++ != 'a')   // search first 'a' in string
        ;
<
  - set a label just before the closing$}$ 
    Example: >
            ....
               }
    end_loop:  ;
             }




==============================================================================
I.7  Functions                                                 *crv-functions*


------------------------------------------------------------------------------
I.7.1  Definition                                           *crv-fuDefinition*

 $return-type function-name(parameter-list, ...) {$
 $  statement...$
 $}$

 $return-type$    type of value returned by function
 $function-name$  name of function
 $parameter-list$ list of parameters passed to function


The$return-type$is the type the function returns. It can be any type except
array types or function types. If no value is returned,$void$must be used.
If$return-type$is omitted,$int$is assumed.

The$function-name$is the identifier under that a function can be called
(see |crv-gloIdentifier| for valid names).

The$parameter-list$specifies the parameters a function expects when called.
A function can have no parameter, a specific number of parameters or
a variable number of parameters.

  - No Parameter
   --------------
   $parameter-list$must be$void$
    Example: >
      int Func(void)
      {
        ...
        return 0;
      }
<       
  - One or More Parameters
   ------------------------
   $parameter-list$is a comma separated list of parameter specifications.
    Each parameter must be specified this way: $type-name identifier$
     $type-name$ : type of the parameter, if omitted$int$is used
     $identifier$: identifier under which this parameter can be referenced
                   within the function
    Example: >
      int Func(char ch, int cntr)
      {
        if ( (ch == 'q') || (cntr == 42) )
          exit(0);

        return 0;
      }
<       
  - Variable Number of Parameters                           *crv-fuDefVarPara*
   -------------------------------
   $parameter-list$is a comma separated list of parameter specifications
    ending with an ellipsis ($,...$).
    Functions declared in$<stdarg.h>$can be used to access arguments.

    Example: >
      #include <stdarg.h>
      #include <stdio.h>


      void Func(int numOfArgs, ...)
      {
        int n;
        va_list ap;

        va_start(ap, numOfArgs);        // initialize

        for (n = 0; n < numOfArgs; n++)
          printf("%d ", va_arg(ap, int));  // get next argument, type is int

        printf("\n");

        va_end(ap);                     // finish
      }


      int main(void)
      {
        Func(1, 100);            // output is 100
        Func(2, 100, 101);       // output is 100 101
        Func(3, 100, 101, 102);  // output is 100 101 102
      }
<       

A parameter can be of any type. But parameters of array type or function type
are converted automatically to pointers.
Example: >
    #include <stdio.h>


    int Func2()
    {
      return 3;
    }


    void Func1(int n[3], int (*func)(void))
    {
      n[0] = 1;
      n[1] = 2;
      n[2] = func();
    }

    int main(void)
    {
      int n[3] = {5, 5, 5};
      
      Func1(n, Func2);

      printf("%d %d %d\n", n[0], n[1], n[2]);  // output is 1 2 3
      
    }
<

The only allowed storage class for a parameter is$register$.
All kinds of type qualifiers are allowed for parameters.

Arguments are passed by value, that means that a function receives a copy
of the argument's value.
The order of evaluation of arguments is not specified.



------------------------------------------------------------------------------
I.7.2  Prototype                                             *crv-fuPrototype*

 $return-type function-name(parameter-list, ...);$


If a function is used before it's defined then it must be prototyped, so 
that the compiler knows about return type and parameter types of the function,
else$int$is assumed for return type and parameter types.

A prototype is identical to the function header with the addition of an 
ending$;$. Function prototypes need not use parameter identifiers. Only the
types are required.

Normally prototyping occurs at the beginning of a source code file or in a 
header file.


Example: >
    int Func(char ch);


    int main(void)
    {
      if (Func1('q') == 2)
      {
        ....
      }
    }


    int Func(char ch)
    {
      ...
    }
<


------------------------------------------------------------------------------
I.7.3  Conversion                                           *crv-fuConversion*


If a function is called the arguments must be of the same types as specified
in prototype. If not, conversions are done.

Example: >
    void Func(int n, char c, long l);

    int main(void)
    {
      char chr;
      long a;
      int  b;
      
      ...
      
      Func(chr, a, b);    // chr is converted to type int
                          // a is converted to type char
                          // b is converted to type long
    }
<

If no prototype is in scope when calling a function the following conversions
are done on the arguments:
 - An argument of type$float$is converted to type$double$.
 - If an$int$can represent all values of the original type, the value is 
   converted to an$int$. Otherwise it is converted to an$unsigned int$.
   For most compilers this means: an argument of type$char$,$unsigned char$,
  $short$,$unsigned short$is converted to type$int$.

This is called "argument promotion".

No other conversions are performed on arguments.


------------------------------------------------------------------------------
I.7.4  Storage Classes                                  *crv-fuStorageClasses*

Implicitly functions do have the storage class$extern$. To limit the scope of
a function to a file$static$can be used.

Example$extern$: >
    File 1                             File 2
    ------                             ------

    int GetSolution(void)              extern int GetSolution(void);
    {
      return 42;
    }                                  void Func(void)
                                       {
                                          if (GetSolution() == 42)
    int main(void)                        {
    {                                       ...
      if (GetSolution() != 42)            }
      {                                }
        ...
      }
    }
<

Example$static$: >
    File
    ----
    
    static int GetSolution(void)   // can only be referenced within same file
    {
      return 42;
    }


    int main(void)
    {
      if (GetSolution() == 42)
      {
        ...
      }
    }
<


------------------------------------------------------------------------------
I.7.5  Specifier                                             *crv-fuSpecifier*
                                                                  *crv-inline*

A function declared with an$inline$specifier is an inline function. This
suggests that calls to the function be as fast as possible. The extend to
which this suggestion is taken into account is implementation specific.

Normally$inline$means that the call to the function is replaced by the 
function body. As a result of this there is no overhead for calling, but at
the expense of code size, since each call of the inline function is replaced
by it's function body.

For$main()$the$inline$specifier is not allowed.

Example: >

    inline int Func(void)
    {
      ...
      return 42;
    }


    int main(void)
    {
      int a;

      a = Func();
      ...
    }
<



------------------------------------------------------------------------------
I.7.6  main()                                                     *crv-fuMain*

A program begins by calling the$main()$function and ends by exiting
the$main()$function. There is no prototype required for$main()$.

$main()$can be defined in two ways, either with no parameter

$ int main(void)$
$ {$
$   statements$
$ }$

or with two parameters

$ int main(int argc, char *argv[])$
$ {$
$   statements$
$ }$

The return type is type$int$.

The parameters do not have to be named$argc$and$argv$, but it is a common way 
to do so.

Parameter$argc$is a nonnegative integer. If the value of$argc$is greater than
zero, the string pointed to by$argv[0]$is the program name. If the value 
of$argc$is greater than one, the strings pointed to by$argv[1]$through 
$argv[argc - 1]$represent the program parameters.



==============================================================================
I.8  Preprocessor                                           *crv-preprocessor*

A preprocessor is the first pass of a compiler. It does perform macro
substitution, inclusion of files, conditional compilation and provides the
ability to pass control directives to the compiler.

A C-preprocessor directive is invoked by a$#$. Opposed to a C-statement a
C-preprocessor directive is NOT terminated by a semicolon ($;$), instead of
it is terminated by the new-line. To span a directive over several lines
the "line-escape"$\$can be used (see |crv-lngEscSeq|).
Example: >
 #define MEAS_CYCLES   (3  \
                        +  \
                        1)
<
is synonymical to: >
 #define MEAS_CYCLES   (3 + 1)
  

A C-preprocessor directive can be placed anywhere in a source file. The
directive is active from the line of invocation up to the end of source file.


In the following sections possible preprocessor directives and preprocessor
operators are described.



------------------------------------------------------------------------------
I.8.1  Macros                                                  *crv-preMacros*

A macro is an identifier that is equated to a text or symbolic expression 
to which it is to be expanded by the preprocessor.

                                              *crv-preMacObj* *crv-preMacFunc*
There are two types of macros: macros without parameters, they are called 
object-like macros and macros with parameters, they are called function-like
macros.

When using a macro each subsequent occurrence of the macro$identifier$within
source-file is replaced by its$replacement-list$, unless the macro occurs
inside of a comment, a literal string or a character constant.

A macro definition lasts until end of the source-file or until a corresponding
$#undef$is encountered.

Macros can be nested.


NOTE: It is not a good programming style to specify macro arguments that
use side effects. Macro parameters can be used several times within a macro,
that can cause unexpected behaviour.
Example: >
  #define MIN(a, b)  ( (a < b) ? a : b )

  MIN(val1++, val2)
<
  would be replaced: >
  ( (val1++ < val2) ? val1++ : val2 )



I.8.1.1  Definition #define                                    *crv-preMacDef*
---------------------------
                                                                 *crv-#define*
Syntax Object-Like Macro:
 $#define identifier replacement-list newline$

Syntax Function-Like Macro:
 $#define identifier(identifier-list) replacement-list newline$


Example of an object-like macro: >
    #define CONST_ADD  42
    #define FOREVER    for(;;)

    int main(void)
    {
      int a = 0;

      FOREVER
      {
        a += CONST_ADD;
        ...
      }
    }
<
Example of a function-like macro: >
    #define MIN(a, b)  ( (a < b) ? a : b )

    int main(void)
    {
      int x1, x2, x;

      x1 = 2;
      x2 = 5;

      x = MIN(x1, x2);
    }
<
Example of a nested macro: >
    #define CONST1  ( 35 + CONST2 )
    #define COSNT2   7
<


I.8.1.2  Cancellation #undef                                *crv-preMacCancel*
----------------------------
Syntax: $#undef identifier newline$                               *crv-#undef*

A macro specified by$identifier$is no longer a macro name. If$identifier$is 
currently no macro, this directive is ignored.

Example: >
    #define CONST  5

    int main(void)
    {
      ...
      a = CONST;
      ...

      #undef CONST

      a = CONST;   // will cause an error at compilation time
    }
<


I.8.1.3  # Operator                                      *crv-preMac#Operator*
-------------------
                                                                       *crv-#*
The preprocessor operator$#$converts an argument of a function-like macro to a
string literal.

Example: >
    #define PRINT1(var) printf("Value of "#var" is: %d\n", var) 
    #define PRINT2(var) printf("Value of %s is: %d\n", #var, var) 
    
    int main(void)
    {
      int a = 2;
      int b = 3;

      PRINT1(a);   // prints: Value of a is: 2
      PRINT2(b);   // prints: Value of b is: 3
    }



I.8.1.4  ## Operator                                    *crv-preMac##Operator*
--------------------
                                                                      *crv-##*
The preprocessor operator$##$concatenates two tokens.

Example: >
    #define PRINT(prefix, postfix) printf("Value is: %d\n", prefix ## postfix) 

    int main(void)
    {
      int varCar   = 2;
      int varHouse = 3;

      PRINT(var, Car);     // prints: Value is: 2
      PRINT(var, House);   // prints: Value is: 3
    }



I.8.1.5  Predefined Macros                              *crv-preMacPredefined*
--------------------------

There is a set of predefined macro names. They are not allowed to be changed.
                                                                *crv-__DATA__*
$__DATA__$    This macro is evaluated to a string literal representing the 
              date when compilation of the current source-file began. Its 
              form is "Mmm dd yyyy". The names of the months are the same as
              those generated by the$asctime()$function.
                                                                *crv-__FILE__*
$__FILE__$    This macro is evaluated to a string literal representing the
              name of the current source-file.
                                                                *crv-__LINE__*
$__LINE__$    This macro is evaluated to a decimal constant representing the
              current line number.
                                                                *crv-__STDC__*
$__STDC__$    The integer constant 1. Used to indicate if this is a standard 
              C compiler.

$__STDC_HOSTED__$                                        *crv-__STDC_HOSTED__* 
              This macro is evaluated to an integer constant value. If 1
              the compiler is hosted, if 0 it is not.

$__STDC_VERSION__$                                      *crv-__STDC_VERSION__*
              This macro is evaluated to a$long int$value that belongs to the
              revision of the International C Standard. 
                                                                *crv-__TIME__*
$__TIME__$    This macro is evaluated to a string literal representing the 
              time when compilation of the current source-file began. Its 
              form is "hh:mm:ss", the same as what is generated the$asctime()$
              function.


Furthermore the compiler conditionally provides the following macros:

$__STDC_IEC_559__$                                      *crv-__STDC_IEC_559__*
              The integer constant 1. Used to indicate if this C compiler is
              conform to the floating-point standard IEC 60559.
              
$__STDC_IEC_559_COMPLEX__$                      *crv-__STDC_IEC_559_COMPLEX__*
              The integer constant 1. Used to indicate if this C compiler's 
              complex arithmetic is conform to the floating-point standard
              IEC 60559.

$__STDC_ISO_10646__$                                   *crv-__STDC_ISO10646__*
              This macro is evaluated to a$long int$constant value of the
              form yyyymm. Its intention is to indicate that values of
             $wchar_t$are the coded representations of the characters defined
              by ISO/IEC 10646. The year/month refers to the ISO/IEC 10646
              including amendments and corrections this implementation is
              conform to.



------------------------------------------------------------------------------
I.8.2  Conditional Compilation                            *crv-preConditional*

There are preprocessor directives that allow to control which part of a
source-code is to be or is not to be translated (conditional compilation).


I.8.2.1  defined Operator                                 *crv-preCondDefined*
-------------------------
                                                                 *crv-defined*
Syntax: $defined identifier$
      or$defined (identifier)$


The$defined$operator evaluates to 1 if$identifier$is defined, else it
evaluates to 0.$identifier$is a macro name.

$defined$operators can be combined in any logical expression using logical
operators (see |crv-opLogical|).
$defined$is allowed to be used in the expression of an$#if$or$#elif$directive.


Example: >
    #if defined(MACRO1) || (defined(MACRO2) && !defined(MACRO3))
      ...
    #endif


I.8.2.2  #if Directive                                         *crv-preCondIf*
----------------------
                                                                     *crv-#if*
Syntax: $#if constant-expression newline$


This preprocessor directive checks whether the constant expression evaluates
to nonzero. If so, the source-code between$#if$and the corresponding$#endif$,
$#else$or$#elif$is passed to compiler, else it's skipped.

The constant expression may be a$defined$operator, a macro name or any
constant integer expression. Not allowed are type-casts, keywords or 
expressions that need memory ($++$,$--$...).
If a macro name used in the constant expression does not exist, it's treated
as zero.

Example: >
    #if defined(MACRO1) || (defined(MACRO2) && !defined(MACRO3))
      ...
    #endif

    #if (CONST_VALUE + 5 == 8)
      ...       // its value is 8
    #else
      ...       // its value is not 8
    #endif



I.8.2.3  #ifdef Directive                                   *crv-preCondIfdef*
-------------------------
                                                                  *crv-#ifdef*
Syntax: $#ifdef identifier newline$


This preprocessor directive checks whether the identifier is currently 
defined. If so, the source-code between$#ifdef$and the corresponding$#endif$,
$#else$or$#elif$is passed to compiler, else it's skipped.

Example: >
    #define DEBUG  1

    #ifdef DEBUG
       ...       // that is passed to the compiler
    #endif



I.8.2.4  #ifndef Directive                                 *crv-preCondIfndef*
--------------------------
                                                                 *crv-#ifndef*
Syntax: $#ifndef identifier newline$


This preprocessor directive checks whether the identifier is currently not 
defined. If so, the source-code between$#ifndef$and the corresponding$#endif$,
$#else$or$#elif$is passed to compiler, else it's skipped.

Example: >
    #define DEBUG  1

    #ifndef DEBUG
       ...       // that is not passed to the compiler
    #endif



I.8.2.5  #else Directive                                     *crv-preCondElse*
------------------------
                                                                   *crv-#else*
Syntax: $#else newline$


This directive is used together with$#if$,$#ifdef$or$#ifndef$. If the "if"
does not evaluate to nonzero, the source code between the matching$else$and
the$endif$is passed to compiler.

Example: >
    #define DEBUG  1

    #ifndef DEBUG
       ...       // that is not passed to the compiler
    #else
       ...       // that is passed to the compiler
    #endif



I.8.2.6  #elif Directive                                     *crv-preCondElif*
------------------------
                                                                   *crv-#elif*
Syntax: $#elif constant-expression newline$


This directive provides an else-if statement. It can be used together 
with$#if$,$#ifdef$,$#ifndef$or another$#elif$. If the corresponding "if" does
not evaluate to nonzero the$#elif$'s constant expression is tested to be
nonzero. If so, the source-code between$#elif$and the matching$#else$,$#elif$
or$#endif$is passed to the compiler, else not.

See |crv-preCondIf| for further information on the constant expression. 

Example: >
    #if (CONST_VALUE + 5 == 8)
      ...       // its value is 8
    #elif (CONST_VALUE + 5 == 9)
      ...       // its value is 9
    #endif



I.8.2.7  #endif Directive                                   *crv-preCondEndif*
-------------------------
                                                                  *crv-#endif*
Syntax: $#endif newline$


This directive is used to finish one of this directives:$#if$,$#ifdef$,
$#ifndef$,$elif$or$else$.


Example: >
    #ifdef DEBUG
       ...
    #endif



------------------------------------------------------------------------------
I.8.3  File Inclusion #include                              *crv-preSourceInc*
                                                                *crv-#include*
Syntax: $#include "filename" newline$  (1)
        $#include <filename> newline$  (2)
        $#include macro-name newline$  (3)


This preprocessor directive causes the replacement of that directive by the
entire contents of the file specified by$filename$.

Files enclosed in <...> are searched in an implementation-defined manner.
Files enclosed in quotes "..." are searched in an implementation-defined
manner too, if a file is not found it is searched in the same way like
files enclosed in <...>.

In general, form (1) is used to include user files whereas form (2) is used
to include standard library files.

This directive does support macro replacement (form (3)).

Nesting is allowed, an included file may itself contain$#include$directives.
But nesting easy leads to the situation that files are included several times,
which would waste time and may cause compilation errors. There is a standard
way to prevent that a file is included twice due to nesting. It is called
"wrapper #ifndef". Do the following in included files to avoid processing
them twice: >
    // file foo.h
    
    #ifndef _FOO_H_
    #define _FOO_H_

      ... the entire file

    #endif    // #endif of _FOO_H_


Example: >
    #include <stdio.h>
    
    #include "galer.h"


    #define HEADER_FILE "datatype.h"
   
    #include HEADER_FILE




------------------------------------------------------------------------------
I.8.4  Line Control #line                                        *crv-preLine*
                                                                   *crv-#line*
Syntax: $#line digit-sequence newline$              (1)
        $#line digit-sequence "filename" newline$   (2)
        $#line macro-names newline$                 (3)


This preprocessor directive allows to change the current line number and/or
the name of the current source-code file.

The$#line$directive gives the next line in source-code a new line-number.
The line numbers of the subsequent lines are derived from this number by
incrementing for each new line.
The new line-number is specified by$digit-sequence$. Line numbers must be
in the range of 1 to 2147483647.

Furthermore for the current source-code file a new filename can be specified
($filename$).

Form (1) can be used to set a new line number. Form (2) can be used to set
both, a new line number and a new filename.
In form (3) the macro-names are expanded, the result must match either
form (1) or (2). Its then processed appropriate.

The$#line$directive effects the predefined macros$#__LINE__$and$#__FILE__$.

Example: >
    #line 1000 "GALer.c"
or >
    #define NEW_LINE_NUMBER 1000
    #define SOURCE "GALer.c"
    
    #line NEW_LINE_NUMBER SOURCE
    printf("%d %s\n", __LINE__, __FILE__);  // result is: 1000 GALer.c



------------------------------------------------------------------------------
I.8.5  Error Directive #error                                   *crv-preError*
                                                                  *crv-#error*
Syntax: $#error message newline$

        $message$is optional


This preprocessor directive causes the compiler to print a diagnostic message
that includes$message$and cancel compilation.

Example: >
   #if defined UNIX
     ...
   #elif defined LINUX
     ...
   #elif
     #error Error: no system specified
   #endif
<
   If neither UNIX nor LINUX is defined, the compiler prints an error message:
   "Error: no system specified" and cancels compilation.



------------------------------------------------------------------------------
I.8.6  Pragma Directive #pragma                                *crv-prePragma*
                                                                 *crv-#pragma*
Syntax: $#pragma directive newline$


This preprocessor directive provides further control over the compiler. Which
$#pragma$directives an implementation provides is implementation specific. 
If a$#pragma$directive is not known by the implementation, it is ignored.


Example: >
    #pragma Int16    // use 16 bit integer for this file

    #pragma DISABLE_WARNING_32  // disable warning 32 for this file
      ... do stuff that would cause a warning 32
    #pragma ENABLE_WARNING_32




------------------------------------------------------------------------------
I.8.7  Null Directive #                                          *crv-preNull*

Syntax: $# newline$

The preprocessor directive of the form$# newline$has no effect.






==============================================================================
Chapter II  STANDARD C LIBRARY                                   *crv-stdCLib*
==============================================================================

The C language provides no built-in facilities for performing such common
operations as input/output, memory management, string manipulation, and the
like. Instead, these facilities are defined in a standard C library which can
be linked to program.
Subject of this chapter is the standard C library as specified by the ISO C
standard.


==============================================================================
II.1  Standard Headers                                        *crv-libHeaders*

Below is an alphabetically sorted list of all header files of the standard C
library.

        Header    |  Short Description
    --------------+-----------------------------------------------------------
    $<assert.h>  $| diagnostics.............................|crv-libAssertH|
    $<complex.h> $| complex arithmetic......................|crv-libComplexH|
    $<ctype.h>   $| character handling......................|crv-libCtypeH|
    $<errno.h>   $| error codes.............................|crv-libErrnoH|
    $<fenv.h>    $| floating point environment..............|crv-libFenvH|
    $<float.h>   $| characteristics of floating point types.|crv-libFloatH|
    $<inttypes.h>$| format conversion of integer types......|crv-libInttypesH|
    $<iso646.h>  $| alternative spelling....................|crv-libIso646H|
    $<limits.h>  $| sizes of integer types..................|crv-libLimitsH|
    $<local.h>   $| localization............................|crv-libLocalH|
    $<math.h>    $| mathematics.............................|crv-libMathH|
    $<setjmp.h>  $| nonlocal jumps..........................|crv-libSetjmpH|
    $<signal.h>  $| signal handling.........................|crv-libSignalH|
    $<stdarg.h>  $| variable arguments......................|crv-libStdargH|
    $<stdbool.h> $| boolean type and values.................|crv-libStdboolH|
    $<stddef.h>  $| common definitions......................|crv-libStddefH|
    $<stdint.h>  $| integer types...........................|crv-libStdintH|
    $<stdio.h>   $| input / output..........................|crv-libStdioH|
    $<stdlib.h>  $| general utilities.......................|crv-libStdlibH|
    $<string.h>  $| string handling.........................|crv-libStringH|
    $<tgmath.h>  $| type-generic math.......................|crv-libTgmathH|
    $<time.h>    $| date and time...........................|crv-libTimeH|
    $<wchar.h>   $| extended multibyte and wide.............|crv-libWcharH|  
                  | character utilities
    $<wctype.h>  $| wide character classification and.......|crv-libWctypeH| 
                  | mapping utilities



==============================================================================
II.2  <assert.h> Diagnostics                                  *crv-libAssertH*

  Quicklink:
    $assert()$ Macro  |crv-assert|
    $NDEBUG$   Macro  |crv-NDEBUG| 


assert() Macro                                       *crv-assert* *crv-NDEBUG*
--------------
Synopsis~
 $#include <assert.h>$
 $void assert (int expression);$

Return~
  none
  
Description~
The macro$assert()$tests the value of$expression$. If it is false (zero),
the$assert()$macro writes the following information on the standard error
stream:
  - text of argument
  - name of source file
  - line number
  - name of the enclosing function
The format of output is implementation-defined. After writing this information
the program is terminated by calling the$abort()$function.

If the macro$NDEBUG$is defined before including$<assert.h>$,$assert()$is
defined as follows:
 $#define assert(ignore) ((void)0)$
This means that the macro has no effect,$expression$is even not evaluated.

Note: The assert facility is designed for detecting internal inconsistency; 
it is not suitable for reporting invalid input or improper usage by the user
of the program.




==============================================================================
II.3  <complex.h> Complex Math                               *crv-libComplexH*

This header file defines macros and declares functions that allow to do
complex arithmetic.

Quicklink:
    $_Complex_I$       Macro  |crv-_Complex_I|
    $_Imaginary_I$     Macro  |crv-_Imaginary_I|
    $cabs()$           Func   |crv-cabs|
    $cabsf()$          Func   |crv-cabsf|
    $cabsl()$          Func   |crv-cabsl|
    $cacos()$          Func   |crv-cacos|
    $cacosf()$         Func   |crv-cacosf|
    $cacosl()$         Func   |crv-cacosl|
    $casin()$          Func   |crv-casin|
    $casinf()$         Func   |crv-casinf|
    $casinl()$         Func   |crv-casinl|
    $catan()$          Func   |crv-catan|
    $catanf()$         Func   |crv-catanf|
    $catanl()$         Func   |crv-catanl|
    $cacosh()$         Func   |crv-cacosh|
    $cacoshf()$        Func   |crv-cacoshf|
    $cacoshl()$        Func   |crv-cacoshl|
    $carg()$           Func   |crv-carg|
    $cargf()$          Func   |crv-cargf|
    $cargl()$          Func   |crv-cargl|
    $casinh()$         Func   |crv-casinh|
    $casinhf()$        Func   |crv-casinhf|
    $casinhl()$        Func   |crv-casinhl|
    $catanh()$         Func   |crv-catanh|
    $catanhf()$        Func   |crv-catanhf|
    $catanhl()$        Func   |crv-catanhl|
    $ccos()$           Func   |crv-ccos|
    $ccosf()$          Func   |crv-ccosf|
    $ccosl()$          Func   |crv-ccosl|
    $ccosh()$          Func   |crv-ccosh|
    $ccoshf()$         Func   |crv-ccoshf|
    $ccoshl()$         Func   |crv-ccoshl|
    $cexp()$           Func   |crv-cexp|
    $cexpf()$          Func   |crv-cexpf|
    $cexpl()$          Func   |crv-cexpl|
    $cimag()$          Func   |crv-cimag|
    $cimagf()$         Func   |crv-cimagf|
    $cimagl()$         Func   |crv-cimagl|
    $clog()$           Func   |crv-clog|
    $clogf()$          Func   |crv-clogf|
    $clogl()$          Func   |crv-clogl|
    $conj()$           Func   |crv-conj|
    $conjf()$          Func   |crv-conjf|
    $conjl()$          Func   |crv-conjl|
    $cpow()$           Func   |crv-cpow|
    $cpowf()$          Func   |crv-cpowf|
    $cpowl()$          Func   |crv-cpowl|
    $cproj()$          Func   |crv-cproj|
    $cprojf()$         Func   |crv-cprojf|
    $cprojl()$         Func   |crv-cprojl|
    $creal()$          Func   |crv-creal|
    $crealf()$         Func   |crv-crealf|
    $creall()$         Func   |crv-creall|
    $csinh()$          Func   |crv-csinh|
    $csin()$           Func   |crv-csin|
    $csinf()$          Func   |crv-csinf|
    $csinl()$          Func   |crv-csinl|
    $csinh()$          Func   |crv-csinh|
    $csinhf()$         Func   |crv-csinhf|
    $csinhl()$         Func   |crv-csinhl|
    $csqrt()$          Func   |crv-csqrt|
    $csqrtf()$         Func   |crv-csqrtf|
    $csqrtl()$         Func   |crv-csqrtl|
    $ctan()$           Func   |crv-ctan|
    $ctanf()$          Func   |crv-ctanf|
    $ctanl()$          Func   |crv-ctanl|
    $ctanh()$          Func   |crv-ctanh|
    $ctanhf()$         Func   |crv-ctanhf|
    $ctanhl()$         Func   |crv-ctanhl|
    $complex$          Macro  |crv-complex|
    $CX_LIMITED_RANGE$ Pragma |crv-CX_LIMITED_RANGE|
    $I$                Macro  |crv-I|
    $imaginary$        Macro  |crv-imaginary|


------------------------------------------------------------------------------
II.3.1  Macros                                                  *crv-libCHMac*


_Complex_I Macro                                              *crv-_Complex_I*
----------------
This macro expands to$const float _Complex$with the complex number "0+1i".


_Imaginary_I Macro                                          *crv-_Imaginary_I*
------------------
This macro is defined only if the compiler supports imaginary types.
If defined, it expands to$_Imaginary$and a constant expression of the type
$const float _Imaginary$with the value "0+1i".


complex Macro                                                    *crv-complex*
-------------
This macro expands to$_Complex$.


I Macro                                                                *crv-I*
-------
This macro either expands to$_Imaginary_I$or$_Complex_I$. If$_Imaginary_I$is
not defined$I$expands to$_Complex_I$.


imaginary Macro                                                *crv-imaginary*
---------------
This macro is defined only if the compiler supports imaginary types.
If defined, it expands to$_Imaginary$and a constant expression of the type
$const float _Imaginary$with the value "0+1i".



------------------------------------------------------------------------------
II.3.2  Pragmas                                                *crv-libCHPrag*


CX_LIMITED_RANGE Pragma                                 *crv-CX_LIMITED_RANGE*
-----------------------
Synopsis~
 $#include <complex.h>$
 $#pragma STDC CX_LIMITED_RANGE on/off-switch$

 $on/off-switch$is$ON$,$OFF$or$DEFAULT$
  
Description~
Complex arithmetic is problematic because of their treatment of infinities
and because of undue overflow and underflow.
If this pragma is on the compiler is informed that the usual mathematical
formulas can be used. If on, the compiler can use this formulas:
  (x + iy)x(u + iv) = (xu - yv) + i(yu + xv)
  
  (x + iy) / ( u + iv) = [(xu + yv) + i(yu - xv)] / (u^2 + v^2)

                  -----------
  | x + iy | =  \| x^2 + y^2

When inside a compound statement, the pragma takes effect from its occurrence
until end of compound statement or until the next$CX_LIMITED_RANGE$is
encountered; at the end of a compound statement the state of the pragma is
restored to its state just before entering that compound statement.
When outside a compound statement, the pragma takes effect from its occurrence
until end of source-file or until the next$CX_LIMITED_RANGE$is encountered.
The default state of this pragma is off.



------------------------------------------------------------------------------
II.3.3  Trigonometric                                          *crv-libCHTrig*


cacos() Functions                        *crv-cacos* *crv-cacosf* *crv-cacosl*
-----------------
Synopsis~
 $#include <complex.h>$
 $double complex cacos(double complex z);$
 $float complex cacosf(float complex z);$
 $long double complex cacosl(long double complex z);$

Return~
return complex arc cosine of z in radians
Values: imaginary is unbounded, real is in the interval [0, PI]

Description~
These functions compute the complex arc cosine of z, with branch cuts outside
the interval [-1, +1] along real axis.



casin() Functions                        *crv-casin* *crv-casinf* *crv-casinl*
-----------------
Synopsis~
 $#include <complex.h>$
 $double complex casin(double complex z);$
 $float complex casinf(float complex z);$
 $long double complex casinl(long double complex z);$

Return~
return complex arc sine of z in radians
Range: imaginary is unbounded, real is in the interval [-PI/2, +PI/2]

Description~
These functions compute the complex arc sine of z, with branch cuts outside
the interval [-1, +1] along real axis



catan() Functions                        *crv-catan* *crv-catanf* *crv-catanl*
-----------------
Synopsis~
 $#include <complex.h>$
 $double complex catan(double complex z);$
 $float complex catanf(float complex z);$
 $long double complex catanl(long double complex z);$

Return~
return complex arc tangent of z in radians
Range: imaginary is unbounded, real is in the interval [-PI/2, +PI/2]

Description~
These functions compute the complex arc tangent of z, with branch cuts outside
the interval [-i, +i] along imaginary axis.



ccos() Functions                            *crv-ccos* *crv-ccosf* *crv-ccosl*
----------------
Synopsis~
 $#include <complex.h>$
 $double complex ccos(double complex z);$
 $float complex ccosf(float complex z);$
 $long double complex ccosl(long double complex z);$

Return~
return complex cosine of z

Description~
These functions compute the complex cosine of z.
The mathematical definition of the complex cosine is:
  cos(z) = 1/2 * (exp(z*i) + exp(-z*i))



csin() Functions                            *crv-csin* *crv-csinf* *crv-csinl*
----------------
Synopsis~
 $#include <complex.h>$
 $double complex csin(double complex z);$
 $float complex csinf(float complex z);$
 $long double complex csinl(long double complex z);$

Return~
return complex sine of z

Description~
These functions compute the complex sine of z.
The mathematical definition of the complex sine is:
  sin(z) = 1/(2*i) * (exp(z*i) - exp(-z*i)) 



ctan() Functions                            *crv-ctan* *crv-ctanf* *crv-ctanl*
----------------
Synopsis~
 $#include <complex.h>$
 $double complex ctan(double complex z);$
 $float complex ctanf(float complex z);$
 $long double complex ctanl(long double complex z);$

Return~
return complex tangent of z

Description~
These functions compute the complex tangent of z.
The mathematical definition of the complex tangent is:
  tan(z) = -i * (exp(z*i) - exp(-z*i)) / (exp(z*i) + exp(-z*i)) 

NOTE: The complex tangent has poles at PI/2 + 2n, where n is an integer. 
$ctan()$may signal overflow if z is too close to a pole.



------------------------------------------------------------------------------
II.3.4  Hyperbolic                                            *crv-libCHHyper*


cacosh() Functions                    *crv-cacosh* *crv-cacoshf* *crv-cacoshl*
------------------
Synopsis~
 $#include <complex.h>$
 $double complex cacosh(double complex z);$
 $float complex cacoshf(float complex z);$
 $long double complex cacoshl(long double complex z);$

Return~
return complex arc hyperbolic cosine of z
Range: real is >= 0, imaginary is [-iPI, +iPI]

Description~
These functions compute the complex arc hyperbolic cosine of z.
Domain: real of z >= 1



casinh() Functions                    *crv-casinh* *crv-casinhf* *crv-casinhl*
------------------
Synopsis~
 $#include <complex.h>$
 $double complex casinh(double complex z);$
 $float complex casinhf(float complex z);$
 $long double complex casinhl(long double complex z);$

Return~
return complex arc hyperbolic sine of z
Range: real is unbounded, imaginary is [-iPI/2, +iPI/2]

Description~
These functions compute the complex arc hyperbolic sine of z.
Domain: imaginary in range [-i, +i]



catanh() Functions                    *crv-catanh* *crv-catanhf* *crv-catanhl*
------------------
Synopsis~
 $#include <complex.h>$
 $double complex catanh(double complex z);$
 $float complex catanhf(float complex z);$
 $long double complex catanhl(long double complex z);$

Return~
return complex arc hyperbolic tangent of z
Range: imaginary is unbounded, real is [-PI/2, +PI/2]

Description~
These functions compute the complex arc hyperbolic tangent of z.
Domain: real in range [-1, +1]



ccosh() Functions                        *crv-ccosh* *crv-ccosfh* *crv-ccoslh*
-----------------
Synopsis~
 $#include <complex.h>$
 $double complex ccosh(double complex z);$
 $float complex ccoshf(float complex z);$
 $long double complex ccoshl(long double complex z);$

Return~
return complex hyperbolic cosine of z

Description~
These functions compute the complex hyperbolic cosine of z.
The mathematical definition of the complex hyperbolic cosine is:
  cosh(z) = 1/2 * (exp(z) + exp(-z))



csinh() Functions                        *crv-csinh* *crv-csinhf* *crv-csinhl*
-----------------
Synopsis~
 $#include <complex.h>$
 $double complex csinh(double complex z);$
 $float complex csinhf(float complex z);$
 $long double complex csinhl(long double complex z);$

Return~
return complex hyperbolic sine of z

Description~
These functions compute the complex hyperbolic sine of z.
The mathematical definition of the complex hyperbolic sine is:
  sinh(z) = 1/2 * (exp(z) - exp(-z)) / 2



ctanh() Functions                        *crv-ctanh* *crv-ctanhf* *crv-ctanhl*
-----------------
Synopsis~
 $#include <complex.h>$
 $double complex ctanh(double complex z);$
 $float complex ctanhf(float complex z);$
 $long double complex ctanhl(long double complex z);$

Return~
return complex hyperbolic tangent of z

Description~
These functions compute the complex hyperbolic tangent of z.
The mathematical definition of the complex hyperbolic tangent is:
  tanh(z) = sinh(z) / cosh(z)



------------------------------------------------------------------------------
II.3.5  Exponential & Logarithmic                            *crv-libCHExpLog*


cexp() Functions                            *crv-cexp* *crv-cexpf* *crv-cexpl*
----------------
Synopsis~
 $#include <complex.h>$
 $double complex cexp(double complex z);$
 $float complex cexpf(float complex z);$
 $long double complex cexpl(long double complex z);$

Return~
return complex base e exponential of z

Description~
These functions compute e (the base of natural logarithms) raised to the power
of z. Mathematically, this corresponds to the value 

  exp(z) = exp(creal(z)) * (cos(cimag(z)) + I * sin(cimag(z)))



clog() Functions                            *crv-clog* *crv-clogf* *crv-clogl*
----------------
Synopsis~
 $#include <complex.h>$
 $double complex clog(double complex z);$
 $float complex clogf(float complex z);$
 $long double complex clogl(long double complex z);$

Return~
return complex natural logarithm of z
Range: real > 0

Description~
These functions compute the complex natural logarithm of z (base e).
Domain: imaginary is [-iPI, +iPI], real is unbounded

The mathematical definition is:
  log(z) = log(cabs(z)) + I * carg(z)



------------------------------------------------------------------------------
II.3.6  Power & Absolute                                      *crv-libCHPower*


cabs() Functions                            *crv-cabs* *crv-cabsf* *crv-cabsl*
----------------
Synopsis~
 $#include <complex.h>$
 $double cabs(double complex z);$
 $float cabsf(float complex z);$
 $long double cabsl(long double complex z);$

Return~
return absolute value of z

Description~
These functions compute the absolute value of the complex number z.

                      ------------------------
  absolute value =  \|creal(z)^2 + cimag(z)^2



cpow() Functions                            *crv-cpow* *crv-cpowf* *crv-cpowl*
----------------
Synopsis~
 $#include <complex.h>$
 $double complex cpow(double complex base, double complex power);$
 $float complex cpowf(float complex base, double complex power);$
 $long double complex cpowl(long double complex base,$
 $                          long doubl complex power);$

Return~
return complex power of z

Description~
These functions compute the complex power function x^y
($base$raised to the power$power$).

This is equivalent to:
  exp(y * log(x))



csqrt() Functions                        *crv-csqrt* *crv-csqrtf* *crv-csqrtl*
-----------------
Synopsis~
 $#include <complex.h>$
 $double complex csqrt(double complex z);$
 $float complex csqrtf(float complex z);$
 $long double complex csqrtl(long double complex z);$

Return~
return complex square root of z
Range: real >= 0

Description~
These functions compute the complex square root of z.
Domain: imaginary unbounded, real >= 0



------------------------------------------------------------------------------
II.3.7  Manipulating                                           *crv-libCHMani*


carg() Functions                            *crv-carg* *crv-cargf* *crv-cargl*
----------------
Synopsis~
 $#include <complex.h>$
 $double carg(double complex z);$
 $float cargf(float complex z);$
 $long double cargl(long double complex z);$

Return~
return argument of z
Range: [-PI, +PI]

Description~
These functions compute the argument of the complex number z.
The argument of a complex number is the angle in the complex plane between the
positive real axis and a line passing through zero and the number.
Domain: branch cut along the positive real axis



cimag() Functions                        *crv-cimag* *crv-cimagf* *crv-cimagl*
-----------------
Synopsis~
 $#include <complex.h>$
 $double cimag(double complex z);$
 $float cimagf(float complex z);$
 $long double cimagl(long double complex z);$

Return~
return imaginary part of z

Description~
These functions compute the imaginary part of the complex number z.



conj() Functions                            *crv-conj* *crv-conjf* *crv-conjl*
----------------
Synopsis~
 $#include <complex.h>$
 $double complex conj(double complex z);$
 $float complex conjf(float complex z);$
 $long double complex conjl(long double complex z);$

Return~
return complex conjugate value of z

Description~
These functions compute the complex conjugate of the complex number z.
The conjugate of a complex number has the same real part and a negated
imaginary part. In other words, conj(a + bi) = a + -bi. 



cproj() Functions                        *crv-cproj* *crv-cprojf* *crv-cprojl*
-----------------
Synopsis~
 $#include <complex.h>$
 $double complex cproj(double complex z);$
 $float complex cprojf(float complex z);$
 $long double complex cprojl(long double complex z);$

Return~
return value of projection onto the Riemann sphere

Description~
These functions compute the projection of the complex value z onto the Riemann
sphere. Values with a infinite imaginary part are projected to positive
infinity on the real axis, even if the real part is NaN. If the real part is
infinite, the result is equivalent to 
   INFINITY + I * copysign (0.0, cimag(z))



creal() Functions                        *crv-creal* *crv-crealf* *crv-creall*
-----------------
Synopsis~
 $#include <complex.h>$
 $double creal(double complex z);$
 $float crealf(float complex z);$
 $long double creall(long double complex z);$

Return~
return real part of z

Description~
These functions compute the real part of the complex number z.




==============================================================================
II.4  <ctype.h> Character                                      *crv-libCtypeH*


This header declares functions useful for case mapping and classifying
characters.

Quicklink:
    $isalnum()$   Func   |crv-isalnum|
    $isalpha()$   Func   |crv-isalpha|
    $isblank()$   Func   |crv-isblank|
    $iscntrl()$   Func   |crv-iscntrl|
    $isdigit()$   Func   |crv-isdigit|
    $isgraph()$   Func   |crv-isgraph|
    $islower()$   Func   |crv-islower|
    $isprint()$   Func   |crv-isprint|
    $ispunct()$   Func   |crv-ispunct|
    $isspace()$   Func   |crv-isspace|
    $isupper()$   Func   |crv-isupper|
    $isxdigit()$  Func   |crv-isxdigit|
    $tolower()$   Func   |crv-tolower|
    $toupper()$   Func   |crv-toupper|



------------------------------------------------------------------------------
II.4.1  Character Handling                               *crv-libCharHandling*

Each of the functions in this section tests for membership in a particular
class of characters; each has a name starting with is. Each of them takes
one argument, which is a character to test, and returns an int which is
treated as a boolean value. The character argument is passed as an int,
and it may be the constant value EOF instead of a real character. 

The attributes of any given character can vary between locales.


$int isalnum(int c);$                                            *crv-isalnum*
   Returns true if c is an alphanumeric character (a letter or number); in
   other words, if either$isalpha$or$isdigit$is true of a character, then
  $isalnum$ is also true.


$int isalpha(int c);$                                            *crv-isalpha*
   Returns true if c is an alphabetic character (a letter). If$islower$or
  $isupper$is true of a character, then$isalpha$is also true. 
   It returns also true, if c is one of a local-specific set of characters for
   which none of$iscntrl$,$isdigt$,$ispunct$ or$isspcace$is true.
   
   In some locales, there may be additional characters for which isalpha
   is true - letters which are neither upper case nor lower case. But in 
   the standard C locale, there are no such additional characters. 


$int isblank(int c);$                                            *crv-isblank*
   Returns true if c is a blank character; that is, a space or a tab.


$int iscntrl(int c);$                                            *crv-iscntrl*
   Returns true if c is a control character (that is, a character that is
   not a printing character). 


$int isdigit(int c);$                                            *crv-isdigit*
   Returns true if c is a decimal digit (0 through 9). 


$int isgraph(int c);$                                            *crv-isgraph*
   Returns true if c is a graphic character; that is any printing character
   except a space character.


$int islower(int c);$                                            *crv-islower*
   Returns true if c is a lower-case letter or is one of a local-specific set
   of characters for which none of$iscntrl$,$isdigt$,$ispunct$ or$isspcace$is
   true.


$int isprint(int c);$                                            *crv-isprint*
   Returns true if c is a printing character. Printing characters include
   all the graphic characters, plus the space (' ') character. 


$int ispunct(int c);$                                            *crv-ispunct*
   Returns true if c is a punctuation character. This means any printing 
   character for that is neither$isalnum$nor$isspace$is true (no 
   alphanumeric and no space character).


$int isspace(int c);$                                            *crv-isspace*
   Returns true if c is a whitespace character. In the standard "C" locale, 
  $isspace$returns true for only the standard whitespace characters: 
     ' '   space 
     '\f'  formfeed 
     '\n'  newline 
     '\r'  carriage return 
     '\t'  horizontal tab 
     '\v'  vertical tab 


$int isupper(int c);$                                            *crv-isupper*
   Returns true if c is an upper-case letter or is one of a local-specific set
   of characters for which none of$iscntrl$,$isdigt$,$ispunct$ or$isspcace$is
   true.


$int isxdigit(int c);$                                          *crv-isxdigit*
   Returns true if c is a hexadecimal digit. Hexadecimal digits include the
   normal decimal digits 0 through 9 and the letters A through F and 
   a through f. 




------------------------------------------------------------------------------
II.4.2  Character Mapping                                 *crv-libCharMapping*

This section explains the functions for performing case mappings on
characters.
These functions take one argument of type int, which is the character to
convert, and return the converted character as an int. If the conversion is
not applicable to the argument given, the argument is returned unchanged.


$int tolower(int c);$                                            *crv-tolower*
   If c is an upper-case letter,$tolower$returns the corresponding lower-case
   letter. If c is not an upper-case letter, c is returned unchanged.
   
$int toupper(int c);$                                            *crv-toupper*
   If c is a lower-case letter,$toupper$returns the corresponding upper-case
   letter. If c is not an lower-case letter, c is returned unchanged.




==============================================================================
II.5  <errno.h> Error Codes                                    *crv-libErrnoH*

This header file defines macros used for reporting of error conditions.
All macros expand to integer constant expressions of type$int$with distinct
positive values.

Additional macro definitions may be specified by the implementation. They
begin with E followed by digits or begin with E followed by uppercase letters.


EDOM Macro                                                          *crv-EDOM*
----------
Domain error; used by mathematical functions when an argument value does not
fall into the domain over which the function is defined.


EILSEQ Macro                                                      *crv-EILSEQ*
------------
While decoding a multibyte character the function came along an invalid or an
incomplete sequence of bytes or the given wide character is invalid.


ERANGE Macro                                                      *crv-ERANGE*
------------
Range error; used by mathematical functions when the result value is not
representable because of overflow or underflow.


errno Macro/Variable                                               *crv-errno*
--------------------
$errno$is either a macro or an external variable of type int (implementation-
defined).

The$errno$variable is used for holding implementation-defined error codes 
reported by library routines. See above for error code macros specified by the
standard C language.
The value of$errno$is set to 0 at program startup, but is never set to 0
by any library function. Therefore,$errno$should be set to 0 before calling a
library function and then inspected afterward.




------------------------------------------------------------------------------
II.6  <fenv.h> FPU Status                                       *crv-libFenvH*

This header declares types, macros and functions to provide access to the
floating-point environment (floating-point status word and control modes).

Quicklink:
    $FE_ALL_EXCEPT$     Macro  |crv-FE_ALL_EXCEPT|
    $FE_DIVBYZERO$      Macro  |crv-FE_DIVBYZERO|
    $FE_DOWNWARD$       Macro  |crv-FE_DOWNWARD|
    $FE_INEXACT$        Macro  |crv-FE_INEXACT|
    $FE_INVALID$        Macro  |crv-FE_INVALID|
    $FE_OVERFLOW$       Macro  |crv-FE_OVERFLOW|
    $FE_TONEAREST$      Macro  |crv-FE_TONEAREST|
    $FE_TOWARDZERO$     Macro  |crv-FE_TOWARDZERO|
    $FE_UNDERFLOW$      Macro  |crv-FE_UNDERFLOW|
    $FE_UPWARD$         Macro  |crv-FE_UPWARD|
    $FENV_ACCESS$       Pragma |crv-FENV_ACCESS|
    $feclearexcept()$   Func   |crv-feclearexcept|
    $fegetenv()$        Func   |crv-fegetenv|
    $fegetexceptflag()$ Func   |crv-fegetexceptflag|
    $fegetround()$      Func   |crv-fegetround|
    $feholdexcept()$    Func   |crv-feholdexcept|
    $feraiseexcept()$   Func   |crv-feraiseexcept|
    $fesetenv()$        Func   |crv-fesetenv|
    $fesetexceptflag()$ Func   |crv-fesetexceptflag|
    $fesetround()$      Func   |crv-fesetround|
    $fetestexcept()$    Func   |crv-fetestexcept|
    $feupdateenv()$     Func   |crv-feupdateenv|



------------------------------------------------------------------------------
II.6.1  Pragmas                                                *crv-libFHPrag*

FENV_ACCESS Pragma                                           *crv-FENV_ACCESS*
------------------
Synopsis~
 $#include <fenv.h>$
 $#pragma STDC FENV_ACCESS on/off-switch$
 
 $on/off-switch$is$ON$,$OFF$or$DEFAULT$

Description~
This pragma provides a means to inform the compiler when a program might
access the floating-point environment (FPU or software emulation of FP) to
test status flags or run under non-default control modes. An "off"-state 
signals that a program does not test status flags and does not run under
non-default control modes. Knowing this the compiler can do better
optimization that could subvert flag tests or mode changes.

When inside a compound statement, the pragma takes effect from its occurrence
until end of compound statement or until the next$FENV_ACCESS$is  encountered;
at the end of a compound statement the state of the pragma is restored to its
state just before entering that compound statement.
When outside a compound statement, the pragma takes effect from its occurrence
until end of source-file or until the next$FENV_ACCESS$is encountered.
The default state of this pragma is implementation-defined.



------------------------------------------------------------------------------
II.6.2  Exceptions                                       *crv-libFHExceptions*

The following functions allow to query and manipulate the floating-point
status word. They can be used to check for untrapped exceptions when it's
convenient, rather than worrying about them in the middle of a calculation. 

The macros below represent the various IEEE 754 exceptions. Not all FPUs 
report all the different exceptions. Each constant is defined if and only if
the FPU compiling for supports that exception.$#ifdef$can be used to test for
FPU support.
Additional macro definitions may be specified by the implementation. They
begin with FE_ followed by uppercase letters.


FE_INEXACT Macro                                              *crv-FE_INEXACT*
----------------
The inexact exception. 


FE_DIVBYZERO Macro                                          *crv-FE_DIVBYZERO*
------------------
The divide by zero exception. 


FE_UNDERFLOW Macro                                          *crv-FE_UNDERFLOW*
------------------
The underflow exception. 


FE_OVERFLOW Macro                                            *crv-FE_OVERFLOW*
-----------------
The overflow exception. 


FE_INVALID Macro                                              *crv-FE_INVALID*
----------------
The invalid exception. 


FE_ALL_EXCEPT Macro                                        *crv-FE_ALL_EXCEPT*
-------------------
This macro is the bitwise OR of all exception macros which are supported by
the FP implementation.


feclearexcept() Function                                   *crv-feclearexcept*
------------------------
Synopsis~
 $#include <fenv.h>$
 $int feclearexcept(int excepts);$
 
Return~
zero in case the operation was successful, otherwise a non-zero value
   
Description~
This function clears all of the supported exception flags indicated by
$excepts$.


fegetexceptflag() Function                               *crv-fegetexceptflag*
--------------------------
Synopsis~
 $#include <fenv.h>$
 $int fegetexceptflag(fexcept_t *flagp, int excepts);$
 
Return~
zero in case the operation was successful, otherwise a non-zero value
   
Description~
This function attempts to store in the variable pointed to by$flagp$an 
implementation-defined value representing the current setting of the
exception flags indicated by$excepts$.


feraiseexcept() Function                                   *crv-feraiseexcept*
------------------------
Synopsis~
 $#include <fenv.h>$
 $int feraiseexcept(int excepts);$
 
Return~
zero in case the operation was successful, otherwise a non-zero value
   
Description~
This function attempts to raises the supported exceptions indicated by
$excepts$. If more than one exception bit in$excepts$is set the order in which
the exceptions are raised is undefined except that overflow ($FE_OVERFLOW$) or
underflow ($FE_UNDERFLOW$) are raised before inexact ($FE_INEXACT$). Whether
for overflow or underflow the inexact exception is also raised is also
implementation dependent. 


fesetexceptflag() Function                               *crv-fesetexceptflag*
--------------------------
Synopsis~
 $#include <fenv.h>$
 $int fesetexceptflag(fexcept_t *flagp, int excepts);$
 
Return~
zero in case the operation was successful, otherwise a non-zero value
   
Description~
This function attempts to restore the flags for the exceptions indicated by
$excepts$to the values stored in the variable pointed to by $flagp$.


fetestexcept() Function                                     *crv-fetestexcept*
-----------------------
Synopsis~
 $#include <fenv.h>$
 $int fetestexcept(int excepts);$
 
Return~
flags which are set
   
Description~
Test whether the exception flags indicated by the parameter$except$are
currently set. If any of them are, a nonzero value is returned which specifies
which exceptions are set. Otherwise the result is zero.



------------------------------------------------------------------------------
II.6.3  Rounding                                           *crv-libFHRounding*

Floating-point calculations are carried out internally with extra precision,
and then rounded to fit into the destination type. This ensures that results
are as precise as the input data. IEEE 754 defines four possible rounding
modes:

- Round to nearest
  This is the default mode. It should be used unless there is a specific need
  for one of the others. In this mode results are rounded to the nearest
  representable value. If the result is midway between two representable 
  values, the even representable is chosen. Even here means the lowest-order
  bit is zero. This rounding mode prevents statistical bias and guarantees
  numeric stability: round-off errors in a lengthy calculation will remain
  smaller than half of$FLT_EPSILON$.

- Round toward plus Infinity
  All results are rounded to the smallest representable value which is greater
  than the result. 

- Round toward minus Infinity
  All results are rounded to the largest representable value which is less
  than the result. 

- Round toward zero
  All results are rounded to the largest representable value whose magnitude
  is less than that of the result. In other words, if the result is negative
  it is rounded up; if it is positive, it is rounded down. 

For examples of effects see |crv-FLT_ROUNDS|.

$<fenv.h>$defines constants which you can use to refer to the various rounding
modes. Each one will be defined if and only if the FPU supports the
corresponding rounding mode. 


FE_TONEAREST Macro                                          *crv-FE_TONEAREST*
------------------
Round to nearest. 


FE_UPWARD Macro                                                *crv-FE_UPWARD*
---------------
Round toward +&infin;. 


FE_DOWNWARD Macro                                            *crv-FE_DOWNWARD*
-----------------
Round toward -&infin;. 


FE_TOWARDZERO Macro                                        *crv-FE_TOWARDZERO*
-------------------
Round toward zero. 


Underflow is an unusual case. Normally, IEEE 754 floating point numbers are 
always normalized. Numbers smaller than 2^r (where r is the minimum exponent
cannot be represented as normalized numbers. Rounding all such numbers to zero
or 2^r would cause some algorithms to fail at 0. Therefore, they are left in
denormalized form. That produces loss of precision, since some bits of the
mantissa are stolen to indicate the decimal point. 

If a result is too small to be represented as a denormalized number, it is
rounded to zero. However, the sign of the result is preserved; if the
calculation was negative, the result is negative zero. Negative zero can also
result from some operations on infinity, such as 4/-&infin;. Negative zero
behaves identically to zero except when the copysign or signbit functions are
used to check the sign bit directly. 


At any time one of the above four rounding modes is selected. The following
functions allow to get and set the rounding modes:


fegetround() Function                                         *crv-fegetround*
---------------------
Synopsis~
 $#include <fenv.h>$
 $int fegetround(void);$
 
Return~
currently selected rounding mode
   
Description~
Returns the currently selected rounding mode, represented by one of the values
of the defined rounding mode macros.


fesetround() Function                                         *crv-fesetround*
---------------------
Synopsis~
 $#include <fenv.h>$
 $int fesetround(int round);$
 
Return~
zero if it changed the rounding mode, a nonzero value if the mode is not
supported

Description~
Changes the currently selected rounding mode to$round$. If$round$does not
correspond to one of the supported rounding modes nothing is changed.

You should avoid changing the rounding mode if possible. It can be an
expensive operation; also, some hardware requires you to compile your
program differently for it to work. The resulting code may run slower. See
your compiler documentation for details.




------------------------------------------------------------------------------
II.6.4  Environment                                             *crv-libFHEnv*

The functions in this section manage the floating-point environment.

                                                                 *crv-fentv_t*
The functions to save and restore the floating-point environment all use a
variable of type$fenv_t$to store information. This type is defined in
$<fenv.h>$. Its size and contents are implementation-defined. This variable
should not be manipulated directly.


fegetenv() Function                                             *crv-fegetenv*
-------------------
Synopsis~
 $#include <fenv.h>$
 $int fegetenv(fenv_t *envp);$
 
Return~
zero in case the operation was successful, otherwise a non-zero value

Description~
Store the floating-point environment in the variable pointed to by$envp$.


feholdexcept() Function                                     *crv-feholdexcept*
-----------------------
Synopsis~
 $#include <fenv.h>$
 $int feholdexcept(fenv_t *envp);$
 
Return~
zero in case the operation was successful, otherwise a non-zero value

Description~
Store the current floating-point environment in the object pointed to by
$envp$. Then clear all exception flags, and set the FPU to trap no exceptions.
Not all FPUs support trapping no exceptions; if$feholdexcept$cannot set this
mode, it returns nonzero value.


fesetenv() Function                                             *crv-fesetenv*
-------------------
Synopsis~
 $#include <fenv.h>$
 $int fesetenv(const fenv_t *envp);$
 
Return~
zero in case the operation was successful, otherwise a non-zero value

Description~
Set the floating-point environment to that described by$envp$.


feupdateenv() Function                                       *crv-feupdateenv*
----------------------
Synopsis~
 $#include <fenv.h>$
 $int feupdateenv(const fenv_t *envp);$
 
Return~
zero in case the operation was successful, otherwise a non-zero value

Description~
Like$fesetenv()$, this function sets the floating-point environment to that
described by$envp$. However, if any exceptions were flagged in the status word
before$feupdateenv()$was called, they remain flagged after the call. In other
words, after$feupdateenv()$is called, the status word is the bitwise OR of the
previous status word and the one saved in$envp$.




==============================================================================
II.7  <float.h> Floating Point                                 *crv-libFloatH*

This header file defines several macros that expand to various
implementation-specific limits and parameters describing floating-point
properties. 
NOTE: The values are platform- and implementation-specific.The ISO C standard
specifies minimum and maximum values for most of these parameters.

Macro names starting with FLT_ refer to the float type, while names beginning
with DBL_ refer to the double type and names beginning with LDBL_ refer to the
long double type.

Quicklink:
    $FLT_DIG  $       Macro  |crv-FLT_DIG|
    $FLT_EPSILON  $   Macro  |crv-FLT_EPSILON|
    $FLT_MANT_DIG  $  Macro  |crv-FLT_MANT_DIG|
    $FLT_MAX  $       Macro  |crv-FLT_MAX|
    $FLT_MAX_10_EXP $ Macro  |crv-FLT_MAX_10_EXP|
    $FLT_MAX_EXP  $   Macro  |crv-FLT_MAX_EXP|
    $FLT_MIN  $       Macro  |crv-FLT_MIN|
    $FLT_MIN_10_EXP  $Macro  |crv-FLT_MIN_10_EXP|
    $FLT_MIN_EXP  $   Macro  |crv-FLT_MIN_EXP|
    $FLT_RADIX $      Macro  |crv-FLT_RADIX|
    $FLT_ROUNDS $     Macro  |crv-FLT_ROUNDS|
    $DBL_DIG  $       Macro  |crv-DBL_DIG|
    $DBL_EPSILON  $   Macro  |crv-DBL_EPSILON|
    $DBL_MANT_DIG  $  Macro  |crv-DBL_MANT_DIG|
    $DBL_MAX  $       Macro  |crv-DBL_MAX|
    $DBL_MAX_10_EXP $ Macro  |crv-DBL_MAX_10_EXP|
    $DBL_MAX_EXP  $   Macro  |crv-DBL_MAX_EXP|
    $DBL_MIN  $       Macro  |crv-DBL_MIN|
    $DBL_MIN_10_EXP  $Macro  |crv-DBL_MIN_10_EXP|
    $DBL_MIN_EXP  $   Macro  |crv-DBL_MIN_EXP|
    $LDBL_DIG $       Macro  |crv-LDBL_DIG|
    $LDBL_EPSILON $   Macro  |crv-LDBL_EPSILON|
    $LDBL_MANT_DIG $  Macro  |crv-LDBL_MANT_DIG|
    $LDBL_MAX $       Macro  |crv-LDBL_MAX|
    $LDBL_MAX_10_EXP$ Macro  |crv-LDBL_MAX_10_EXP|
    $LDBL_MAX_EXP $   Macro  |crv-LDBL_MAX_EXP|
    $LDBL_MIN $       Macro  |crv-LDBL_MIN|
    $LDBL_MIN_10_EXP $Macro  |crv-LDBL_MIN_10_EXP|
    $LDBL_MIN_EXP $   Macro  |crv-LDBL_MIN_EXP|



FLT_ROUNDS Macro                                              *crv-FLT_ROUNDS*
----------------
This value characterizes the rounding mode for floating point addition. The
following values indicate standard rounding modes: 

    Value | Mode
  --------+----------------------------------------------------------------
     -1   | the mode is indeterminable
      0   | rounding is towards zero, see |crv-libFHRounding|
      1   | rounding is to the nearest number, see |crv-libFHRounding|
      2   | rounding is towards positive infinity, see |crv-libFHRounding|
      3   | rounding is towards negative infinity, see |crv-libFHRounding|

Any other value represents a machine-dependent nonstandard rounding mode. 

On most machines, the value is 1, in accordance with the IEEE standard for
floating point. 

Here is a table showing how certain values round for each possible value
of$FLT_ROUNDS$, if the other aspects of the representation match the IEEE
single-precision standard:

        Value   |   0  |   1         |    2        |    3
    ------------+------+-------------+-------------+------------- 
     1.00000003 |  1.0 |  1.0        |  1.00000012 |  1.0
     1.00000007 |  1.0 |  1.00000012 |  1.00000012 |  1.0
    -1.00000003 | -1.0 | -1.0        | -1.0        | -1.00000012
    -1.00000007 | -1.0 | -1.00000012 | -1.0        | -1.00000012



FLT_RADIX Macro                                                *crv-FLT_RADIX*
---------------
This is the value of the base, or radix, of the exponent representation. In
the very most times the value is 2 (except IBM 360 and derivatives).


FLT_MANT_DIG  Macro                                         *crv-FLT_MANT_DIG*
DBL_MANT_DIG  Macro                                         *crv-DBL_MANT_DIG*
LDBL_MANT_DIG Macro                                        *crv-LDBL_MANT_DIG*
------------------
This is the number of base-$FLT_RADIX$digits in the floating point mantissa.


FLT_DIG  Macro                                                   *crv-FLT_DIG*
DBL_DIG  Macro                                                   *crv-DBL_DIG* 
LDBL_DIG Macro                                                  *crv-LDBL_DIG* 
--------------
This is the number of decimal digits of precision.
To satisfy standard C, the values supposed to be at least:
  FLT_DIG  >=  6
  DBL_DIG  >= 10
  LDBL_DIG >= 10

Technically, if p and b are the precision and base (respectively) for the
representation, then the decimal precision q is the maximum number of decimal
digits such that any floating point number with q base 10 digits can be
rounded to a floating point number with p base b digits and back again,
without change to the q decimal digits. 


FLT_MIN_EXP  Macro                                           *crv-FLT_MIN_EXP*
DBL_MIN_EXP  Macro                                           *crv-DBL_MIN_EXP*
LDBL_MIN_EXP Macro                                          *crv-LDBL_MIN_EXP*
------------------
This is the minimum negative integer value for an exponent in base$FLT_RADIX$.


FLT_MIN_10_EXP  Macro                                     *crv-FLT_MIN_10_EXP*
DBL_MIN_10_EXP  Macro                                     *crv-DBL_MIN_10_EXP*
LDBL_MIN_10_EXP Macro                                    *crv-LDBL_MIN_10_EXP*
---------------------
This is the minimum negative integer value for an exponent in base 10.
To satisfy standard C, the values supposed to be at least:
  FLT_MIN_10_EXP  <= -37
  DBL_MIN_10_EXP  <= -37
  LDBL_MIN_10_EXP <= -37


FLT_MAX_EXP  Macro                                           *crv-FLT_MAX_EXP*
DBL_MAX_EXP  Macro                                           *crv-DBL_MAX_EXP*
LDBL_MAX_EXP Macro                                          *crv-LDBL_MAX_EXP*
------------------
This is the maximum integer value for an exponent in base$FLT_RADIX$.


FLT_MAX_10_EXP  Macro                                     *crv-FLT_MAX_10_EXP*
DBL_MAX_10_EXP  Macro                                     *crv-DBL_MAX_10_EXP*
LDBL_MAX_10_EXP Macro                                    *crv-LDBL_MAX_10_EXP*
---------------------
This is the maximum integer value for an exponent in base 10.
To satisfy standard C, the values supposed to be at least:
  FLT_MAX_10_EXP  >= -37
  DBL_MAX_10_EXP  >= -37
  LDBL_MAX_10_EXP >= -37



FLT_MAX  Macro                                                   *crv-FLT_MAX*
DBL_MAX  Macro                                                   *crv-DBL_MAX*
LDBL_MAX Macro                                                  *crv-LDBL_MAX*
--------------
The value is the maximum finite number representable.
To satisfy standard C, the values supposed to be at least:
  FLT_MAX  >= 1E+37
  DBL_MAX  >= 1E+37
  LDBL_MAX >= 1E+37

The smallest representable number is -FLT_MAX, -DBL_MAX, -LDBL_MAX.


FLT_MIN  Macro                                                   *crv-FLT_MIN*
DBL_MIN  Macro                                                   *crv-DBL_MIN*
LDBL_MIN Macro                                                  *crv-LDBL_MIN*
--------------
The value is the minimum number representable.
To satisfy standard C, the values supposed to be at least:
  FLT_MIN  <= 1E-37
  DBL_MIN  <= 1E-37
  LDBL_MIN <= 1E-37


FLT_EPSILON  Macro                                           *crv-FLT_EPSILON*
DBL_EPSILON  Macro                                           *crv-DBL_EPSILON*
LDBL_EPSILON Macro                                          *crv-LDBL_EPSILON*
------------------
This is the maximum positive floating point number such that
1.0 +$FLT_EPSILON$!= 1.0 is true (least significant digit representable).

To satisfy standard C, the values supposed to be at least:
  FLT_EPSILON  >= 1E-5
  DBL_EPSILON  >= 1E-9
  LDBL_EPSILON >= 1E-9



==============================================================================
II.8  <inttypes.h> Absolute Value                           *crv-libInttypesH*

This header extends the$<stdint.h>$header (->|crv-libStdintH|). It provides
macros for format conversion of integer types and provides functions for
manipulating greatest-width integer types.

Quicklink:
    $imaxdiv_t$  Type   |crv-imaxdiv_t|
    $imaxabs$    Func   |crv-imaxabs|
    $imaxdiv$    Func   |crv-imaxdiv|

    $PRIdN$      Macro  |crv-PRIdN|
    $PRIdLEASTN$ Macro  |crv-PRIdLEASTN|
    $PRIdFASTN$  Macro  |crv-PRIdFASTN|
    $PRIdMAX$    Macro  |crv-PRIdMAX|
    $PRIdPTR$    Macro  |crv-PRIdPTR|

    $PRIiN$      Macro  |crv-PRIiN|
    $PRIiLEASTN$ Macro  |crv-PRIiLEASTN|
    $PRIiFASTN$  Macro  |crv-PRIiFASTN|
    $PRIiMAX$    Macro  |crv-PRIiMAX|
    $PRIiPTR$    Macro  |crv-PRIiPTR|

    $PRIoN$      Macro  |crv-PRIoN|
    $PRIoLEASTN$ Macro  |crv-PRIoLEASTN|
    $PRIoFASTN$  Macro  |crv-PRIoFASTN|
    $PRIoMAX$    Macro  |crv-PRIoMAX|
    $PRIoPTR$    Macro  |crv-PRIoPTR|

    $PRIuN$      Macro  |crv-PRIuN|
    $PRIuLEASTN$ Macro  |crv-PRIuLEASTN|
    $PRIuFASTN$  Macro  |crv-PRIuFASTN|
    $PRIuMAX$    Macro  |crv-PRIuMAX|
    $PRIuPTR$    Macro  |crv-PRIuPTR|

    $PRIxN$      Macro  |crv-PRIxN|
    $PRIxLEASTN$ Macro  |crv-PRIxLEASTN|
    $PRIxFASTN$  Macro  |crv-PRIxFASTN|
    $PRIxMAX$    Macro  |crv-PRIxMAX|
    $PRIxPTR$    Macro  |crv-PRIxPTR|

    $PRIXN$      Macro  |crv-PRIXN|
    $PRIXLEASTN$ Macro  |crv-PRIXLEASTN|
    $PRIXFASTN$  Macro  |crv-PRIXFASTN|
    $PRIXMAX$    Macro  |crv-PRIXMAX|
    $PRIXPTR$    Macro  |crv-PRIXPTR|

    $SCNdN$      Macro  |crv-SCNdN|
    $SCNdLEASTN$ Macro  |crv-SCNdLEASTN|
    $SCNdFASTN$  Macro  |crv-SCNdFASTN|
    $SCNdMAX$    Macro  |crv-SCNdMAX|
    $SCNdPTR$    Macro  |crv-SCNdPTR|

    $SCNiN$      Macro  |crv-SCNiN|
    $SCNiLEASTN$ Macro  |crv-SCNiLEASTN|
    $SCNiFASTN$  Macro  |crv-SCNiFASTN|
    $SCNiMAX$    Macro  |crv-SCNiMAX|
    $SCNiPTR$    Macro  |crv-SCNiPTR|

    $SCNoN$      Macro  |crv-SCNoN|
    $SCNoLEASTN$ Macro  |crv-SCNoLEASTN|
    $SCNoFASTN$  Macro  |crv-SCNoFASTN|
    $SCNoMAX$    Macro  |crv-SCNoMAX|
    $SCNoPTR$    Macro  |crv-SCNoPTR|

    $SCNuN$      Macro  |crv-SCNuN|
    $SCNuLEASTN$ Macro  |crv-SCNuLEASTN|
    $SCNuFASTN$  Macro  |crv-SCNuFASTN|
    $SCNuMAX$    Macro  |crv-SCNuMAX|
    $SCNuPTR$    Macro  |crv-SCNuPTR|

    $SCNxN$      Macro  |crv-SCNxN|
    $SCNxLEASTN$ Macro  |crv-SCNxLEASTN|
    $SCNxFASTN$  Macro  |crv-SCNxFASTN|
    $SCNxMAX$    Macro  |crv-SCNxMAX|
    $SCNxPTR$    Macro  |crv-SCNxPTR|

    $strtoimax$  Func   |crv-strtoimax|
    $strtoumax$  Func   |crv-strtoumax|
    $wcstoimax$  Func   |crv-wcstoimax|
    $wcstoumax$  Func   |crv-wcstoumax|


Macros                                              *crv-__STDC_FORMAT_MACROS*
------
The following macros expand to a string (in most cases a single character)
containing a conversion specifier suitable for use within format arguments
of formated input/output functions, like$printf()$or$scanf()$.
They are only defined when$__STDC_FORMAT_MACROS$is defined before including
$<inttypes.h>$.
For each type declared in$<stdint.h>$, corresponding macros for conversion
specifiers for use with the formatted input/output functions are defined.

The macro names have a prefix PRI for the printf family or SCN for the
scanf family functions followed by the conversion specifier, followed by name
that is similar to the type name this macro is for, followed by a number N.
The number N represents the width of the type as specified in$<stdint.h>.$

Example: The macro$PRIxFAST32$can be used in a format string to print an
integer value of type$int_fast32_t$in hexedecimal format ('x').

Usage see example below.


Format Specifiers for ..printf
------------------------------

Signed Integers:
$PRIdN$      width N, decimal notation                             *crv-PRIdN*
$PRIdLEASTN$ minimum width N, decimal notation                *crv-PRIdLEASTN*
$PRIdFASTN$  width N, fast to operate with, decimal not.       *crv-PRIdFASTN*
$PRIdMAX$    type$intmax_t$, decimal notation                    *crv-PRIdMAX*
$PRIdPTR$    type$intptr_t$, decimal notation                    *crv-PRIdPTR*

$PRIiN$      width N, decimal notation                             *crv-PRIiN*
$PRIiLEASTN$ minimum width N, decimal notation                *crv-PRIiLEASTN*
$PRIiFASTN$  width N, fast to operate with, decimal not.       *crv-PRIiFASTN*
$PRIiMAX$    type$intmax_t$, decimal notation                    *crv-PRIiMAX*
$PRIiPTR$    type$intptr_t$, decimal notation                    *crv-PRIiPTR*

Unsigned Integers:
$PRIoN$      width N, octal notation                               *crv-PRIoN*
$PRIoLEASTN$ minimum width N, octal notation                  *crv-PRIoLEASTN*
$PRIoFASTN$  width N, fast to operate with, octal not.         *crv-PRIoFASTN*
$PRIoMAX$    type$intmax_t$, octal notation                      *crv-PRIoMAX*
$PRIoPTR$    type$intptr_t$, octal notation                      *crv-PRIoPTR*

$PRIuN$      width N, decimal notation                             *crv-PRIuN*
$PRIuLEASTN$ minimum width N, decimal notation                *crv-PRIuLEASTN*
$PRIuFASTN$  width N, fast to operate with, decimal not.       *crv-PRIuFASTN*
$PRIuMAX$    type$intmax_t$, decimal notation                    *crv-PRIuMAX*
$PRIuPTR$    type$intptr_t$, decimal notation                    *crv-PRIuPTR*

$PRIxN$      width N, lowercase hex. notation                      *crv-PRIxN*
$PRIxLEASTN$ minimum width N, lowercase hex. notation         *crv-PRIxLEASTN*
$PRIxFASTN$  width N, fast operation, lowercase hex. not       *crv-PRIxFASTN*
$PRIxMAX$    type$intmax_t$, lowercase hex. notation             *crv-PRIxMAX*
$PRIxPTR$    type$intptr_t$, lowercase hex. notation             *crv-PRIxPTR*

$PRIXN$      width N, uppercase hex. notation                      *crv-PRIXN*
$PRIXLEASTN$ minimum width N, uppercase hex. notation         *crv-PRIXLEASTN*
$PRIXFASTN$  width N, fast operation, uppercase hex. not.      *crv-PRIXFASTN*
$PRIXMAX$    type$intmax_t$, uppercase hex. notation             *crv-PRIXMAX*
$PRIXPTR$    type$intptr_t$, uppercase hex. notation             *crv-PRIXPTR*


Format Specifiers for ..scanf
-----------------------------

Signed Integers:
$SCNdN$      width N, decimal notation                             *crv-SCNdN*
$SCNdLEASTN$ minimum width N, decimal notation                *crv-SCNdLEASTN*
$SCNdFASTN$  width N, fast to operate with, decimal not.       *crv-SCNdFASTN*
$SCNdMAX$    type$intmax_t$, decimal notation                    *crv-SCNdMAX*
$SCNdPTR$    type$intptr_t$, decimal notation                    *crv-SCNdPTR*

$SCNiN$      width N, decimal notation                             *crv-SCNiN*
$SCNiLEASTN$ minimum width N, decimal notation                *crv-SCNiLEASTN*
$SCNiFASTN$  width N, fast to operate with, decimal not.       *crv-SCNiFASTN*
$SCNiMAX$    type$intmax_t$, decimal notation                    *crv-SCNiMAX*
$SCNiPTR$    type$intptr_t$, decimal notation                    *crv-SCNiPTR*

Unsigned Integers:
$SCNoN$      width N, octal notation                               *crv-SCNoN*
$SCNoLEASTN$ minimum width N, octal notation                  *crv-SCNoLEASTN*
$SCNoFASTN$  width N, fast to operate with, octal not.         *crv-SCNoFASTN*
$SCNoMAX$    type$intmax_t$, octal notation                      *crv-SCNoMAX*
$SCNoPTR$    type$intptr_t$, octal notation                      *crv-SCNoPTR*

$SCNuN$      width N, decimal notation                             *crv-SCNuN*
$SCNuLEASTN$ minimum width N, decimal notation                *crv-SCNuLEASTN*
$SCNuFASTN$  width N, fast to operate with, decimal not.       *crv-SCNuFASTN*
$SCNuMAX$    type$intmax_t$, decimal notation                    *crv-SCNuMAX*
$SCNuPTR$    type$intptr_t$, decimal notation                    *crv-SCNuPTR*

$SCNxN$      width N, hex. notation                                *crv-SCNxN*
$SCNxLEASTN$ minimum width N, hex. notation                   *crv-SCNxLEASTN*
$SCNxFASTN$  width N, fast operation, hex. not                 *crv-SCNxFASTN*
$SCNxMAX$    type$intmax_t$, hex. notation                       *crv-SCNxMAX*
$SCNxPTR$    type$intptr_t$, hex. notation                       *crv-SCNxPTR*


Example: >
    #define __STDC_FORMAT_MACROS
    
    #include <inttypes.h>
    #include <stdio.h>

    int main(void)
    {
      int16_t n = -123; 

      printf("Value is %4" PRIu16 "\n", n);
    }



imaxdiv_t Type                                                 *crv-imaxdiv_t*
--------------
This is a structure type used to hold the result returned by the$imaxdiv()$
function. It holds both, the quotient and the remainder from the division.



imaxabs() Function                                               *crv-imaxabs*
-------------------
Synopsis~
 $#include <inttypes.h>$
 $intmax_t imaxabs(intmax_t j);$
 
Return~
absolute value of$j$

Description~
This function computes the absolute value of an integer$j$.



imaxdiv() Function                                               *crv-imaxdiv*
-------------------
Synopsis~
 $#include <inttypes.h>$
 $intdiv_t imaxdiv(intmax_t numerator, intmax_t denominator );$
 
Return~
returns result of division and modulo operation, both stored in$intdiv_t$
structur

Description~
This functions computes$numerator / denominator$and$numerator % denominator$in
a single operation.



strtoimax() Function                                           *crv-strtoimax*
--------------------
Synopsis~
 $#include <inttypes.h>$
 $intmax_t strtoimax(const char *restrict string, char **restrict tailptr,$
                    $int base);$
 
Return~
converted value

Description~
This function ("string-to-imax") converts the initial part of$string$to a
signed integer, which is returned as a value of type$intmax_t$.
See$strol()$for description of parameters (|crv-libstrtol|).



strtoumax() Function                                           *crv-strtoumax*
--------------------
Synopsis~
 $#include <inttypes.h>$
 $uintmax_t strtoumax(const char *restrict string, char **restrict tailptr,$
                     $int base);$
 
Return~
converted value

Description~
This function ("string-to-umax") converts the initial part of$string$to a
signed integer, which is returned as a value of type$uintmax_t$.
See$stroul()$for description of parameters (|crv-libstrtoul|).



wcstoimax() Function                                           *crv-wcstoimax*
--------------------
Synopsis~
 $#include <stddef.h>        // for wchar_t$
 $#include <inttypes.h>$
 $wchar_t wcstoimax(const wchar_t *restrict string,$
                   $wchar_t **restrict tailptr, int base);$
 
Return~
converted value

Description~
This function is equivalent to the$strtoimax()$function in nearly all aspects
but handles wide character strings (see |crv-libstrtoimax| for further
information).



wcstoumax() Function                                           *crv-wcstoumax*
--------------------
Synopsis~
 $#include <stddef.h>        // for wchar_t$
 $#include <inttypes.h>$
 $wchar_t wcstoimax(const wchar_t *restrict string,$
                   $wchar_t **restrict tailptr, int base);$
 
Return~
converted value

Description~
This function is equivalent to the$strtoumax()$function in nearly all aspects
but handles wide character strings (see |crv-libstrtoumax| for further
information).



==============================================================================
II.9  <iso646.h> Alternatives                                 *crv-libIso646H*

This header defines some macros. They can be used for alternative spellings.

      Macro  |  Expands to
   ----------+------------
    $and$    |   $&&$
    $and_eq$ |   $&=$
    $bitand$ |   $&$
    $bitor$  |   $|$
    $compl$  |   $~$
    $not$    |   $!$
    $not_eq$ |   $!=$
    $or$     |   $||$
    $or_eq$  |   $|=$
    $xor$    |   $^$
    $xor_eq$ |   $^=$



==============================================================================
II.10 <limits.h> Limits of Integer Types                      *crv-libLimitsH*

This header file defines several macros that expand to various limits and
parameters of the integer types.
NOTE: The values are platform- and implementation-specific.The ISO C standard
specifies minimum and maximum values for most of these parameters.

The macros of this header can be grouped in:
  - range of integer type
  - width of type
  - selection of conversion and its properties
 

Quicklink:
    $CHAR_BIT$      Macro  |crv-CHAR_BIT|
    $CHAR_MAX$      Macro  |crv-CHAR_MAX|
    $CHAR_MIN$      Macro  |crv-CHAR_MIN|
    $INT_MAX$       Macro  |crv-INT_MAX|
    $INT_MIN$       Macro  |crv-INT_MIN|
    $LONG_LONG_MAX$ Macro  |crv-LONG_LONG_MAX|
    $LONG_LONG_MIN$ Macro  |crv-LONG_LONG_MIN|
    $LONG_MAX$      Macro  |crv-LONG_MAX|
    $LONG_MIN$      Macro  |crv-LONG_MIN|
    $MB_LEN_MAX$    Macro  |crv-MB_LEN_MAX|
    $SCHAR_MAX$     Macro  |crv-SCHAR_MAX|
    $SCHAR_MIN$     Macro  |crv-SCHAR_MIN|
    $SHRT_MAX$      Macro  |crv-SHRT_MAX|
    $SHRT_MIN$      Macro  |crv-SHRT_MIN|
    $UCHAR_MAX$     Macro  |crv-UCHAR_MAX|
    $UINT_MAX$      Macro  |crv-UINT_MAX|
    $ULONG_LONG_MAX$Macro  |crv-ULONG_LONG_MAX|
    $ULONG_MAX$     Macro  |crv-ULONG_MAX|
    $USHRT_MAX$     Macro  |crv-USHRT_MAX|


------------------------------------------------------------------------------
II.10.1 Range of Integer Type                                 *crv-libLHRange*

Each signed integer type has a pair of macros which give the smallest and
largest values that it can hold. Each unsigned integer type has one such
macro, for the maximum value; the minimum value is, of course, zero. 

The values of these macros are all integer constant expressions. The MAX and
MIN macros for$char$and$short int$types have values of type$int$. The MAX and
MIN macros for the other types have values of the same type described by
the macro - thus,$ULONG_MAX$has type$unsigned long int$.

SCHAR_MIN Macro                                                *crv-SCHAR_MIN*
SCHAR_MAX Macro                                                *crv-SCHAR_MAX*
---------------
minimum / maximum value that can be represented by a$signed char$


UCHAR_MAX Macro                                                *crv-UCHAR_MAX*
---------------
maximum value that can be represented by an$unsigned char$


CHAR_MIN Macro                                                  *crv-CHAR_MIN*
CHAR_MAX Macro                                                  *crv-CHAR_MAX*
--------------
minimum / maximum value that can be represented by a$char$


SHRT_MIN Macro                                                  *crv-SHRT_MIN*
SHRT_MAX Macro                                                  *crv-SHRT_MAX*
--------------
minimum / maximum value that can be represented by a$signed short int$


USHRT_MAX Macro                                                *crv-USHRT_MAX*
---------------
maximum value that can be represented by an$unsigned short int$ 


INT_MIN Macro                                                    *crv-INT_MIN*
INT_MAX Macro                                                    *crv-INT_MAX*
-------------
minimum / maximum value that can be represented by a$signed int$

UINT_MAX Macro                                                  *crv-UINT_MAX*
--------------
maximum value that can be represented by an$unsigned int$


LONG_MIN Macro                                                  *crv-LONG_MIN*
LONG_MAX Macro                                                  *crv-LONG_MAX*
--------------
minimum / maximum value that can be represented by a$signed long int$


ULONG_MAX Macro                                                *crv-ULONG_MAX*
---------------
maximum value that can be represented by an$unsigned long int$ 


LONG_LONG_MIN Macro                                        *crv-LONG_LONG_MIN*
LONG_LONG_MAX Macro                                        *crv-LONG_LONG_MAX*
-------------------
minimum / maximum value that can be represented by a$signed long long int$


ULONG_LONG_MAX Macro                                      *crv-ULONG_LONG_MAX*
--------------------
maximum value that can be represented by an$unsigned long long int$ 




------------------------------------------------------------------------------
II.10.2 Width of Type                                         *crv-libLHWidth*

CHAR_BIT Macro                                                  *crv-CHAR_BIT*
--------------
this is the number of bits in a$char$- eight, on most systems. The value
has type$int$. 



------------------------------------------------------------------------------
II.10.3 Conversion and Properties                              *crv-libLHConv*

A characteristic of each multibyte character set is the maximum number of
bytes that can be necessary to represent one character. This information
is quite important when writing code that uses the conversion functions.

MB_LEN_MAX Macro                                              *crv-MB_LEN_MAX*
----------------
Specifies the maximum number of bytes in the multibyte sequence for a single
character in any of the supported locales. This is a compile-time constant.




==============================================================================
II.11 <local.h> Localization                                   *crv-libLocalH*

This header defines macros and declares functions for setting local specific
things.

Quicklink:
    $LC_ALL$       Macro   |crv-LC_ALL|
    $LC_COLLATE$   Macro   |crv-LC_COLLATE|
    $LC_CTYPE$     Macro   |crv-LC_CTYPE|
    $LC_MONETARY$  Macro   |crv-LC_MONETARY|
    $LC_NUMERIC$   Macro   |crv-LC_NUMERIC|
    $lconf$        Type    |crv-lconf|
    $localeconf()$ Func    |crv-localeconv|
    $setlocale()$  Func    |crv-setlocale|


------------------------------------------------------------------------------
II.11.1 Categories                                            *crv-libLocHCat*

The purposes that locales serve are grouped into categories, so that a user
or a program can choose the locale for each category independently.
The following macro names are both an environment variable that
a user can set, and a macro name that can be used as an argument
to$setlocale()$.
Additional macro definitions beginning with LC_ followed by uppercase letters
my be specified by the compiler.


LC_COLLATE Macro                                              *crv-LC_COLLATE*
----------------
This category applies to collation of strings (functions$strcoll()$and
$strxfrm()$). 


LC_CTYPE Macro                                                  *crv-LC_CTYPE*
--------------
This category applies to classification and conversion of characters, and to
multibyte and wide characters.


LC_MONETARY Macro                                            *crv-LC_MONETARY*
-----------------
This category applies to formatting monetary values. 


LC_NUMERIC Macro                                              *crv-LC_NUMERIC*
----------------
This category applies to formatting numeric values that are not monetary. 


LC_ALL Macro                                                      *crv-LC_ALL*
------------
This is not an environment variable; it is only a macro that can be use with
$setlocale()$to set a single locale for all purposes. Setting this environment
variable overwrites all selections by the other LC_* variables. 



------------------------------------------------------------------------------
II.11.2 Standard Locales                                      *crv-libLocHLoc*

There are two standard locales:

"C"
This is the standard C locale. The attributes and behavior it provides are
specified in the ISO C standard. This is the default. 
For "C" the members of the$lconf$structure have the following values: >
    char *decimal_point      // "."
    char *mon_decimal_point  // ""
    char *thousands_sep      // ""
    char *mon_thousands_sep  // ""
    char *grouping           // ""
    char *mon_grouping       // ""
    char int_frac_digits     // CHAR_MAX
    char frac_digits         // CHAR_MAX 
    char *currency_symbol    // ""
    char *int_curr_symbol    // ""
    char p_cs_precedes       // CHAR_MAX 
    char n_cs_precedes       // CHAR_MAX 
    char int_p_cs_precedes   // CHAR_MAX 
    char int_n_cs_precedes   // CHAR_MAX 
    char p_sep_by_space      // CHAR_MAX 
    char n_sep_by_space      // CHAR_MAX 
    char int_p_sep_by_space  // CHAR_MAX 
    char int_n_sep_by_space  // CHAR_MAX 
    char *positive_sign      // ""
    char *negative_sign      // ""
    char p_sign_posn         // CHAR_MAX 
    char n_sign_posn         // CHAR_MAX 
    char int_p_sign_posn     // CHAR_MAX 
    char int_n_sign_posn     // CHAR_MAX 
An empty string or$CHAR_MAX$indicates that the value is not available
in this local.

"" 
The empty name says to select a locale based on environment variables,
see categories (|crv-libLocHCat|).



------------------------------------------------------------------------------
II.11.3 Information Structure                                *crv-libLocHInfo*


lconf Type                                                         *crv-lconf*
----------
$lconf$is a structure giving information about numeric and monetary notation.
According to standard C this structure must have at least the following
elements. 
If a member of the structure has type$char$, and the value is$CHAR_MAX$,
it means that the current locale has no value for that parameter. 


$char *decimal_point$                                      *crv-decimal_point*
$char *mon_decimal_point$                              *crv-mon_decimal_point*
These are the decimal-point separators used in formatting non-monetary and
monetary quantities, respectively.


$char *thousands_sep$                                      *crv-thousands_sep*
$char *mon_thousands_sep$                              *crv-mon_thousands_sep*
These are the separators used to delimit groups of digits to the left of the
decimal point in formatting non-monetary and monetary quantities,
respectively. 


$char *grouping$                                                *crv-grouping*
$char *mon_grouping$                                        *crv-mon_grouping*
These are strings that specify how to group the digits to the left of the
decimal point.$grouping$applies to non-monetary quantities and$mon_grouping$
applies to monetary quantities. Use either$thousands_sep$or$mon_thousands_sep$
to separate the digit groups. 

Each member of these strings is to be interpreted as an integer value of type
$char$. Successive numbers (from left to right) give the sizes of successive
groups (from right to left, starting at the decimal point.) The last member
is either 0, in which case the previous member is used over and over again
for all the remaining groups, or$CHAR_MAX$, in which case there is no more
grouping - or, put another way, any remaining digits form one large group
without separators. 

For example, if grouping is "\04\03\02", the correct grouping for the number
123456787654321 is 12, 34, 56, 78, 765, 4321. This uses a group of 4 digits
at the end, preceded by a group of 3 digits, preceded by groups of 2 digits
(as many as needed). With a separator of ,, the number would be printed as
12,34,56,78,765,4321. 

A value of "\03" indicates repeated groups of three digits, as normally used
in the U.S. 


$char int_frac_digits$                                   *crv-int_frac_digits*
$char frac_digits$                                           *crv-frac_digits*
These are small integers indicating how many fractional digits (to the right
of the decimal point) should be displayed in a monetary value in international
and local formats, respectively.


$char *currency_symbol$                                  *crv-currency_symbol*
The local currency symbol for the selected locale. 


$char *int_curr_symbol$                                  *crv-int_curr_symbol*
The international currency symbol for the selected locale. The value should
normally consist of a three-letter abbreviation.


$char p_cs_precedes$                                       *crv-p_cs_precedes*
$char n_cs_precedes$                                       *crv-n_cs_precedes*
$char int_p_cs_precedes$                               *crv-int_p_cs_precedes*
$char int_n_cs_precedes$                               *crv-int_n_cs_precedes*
These members are 1 if the$currency_symbol$or$int_curr_symbol$strings should
precede the value of a monetary amount, or 0 if the strings should follow
the value. The$p_cs_precedes$and$int_p_cs_precedes$members apply to positive
amounts (or zero), and the$n_cs_precedes$and$int_n_cs_precedes$members apply
to negative amounts. 
The members with the$int_ prefix$apply to the$int_curr_symbol$while the other
two apply to$currency_symbol$.


$char p_sep_by_space$                                     *crv-p_sep_by_space*
$char n_sep_by_space$                                     *crv-n_sep_by_space*
$char int_p_sep_by_space$                             *crv-int_p_sep_by_space*
$char int_n_sep_by_space$                             *crv-int_n_sep_by_space*
These members are 1 if a space should appear between the$currency_symbol$
or$int_curr_symbol$strings and the amount, or 0 if no space should appear. 
The$p_sep_by_space$and$int_p_sep_by_space$members apply to positive amounts
(or zero), and the$n_sep_by_space$and$int_n_sep_by_space$members apply to
negative amounts. 
The members with the$int_ prefix$apply to the$int_curr_symbol$while the other
two apply to$currency_symbol$. There is one specialty with 
the$int_curr_symbol$though. Since all legal values contain a space at the
end the string one either$printf()$this space (if the currency symbol must
appear in front and must be separated) or one has to avoid printing this
character at all (especially when at the end of the string). 


$char *positive_sign$                                      *crv-positive_sign*
$char *negative_sign$                                      *crv-negative_sign*
These are strings used to indicate positive (or zero) and negative monetary
quantities, respectively. 


$char p_sign_posn$                                           *crv-p_sign_posn*
$char n_sign_posn$                                           *crv-n_sign_posn*
$char int_p_sign_posn$                                   *crv-int_p_sign_posn*
$char int_n_sign_posn$                                   *crv-int_n_sign_posn*
These members are small integers that indicate how to position the sign for
nonnegative and negative monetary quantities, respectively. (The string used
by the sign is what was specified with$positive_sign$or$negative_sign$.)
The possible values are as follows: 

0 The currency symbol and quantity should be surrounded by parentheses. 

1 Print the sign string before the quantity and currency symbol. 

2 Print the sign string after the quantity and currency symbol. 

3 Print the sign string right before the currency symbol. 

4 Print the sign string right after the currency symbol. 

CHAR_MAX "Unspecified". Both members have this value in the standard C
locale. 

The members with the$int_ prefix$apply to the$int_curr_symbol$while the other
two apply to$currency_symbol$.



------------------------------------------------------------------------------
II.11.4 Functions                                            *crv-libLocHFunc*


setlocale() Function                                           *crv-setlocale*
--------------------
Synopsis~
 $#include <locale.h>$
 $char *setlocale(int category, const char *locale);$
 
Return~
see description

Description~
This function sets the current locale for category$category$to$locale$.

If category is$ LC_ALL$, this specifies the locale for all purposes. The other
possible values of$category$specify an single purpose 
(see Categories |crv-libLocHCat| ).

This function can also be used to find out the current locale by passing a null
pointer as the$locale$argument. In this case, a string is returned that is the
name of the locale currently selected for category$category$. 

The string returned should not be modified.

When the current locale for category$LC_ALL$is read, the value encodes the
entire combination of selected locales for all categories.

It is not guaranteed that the returned pointer remains valid over time, so a
copy must be made.

When the$locale$argument is not a null pointer, the string returned reflects
the newly-modified locale. 

If an empty string for$locale$is specified, this means to read the appropriate
environment variable and use its value to select the locale for$category$.

If a nonempty string is given for$locale$, then the locale of that name is
used if possible. 

If an invalid locale name is specified,$setlocale()$returns a null pointer
and leaves the current locale unchanged. 



localeconf() Function                                         *crv-localeconv*
---------------------
Synopsis~
 $#include <locale.h>$
 $struct lconv *localeconv(void);$
 
Return~
pointer to structure$lconv$, representing the current local settings

Description~
This function returns a pointer to the structure$lconv$whose components
contain information about how numeric and monetary values should be
formatted in the current locale.




==============================================================================
II.12  <math.h> Mathematics                                     *crv-libMathH*

This header file defines macros and declares functions that allow to do
mathematics.

Quicklink:
    $acos()$          Func   |crv-acos|
    $acosf()$         Func   |crv-acosf|
    $acosh()$         Func   |crv-acosh|
    $acoshf()$        Func   |crv-acoshf|
    $acoshl()$        Func   |crv-acoshl|
    $acosl()$         Func   |crv-acosl|
    $asin()$          Func   |crv-asin|
    $asinf()$         Func   |crv-asinf|
    $asinh()$         Func   |crv-asinh|
    $asinhf()$        Func   |crv-asinhf|
    $asinhl()$        Func   |crv-asinhl|
    $asinl()$         Func   |crv-asinl|
    $atan()$          Func   |crv-atan|
    $atanf()$         Func   |crv-atanf|
    $atanh()$         Func   |crv-atanh|
    $atanhf()$        Func   |crv-atanhf|
    $atanhl()$        Func   |crv-atanhl|
    $atanl()$         Func   |crv-atanl|
    $atan2()$         Func   |crv-atan2|
    $atan2f()$        Func   |crv-atan2f|
    $atan2l()$        Func   |crv-atan2l|
    $cbrt()$          Func   |crv-cbrt|
    $cbrtf()$         Func   |crv-cbrtf|
    $cbrtl()$         Func   |crv-cbrtl|
    $ceil()$          Func   |crv-ceil|
    $ceilf()$         Func   |crv-ceilf|
    $ceill()$         Func   |crv-ceill|
    $copysign()$      Func   |crv-copysign|
    $copysignf()$     Func   |crv-copysignf|
    $copysignl()$     Func   |crv-copysignl|
    $cos()$           Func   |crv-cos|
    $cosf()$          Func   |crv-cosf|
    $cosh()$          Func   |crv-cosh|
    $coshf()$         Func   |crv-coshf|
    $coshl()$         Func   |crv-coshl|
    $cosl()$          Func   |crv-cosl|
    $erf()$           Func   |crv-erf|
    $erff()$          Func   |crv-erff|
    $erfl()$          Func   |crv-erfl|
    $erfc()$          Func   |crv-erfc|
    $erfcf()$         Func   |crv-erfcf|
    $erfcl()$         Func   |crv-erfcl|
    $exp2()$          Func   |crv-exp2|
    $exp2f()$         Func   |crv-exp2f|
    $exp2l()$         Func   |crv-exp2l|
    $exp()$           Func   |crv-exp|
    $expf()$          Func   |crv-expf|
    $expl()$          Func   |crv-expl|
    $expm1()$         Func   |crv-expm1|
    $expm1f()$        Func   |crv-expm1f|
    $expm1l()$        Func   |crv-expm1l|
    $fabs()$          Func   |crv-fabs|
    $fabsf()$         Func   |crv-fabsf|
    $fabsl()$         Func   |crv-fabsl|
    $fdim()$          Func   |crv-fdim|
    $fdimf()$         Func   |crv-fdimf|
    $fdiml()$         Func   |crv-fdiml|
    $floor()$         Func   |crv-floor|
    $floorf()$        Func   |crv-floorf|
    $floorl()$        Func   |crv-floorl|
    $fmin()$          Func   |crv-fmin|
    $fminf()$         Func   |crv-fminf|
    $fminl()$         Func   |crv-fminl|
    $fma()$           Func   |crv-fma|
    $fmaf()$          Func   |crv-fmaf|
    $fmal()$          Func   |crv-fmal|
    $fmax()$          Func   |crv-fmax|
    $fmaxf()$         Func   |crv-fmaxf|
    $fmaxl()$         Func   |crv-fmaxl|
    $fmod()$          Func   |crv-fmod|
    $fmodf()$         Func   |crv-fmodf|
    $fmodl()$         Func   |crv-fmodl|
    $FP_FAST_FMA$     Macro  |crv-FP_FAST_FMA|
    $FP_FAST_FMAF$    Macro  |crv-FP_FAST_FMAF|
    $FP_FAST_FMAL$    Macro  |crv-FP_FAST_FMAL|
    $FP_ILOGB0$       Macro  |crv-FP_ILOGB0|
    $FP_ILOGBNAN$     Macro  |crv-FP_ILOGBNAN|
    $frexp()$         Func   |crv-frexp|
    $frexpf()$        Func   |crv-frexpf|
    $frexpl()$        Func   |crv-frexpl|
    $hypot()$         Func   |crv-hypot|
    $hypotf()$        Func   |crv-hypotf|
    $hypotl()$        Func   |crv-hypotl|
    $ilogb()$         Func   |crv-ilogb|
    $ilogbf()$        Func   |crv-ilogbf|
    $ilogbl()$        Func   |crv-ilogbl|
    $isfinite()$      Macro  |crv-isfinite|
    $isgreater()$     Macro  |crv-isgreater|
    $isgreaterequal()$Macro  |crv-isgreaterequal|
    $isinf()$         Macro  |crv-isinf|
    $isless()$        Macro  |crv-isless|
    $islessequal()$   Macro  |crv-islessequal|
    $islessgreater()$ Macro  |crv-islessgreater|
    $isnan()$         Macro  |crv-isnan|
    $isnormal()$      Macro  |crv-isnormal|
    $isunordered()$   Macro  |crv-isunordered|
    $ldexp()$         Func   |crv-ldexp|
    $ldexpf()$        Func   |crv-ldexpf|
    $ldexpl()$        Func   |crv-ldexpl|
    $lgamma()$        Func   |crv-lgamma|
    $lgammaf()$       Func   |crv-lgammaf|
    $lgammal()$       Func   |crv-lgammal|
    $log()$           Func   |crv-log|
    $logf()$          Func   |crv-logf|
    $logl()$          Func   |crv-logl|
    $log10()$         Func   |crv-log10|
    $log10f()$        Func   |crv-log10f|
    $log10l()$        Func   |crv-log10l|
    $log1p()$         Func   |crv-log1p|
    $log1pf()$        Func   |crv-log1pf|
    $log1pl()$        Func   |crv-log1pl|
    $log2()$          Func   |crv-log2|
    $log2f()$         Func   |crv-log2f|
    $log2l()$         Func   |crv-log2l|
    $logb()$          Func   |crv-logb|
    $logbf()$         Func   |crv-logbf|
    $logbl()$         Func   |crv-logbl|
    $lrint()$         Func   |crv-lrint|
    $lrintf()$        Func   |crv-lrintf|
    $lrintl()$        Func   |crv-lrintl|
    $llrint()$        Func   |crv-llrint|
    $llrintf()$       Func   |crv-llrintf|
    $llrintl()$       Func   |crv-llrintl|
    $lround()$        Func   |crv-lround|
    $lroundf()$       Func   |crv-lroundf|
    $lroundl()$       Func   |crv-lroundl|
    $llround()$       Func   |crv-llround|
    $llroundf()$      Func   |crv-llroundf|
    $llroundl()$      Func   |crv-llroundl|
    $modf()$          Func   |crv-modf|
    $modff()$         Func   |crv-modff|
    $modfl()$         Func   |crv-modfl|
    $nan()$           Func   |crv-nan|
    $nanf()$          Func   |crv-nanf|
    $nanl()$          Func   |crv-nanl|
    $nearbyint()$     Func   |crv-nearbyint|
    $nearbyintf()$    Func   |crv-nearbyintf|
    $nearbyintl()$    Func   |crv-nearbyintl|
    $nextafter()$     Func   |crv-nextafter|
    $nextafterf()$    Func   |crv-nextafterf|
    $nextafterl()$    Func   |crv-nextafterl|
    $nexttoward()$    Func   |crv-nexttoward|
    $nexttowardf()$   Func   |crv-nexttowardf|
    $nexttowardl()$   Func   |crv-nexttowardl|
    $pow()$           Func   |crv-pow|
    $powf()$          Func   |crv-powf|
    $powl()$          Func   |crv-powl|
    $remainder()$     Func   |crv-remainder|
    $remainderf()$    Func   |crv-remainderf|
    $remainderl()$    Func   |crv-remainderl|
    $remquo()$        Func   |crv-remquo|
    $remquof()$       Func   |crv-remquof|
    $remquol()$       Func   |crv-remquol|
    $rint()$          Func   |crv-rint|
    $rintf()$         Func   |crv-rintf|
    $rintl()$         Func   |crv-rintl|
    $round()$         Func   |crv-round|
    $roundf()$        Func   |crv-roundf|
    $roundl()$        Func   |crv-roundl|
    $scalbn()$        Func   |crv-scalbn|
    $scalbnf()$       Func   |crv-scalbnf|
    $scalbnl()$       Func   |crv-scalbnl|
    $scalbln()$       Func   |crv-scalbln|
    $scalblnf()$      Func   |crv-scalblnf|
    $scalblnl()$      Func   |crv-scalblnl|
    $signbit()$       Macro  |crv-signbit|
    $signgam$         Var    |crv-signgam|
    $sin()$           Func   |crv-sin|
    $sinf()         $ Func   |crv-sinf|
    $sinh()$          Func   |crv-sinh|
    $sinhf()$         Func   |crv-sinhf|
    $sinhl()$         Func   |crv-sinhl|
    $sinl()$          Func   |crv-sinl|
    $sqrt()$          Func   |crv-sqrt|
    $sqrtf()$         Func   |crv-sqrtf|
    $sqrtl()$         Func   |crv-sqrtl|
    $tan()$           Func   |crv-tan|
    $tanf()$          Func   |crv-tanf|
    $tanh()$          Func   |crv-tanh|
    $tanhf()$         Func   |crv-tanhf|
    $tanhl()$         Func   |crv-tanhl|
    $tanl()$          Func   |crv-tanl|
    $tgamma()$        Func   |crv-tgamma|
    $tgammaf()$       Func   |crv-tgammaf|
    $tgammal()$       Func   |crv-tgammal|
    $trunc()$         Func   |crv-trunc|
    $truncf()$        Func   |crv-truncf|
    $truncl()$        Func   |crv-truncl|



------------------------------------------------------------------------------
II.12.1  Error Conditions                                       *crv-libMHErr*

All functions declared in$<math.h>$do handle errors in a very similar way.

If an argument is outside the domain over a function is defined a domain
error occurs, then$errno$is set to$EDOM$. The value that the function returns
is implementation specific.

If the result of a function cannot be represented in the type of return value,
a range error occurs.
If the result overflows, the function returns the value of the macro
$HUGE_VAL$, with the same sign as the correct value of the function;
$errno$is set to$ERANGE$. 

If the result underflows, the function returns 0; whether or not$errno$is
set to$ERANGE$is implementation-defined.


HUGE_VAL  Macro                                                 *crv-HUGE_VAL*
HUGE_VALF Macro                                                *crv-HUGE_VALF*
HUGE_VALL Macro                                                *crv-HUGE_VALL*
---------------
This macro expands to a positive$double$constant. On machines that use
IEEE 754 floating point format,$HUGE_VAL$is infinity. On other machines,
it's typically the largest positive number that can be represented. 
$HUGE_VALF$and$HUGE_VALL$are the analogs for$float$and$long double$.



------------------------------------------------------------------------------
II.12.2  Classification Macros                                *crv-libMHClass*


fpclassify() Macro                                            *crv-fpclassify*
------------------
Synopsis~
 $#include <math.h>$
 $int fpclassify(float-type x;$
 
Return~
FP_NAN 
The floating-point number x is "Not a Number"

FP_INFINITE 
The value of x is either plus or minus infinity.

FP_ZERO 
The value of x is zero.

FP_SUBNORMAL 
Numbers whose absolute value is too small to be represented in the normal
format are represented in an alternate, denormalized format
(see |crv-dtFormatsFPBasics|)

FP_NORMAL 
This value is returned for all other values of x. It indicates that there
is nothing special about the number. 

Description~
This is a generic macro which works on all floating-point types.
It classifies its argument as NaN, infinite, normal, subnormal, zero or into
another implementation-defined category.



isfinite() Macro                                                *crv-isfinite*
----------------
Synopsis~
 $#include <math.h>$
 $int isfinite(float-type x);$

Return~
0: x is not finite
else x is finite

Description~
This is a generic macro which works on all floating-point types.
This macro returns a nonzero value if x is finite: not plus or minus infinity,
and not NaN. It is equivalent to 
 $(fpclassify (x) != FP_NAN && fpclassify (x) != FP_INFINITE)$



isnormal() Macro                                                *crv-isnormal*
----------------
Synopsis~
 $#include <math.h>$
 $int isnormal(float-type x);$

Return~
0: x is not normal
else x is normal

Description~
This is a generic macro which works on all floating-point types.
This macro returns a nonzero value if x is finite and normalized.
It is equivalent to
 $(fpclassify (x) == FP_NORMAL)$



isnan() Macro                                                      *crv-isnan*
-------------
Synopsis~
 $#include <math.h>$
 $int isnan(float-type x);$

Return~
0: x is not NaN
else x is NaN

Description~
This is a generic macro which works on all floating-point types.
This macro returns a nonzero value if x is NaN. It is equivalent to
 $(fpclassify (x) == FP_NAN)$



isinf() Macro                                                      *crv-isinf*
-------------
Synopsis~
 $#include <math.h>$
 $int isinf(float-type x);$

Return~
0: x is not infinite
else x is infinite

Description~
This is a generic macro which works on all floating-point types.
This macro returns a nonzero value if x is infinte. It is equivalent to
 $(fpclassify (x) == FP_INFINITE)$
~



------------------------------------------------------------------------------
II.12.3  Comparison Macros                                      *crv-libMHCmp*

All macros below are generic macros that work on all floating-point types.


isgreater() Macro                                              *crv-isgreater*
-----------------
Synopsis~
 $#include <math.h>$
 $int isgreater(float-type x, float-type y);$

Return~
0: x is not greater y
else x is greater y

Description~
This macro determines whether the argument x is greater than y.
It is equivalent to (x) > (y), but no exception is raised if x or y are NaN.



isgreaterequal() Macro                                    *crv-isgreaterequal*
----------------------
Synopsis~
 $#include <math.h>$
 $int isgreaterequal(float-type x, float-type y);$

Return~
0: x is not greater or equal y
else x is greater or equal y

Description~
This macro determines whether the argument x is greater than or equal to y.
It is equivalent to (x) >= (y), but no exception is raised if x or y are NaN.



isless() Macro                                                    *crv-isless*
--------------
Synopsis~
 $#include <math.h>$
 $int isless(float-type x, float-type y);$

Return~
0: x is not less y
else x is less y

Description~
This macro determines whether the argument x is less than y. It is equivalent
to (x) < (y), but no exception is raised if x or y are NaN.



islessequal() Macro                                          *crv-islessequal*
-------------------
Synopsis~
 $#include <math.h>$
 $int islessequal(float-type x, float-type y);$

Return~
0: x is not less or equal y
else x is less or equal y

Description~
This macro determines whether the argument x is less than or equal to y. It is
equivalent to (x) <= (y), but no exception is raised if x or y are NaN.



islessgreater() Macro                                      *crv-islessgreater*
---------------------
Synopsis~
 $#include <math.h>$
 $int islessgreater(float-type x, float-type y);$

Return~
0: x is not less or greater y
else x is less or greater y

Description~
This macro determines whether the argument x is less or greater than y. It is
equivalent to (x) < (y) || (x) > (y)  (although it only evaluates x and y
once), but no exception is raised if x or y are NaN. 
This macro is not equivalent to x != y, because that expression is true if x
or y are NaN. 



isunordered() Macro                                          *crv-isunordered*
-------------------
Synopsis~
 $#include <math.h>$
 $int isunordered(float-type x, float-type y);$

Return~
0: x and y are not unordered
else x or y is unordered

Description~
This macro determines whether its arguments are unordered. In other words, 
it is true if x or y are NaN, and false otherwise. 



------------------------------------------------------------------------------
II.12.4  Trigonometric                                         *crv-libMHTrig*


asin() Functions                            *crv-asin* *crv-asinf* *crv-asinl*
----------------
Synopsis~
 $#include <math.h>$
 $double asin(double x);$
 $float asinf(float x);$ 
 $long double asinl(long double x);$

Return~
range -PI/2...+PI/2

Description~
These functions compute the arc sine of x. The value is in units of radians.
The arc sine function is defined mathematically only over the domain -1 to 1.
If x is outside the domain, asin signals a domain error.



acos() Functions                            *crv-acos* *crv-acosf* *crv-acosl*
----------------
Synopsis~
 $#include <math.h>$
 $double acos(double x);$
 $float acosf(float x);$ 
 $long double acosl(long double x);$

Return~
range 0...PI

Description~
These functions compute the arc cosine of x. The value is in units of radians.
The arc cosine function is defined mathematically only over the domain -1 to
1. If x is outside the domain, acos signals a domain error.


atan() Functions                            *crv-atan* *crv-atanf* *crv-atanl*
----------------
Synopsis~
 $#include <math.h>$
 $double atan(double x);$
 $float atanf(float x);$ 
 $long double atanl(long double x);$

Return~
range -PI/2...+PI/2

Description~
These functions compute the arc tangent of x. The value is in units of
radians.


atan2() Functions                        *crv-atan2* *crv-atan2f* *crv-atan2l*
-----------------
Synopsis~
 $#include <math.h>$
 $double atan2(double x);$
 $float atan2f(float x);$ 
 $long double atan2l(long double x);$

Return~
range -PI...+PI
If both x and y are zero, atan2 returns zero.

Description~
This function computes the arc tangent of y/x, but the signs of both arguments
are used to determine the quadrant of the result, and x is permitted to be
zero. The return value is given in radians. 

If x and y are coordinates of a point in the plane, atan2 returns the signed
angle between the line from the origin to that point and the x-axis.
Thus, atan2 is useful for converting Cartesian coordinates to polar
coordinates.



sin() Functions                                *crv-sin* *crv-sinf* *crv-sinl*
---------------
Synopsis~
 $#include <math.h>$
 $double sin(double x);$
 $float sinf(float x);$ 
 $long double sinl(long double x);$

Return~
range -1...+1

Description~
These functions return the sine of x, where x is given in radians.


cos() Functions                                *crv-cos* *crv-cosf* *crv-cosl*
---------------
Synopsis~
 $#include <math.h>$
 $double cos(double x);$
 $float cosf(float x);$ 
 $long double cosl(long double x);$

Return~
range -1...+1

Description~
These functions return the cosine of x, where x is given in radians.


tan() Functions                                *crv-tan* *crv-tanf* *crv-tanl*
---------------
Synopsis~
 $#include <math.h>$
 $double tan(double x);$
 $float tanf(float x);$ 
 $long double tanl(long double x);$

Return~
tangent of x

Description~
These functions return the tangent of x, where x is given in radians. 
Mathematically, the tangent function has singularities at odd multiples of
PI/2. If the argument x is too close to one of these singularities,$tan()$
will signal overflow. 



------------------------------------------------------------------------------
II.12.5  Hyperbolic                                           *crv-libMHHyper*


sinh() Functions                            *crv-sinh* *crv-sinhf* *crv-sinhl*
----------------
Synopsis~
 $#include <math.h>$
 $double sinh(double x);$
 $float sinhf(float x);$ 
 $long double sinhl(long double x);$

Return~
hyperbolic sine of x

Description~
These functions return the hyperbolic sine of x, defined mathematically as
(exp(x) - exp(-x)) / 2. They may signal overflow if x is too large. 



cosh() Functions                            *crv-cosh* *crv-coshf* *crv-coshl*
----------------
Synopsis~
 $#include <math.h>$
 $double cosh(double x);$
 $float coshf(float x);$ 
 $long double coshl(long double x);$

Return~
hyperbolic cosine of x

Description~
These function return the hyperbolic cosine of x, defined mathematically as
(exp(x) + exp(-x)) / 2. They may signal overflow if x is too large. 



tanh() Functions                            *crv-tanh* *crv-tanhf* *crv-tanhl*
----------------
Synopsis~
 $#include <math.h>$
 $double tanh(double x);$
 $float tanhf(float x);$ 
 $long double tanhl(long double x);$

Return~
hyperbolic tangent of x

Description~
These functions return the hyperbolic tangent of x, defined mathematically as
sinh(x) / cosh(x). They may signal overflow if x is too large.



asinh() Functions                        *crv-asinh* *crv-asinhf* *crv-asinhl*
-----------------
Synopsis~
 $#include <math.h>$
 $double asinh(double x);$
 $float asinhf(float x);$ 
 $long double asinhl(long double x);$

Return~
inverse hyperbolic sine of x

Description~
These functions return the inverse hyperbolic sine of x. 



acosh() Functions                        *crv-acosh* *crv-acoshf* *crv-acoshl*
-----------------
Synopsis~
 $#include <math.h>$
 $double acosh(double x);$
 $float acoshf(float x);$ 
 $long double acoshl(long double x);$

Return~
inverse hyperbolic cosine of x

Description~
These functions return the inverse hyperbolic cosine of x. If x is less than
1, acosh signals a domain error. 



atanh() Functions                        *crv-atanh* *crv-atanhf* *crv-atanhl*
-----------------
Synopsis~
 $#include <math.h>$
 $double atanh(double x);$
 $float atanhf(float x);$ 
 $long double atanhl(long double x);$

Return~
inverse hyperbolic tangent of x

Description~
These functions return the inverse hyperbolic tangent of x. If the absolute
value of x is greater than 1,$atanh()$signals a domain error; if it is
equal to 1, it returns infinity. 




------------------------------------------------------------------------------
II.12.6  Exponential & Logarithmic                           *crv-libMHExpLog*



exp() Functions                                *crv-exp* *crv-expf* *crv-expl*
---------------
Synopsis~
 $#include <math.h>$
 $double exp(double x);$
 $float expf(float x);$ 
 $long double expl(long double x);$

Return~
e^x

Description~
These functions compute e (the base of natural logarithms) raised to the
power x. If the magnitude of the result is too large to be representable,
$exp()$signals overflow. 



exp2() Functions                            *crv-exp2* *crv-exp2f* *crv-exp2l*
----------------
Synopsis~
 $#include <math.h>$
 $double exp2(double x);$
 $float exp2f(float x);$ 
 $long double exp2l(long double x);$

Return~
2^x

Description~
These functions compute 2 raised to the power x. Mathematically,$exp2(x)$is
the same as exp(x * log(2)).



expm1() Functions                        *crv-expm1* *crv-expm1f* *crv-expm1l*
-----------------
Synopsis~
 $#include <math.h>$
 $double expm1(double x);$
 $float expm1f(float x);$ 
 $long double expm1l(long double x);$

Return~
exp(x)-1

Description~
These functions return a value equivalent to exp(x) - 1. They are computed in a
way that is accurate even if x is near zero - a case where exp(x) - 1 would be
inaccurate owing to subtraction of two numbers that are nearly equal. 




ilogb() Functions                        *crv-ilogb* *crv-ilogbf* *crv-ilogbl*
-----------------
Synopsis~
 $#include <math.h>$
 $int ilogb(double x);$
 $int ilogbf(float x);$ 
 $int ilogbl(long double x);$

Return~


Description~
These functions are equivalent to the corresponding logb() functions except
that they return signed integer values. Since integers cannot represent
infinity and NaN,$ilogb()$instead returns an integer that can't be the
exponent of a normal floating-point number, the macros are:

FP_ILOGB0 Macro                                                *crv-FP_ILOGB0*
 $ilogb()$returns this value if its argument is 0. The numeric value is
  either$INT_MIN$or$-INT_MAX$.

FP_ILOGBNAN Macro                                            *crv-FP_ILOGBNAN*
 $ilogb()$returns this value if its argument is NaN. The numeric value is
  either$INT_MIN$or$INT_MAX$.



log() Functions                                *crv-log* *crv-logf* *crv-logl*
---------------
Synopsis~
 $#include <math.h>$
 $double log(double x);$
 $float logf(float x);$ 
 $long double logl(long double x);$

Return~
see description

Description~
These functions compute the natural logarithm of x. If x is negative,$log()$
signals a domain error. If x is zero, it returns negative infinity;
if x is too close to zero, it may signal overflow. 



log10() Functions                        *crv-log10* *crv-log10f* *crv-log10l*
-----------------
Synopsis~
 $#include <math.h>$
 $double log10(double x);$
 $float log10f(float x);$ 
 $long double log10l(long double x);$

Return~
base-10 logarithm of x

Description~
These functions return the base-10 logarithm of x.
 $log10(x)$equals$log(x) / log(10)$



log1p() Functions                        *crv-log1p* *crv-log1pf* *crv-log1pl*
------------------
Synopsis~
 $#include <math.h>$
 $double log1p(double x);$
 $float log1pf(float x);$ 
 $long double log1pl(long double x);$

Return~
log(1+x)

Description~
These functions returns a value equivalent to log(1 + x). They are computed
in a way that is accurate even if x is near zero. 



log2() Functions                            *crv-log2* *crv-log2f* *crv-log2l*
----------------
Synopsis~
 $#include <math.h>$
 $double log2(double x);$
 $float log2f(float x);$ 
 $long double log2l(long double x);$

Return~
base-2 logarithm of x

Description~
These functions return the base-2 logarithm of x.
 $log2(x)$equals$log(x) / log(2)$



logb() Functions                            *crv-logb* *crv-logbf* *crv-logbl*
----------------
Synopsis~
 $#include <math.h>$
 $double log2(double x);$
 $float log2f(float x);$ 
 $long double log2l(long double x);$

Return~
see description

Description~
These functions extract the exponent of x and return it as a floating-point
value. If FLT_RADIX is two,$logb()$is equal to$floor(log2 (x))$, except it's
probably faster. 
If x is denormalized,$logb()$returns the exponent x would have if it were
normalized. If x is infinity (positive or negative),$logb()$returns &infin;.
If x is zero,$logb()$returns &infin;. It does not signal. 




frexp() Functions                        *crv-frexp* *crv-frexpf* *crv-frexpl*
-----------------
Synopsis~
 $#include <math.h>$
 $double frexp(double x, int *exponent);$
 $float frexpf(float x, int *exponent);$ 
 $long double frexpl(long double x, int *exponent);$

Return~
see description

Description~
These functions are used to split the number value into a normalized fraction
and an exponent.
If the argument value is not zero, the return value is value times a power
of two, and is always in the range 1/2 (inclusive) to 1 (exclusive). The
corresponding exponent is stored in *exponent; the return value multiplied
by 2 raised to this exponent equals the original number value.

For example,$frexp(12.8, &exponent)$returns 0.8 and stores 4 in exponent.

If value is zero, then the return value is zero and zero is stored in
*exponent.



ldexp() Functions                        *crv-ldexp* *crv-ldexpf* *crv-ldexpl*
-----------------
Synopsis~
 $#include <math.h>$
 $double ldexp(double x, int exponent);$
 $float ldexpf(float x, int exponent);$ 
 $long double ldexpl(long double x, int exponent);$

Return~
see description

Description~
These functions return the result of multiplying the floating-point number
value by 2 raised to the power exponent.
(It can be used to reassemble floating-point numbers that were taken apart
by$frexp()$) .
For example,$ldexp(0.8, 4)$returns 12.8.



modf() Functions                            *crv-modf* *crv-modff* *crv-modfl*
----------------
Synopsis~
 $#include <math.h>$
 $double modf(double x, double *intpart);$
 $float modff(float x, float *intpart);$ 
 $long double modfl(long double x, long double *intpart);$

Return~
stores the integer part in *intpart, and returns the fractional part

Description~
These functions break the argument value into an integer part and a fractional
part (between -1 and 1, exclusive). Their sum equals value. Each of the parts
has the same sign as value, and the integer part is always rounded toward zero.

Example:$modf(2.5, &intpart)$returns 0.5 and stores 2.0 into intpart.



scalbn() Functions                    *crv-scalbn* *crv-scalbnf* *crv-scalbnl*
------------------
Synopsis~
 $#include <math.h>$
 $double scalbn(double x, int n);$
 $float scalbnf(float x, int n);$ 
 $long double scalbnl(long double x, int n);$

Return~
x*FLT_RADIX^n

Description~
These functions compute x * FLT_RADIX^n efficiently (commonly FLT_RADIX is 2).
n is of type$int$, for type$long int$see$scalbln()$.



scalbln() Functions                *crv-scalbln* *crv-scalblnf* *crv-scalblnl*
-------------------
Synopsis~
 $#include <math.h>$
 $double scalbln(double x, long int n);$
 $float scalblnf(float x, long int n);$ 
 $long double scalblnl(long double x, long int n);$

Return~
x*FLT_RADIX^n

Description~
These functions compute x * FLT_RADIX^n efficiently (commonly FLT_RADIX is 2).
n is of type$long int$, for type$int$see$scalbn()$.



------------------------------------------------------------------------------
II.12.7  Power & Absolute                                     *crv-libMHPower*


cbrt() Functions                            *crv-cbrt* *crv-cbrtf* *crv-cbrtl*
----------------
Synopsis~
 $#include <math.h>$
 $double cbrt(double x);$
 $float cbrtf(float x);$ 
 $long double cbrtl(long double x);$

Return~
cube root of x

Description~
These functions return the cube root of x. They cannot fail; every
representable real value has a representable real cube root.



fabs() Functions                            *crv-fabs* *crv-fabsf* *crv-fabsl*
----------------
Synopsis~
 $#include <math.h>$
 $double fabs(double x);$
 $float fabsf(float x);$ 
 $long double fabsl(long double x);$

Return~
absolute of x

Description~
This function returns the absolute value of the floating-point number x.


hypot() Functions                        *crv-hypot* *crv-hypotf* *crv-hypotl*
-----------------
Synopsis~
 $#include <math.h>$
 $double hypot(double x, double y);$
 $float hypotf(float x, float y);$ 
 $long double hypotl(long double x, long double y);$

Return~
sqrt(x*x + y*y)

Description~
These functions return sqrt(x*x + y*y).
Normally this function is faster and more accurate than the direct formula.



pow() Functions                                *crv-pow* *crv-powf* *crv-powl*
---------------
Synopsis~
 $#include <math.h>$
 $double pow(double x, double y);$
 $float powf(float x, float y);$ 
 $long double powl(long double x, long double y);$

Return~
x^y

Description~
These are general exponentiation functions, returning base raised to power
(x^y).

Mathematically,$pow()$would return a complex number when base is negative and
power is not an integral value.$pow$can't do that, so instead it signals a
domain error.$pow$may also underflow or overflow the destination type.



sqrt() Functions                            *crv-sqrt* *crv-sqrtf* *crv-sqrtl*
----------------
Synopsis~
 $#include <math.h>$
 $double sqrt(double x);$
 $float sqrtf(float x);$ 
 $long double sqrtl(long double x);$

Return~
sqrt(x)

Description~
These functions return the nonnegative square root of x.
If x is negative,$sqrt()$signals a domain error. Mathematically, it should
return a complex number. 




------------------------------------------------------------------------------
II.12.8  Error & Gamma                                       *crv-libMHErrGam*


erf() Functions                                *crv-erf* *crv-erff* *crv-erfl*
---------------
Synopsis~
 $#include <math.h>$
 $double erf(double x);$
 $float erff(float x);$ 
 $long double erfl(long double x);$

Return~
error function of x

Description~
$erf()$returns the error function of x. The error function is defined as 
  erf(x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt


erfc() Functions                            *crv-erfc* *crv-erfcf* *crv-erfcl*
----------------
Synopsis~
 $#include <math.h>$
 $double erf(double x);$
 $float erff(float x);$ 
 $long double erfl(long double x);$

Return~
1 - error function of x

Description~
$erfc()$returns 1.0 -$erf(x)$, but computed in a fashion that avoids
round-off error when x is large. 


lgamma() Functions                    *crv-lgamma* *crv-lgammaf* *crv-lgammal*
------------------
Synopsis~
 $#include <math.h>$
 $double lgamma(double x);$
 $float lgammaf(float x);$ 
 $long double lgammal(long double x);$

Return~
see description 

Description~
$lgamma()$returns the natural logarithm of the absolute value of the gamma
function of x. The gamma function is defined as 

  gamma(x) = integral from 0 to &infin; of t^(x-1) e^-t dt

                                                                 *crv-signgam*
The sign of the gamma function is stored in the global variable$signgam$,
which is declared in$<math.h>$. It is 1 if the intermediate result was
positive or zero, or -1 if it was negative.

To compute the real gamma function $tgamma()$can be used or the values as
can be computed as follows: 

  lgam = lgamma(x);
  gam  = signgam*exp(lgam);


The gamma function has singularities at the non-positive integers.$lgamma()$
will raise the zero divide exception if evaluated at a singularity.



tgamma() Functions                    *crv-tgamma* *crv-tgammaf* *crv-tgammal*
------------------
Synopsis~
 $#include <math.h>$
 $double tgamma(double x);$
 $float tgammaf(float x);$ 
 $long double tgammal(long double x);$

Return~
see description 

Description~
$tgamma()$applies the gamma function to x. The gamma function is defined as 
  gamma (x) = integral from 0 to &infin; of t^(x-1) e^-t dt




------------------------------------------------------------------------------
II.12.9  Nearest Integer                                       *crv-libMHNear*


ceil() Functions                            *crv-ceil* *crv-ceilf* *crv-ceill*
----------------
Synopsis~
 $#include <math.h>$
 $double ceil(double x);$
 $float ceilf(float x);$ 
 $long double ceill(long double x);$

Return~
x rounded upwards

Description~
These functions round x upwards to the nearest integer, returning that value
as a double. Thus, ceil(1.5)$ is 2.0.



floor() Functions                        *crv-floor* *crv-floorf* *crv-floorl*
-----------------
Synopsis~
 $#include <math.h>$
 $double floor(double x);$
 $float floorf(float x);$ 
 $long double floorl(long double x);$

Return~
x rounded downwards

Description~
These functions round x downwards to the nearest integer, returning that value
as a double. Thus,$floor(1.5)$is 1.0 and$floor(-1.5)$is -2.0.



trunc() Functions                        *crv-trunc* *crv-truncf* *crv-truncl*
-----------------
Synopsis~
 $#include <math.h>$
 $double trunc(double x);$
 $float truncf(float x);$ 
 $long double truncl(long double x);$

Return~
x rounded towards zero

Description~
These functions round x towards zero to the nearest integer (returned in
floating-point format). Thus,$trunc(1.5)$is 1.0 and$trunc(-1.5)$is -1.0.



rint() Functions                            *crv-rint* *crv-rintf* *crv-rintl*
----------------
Synopsis~
 $#include <math.h>$
 $double rint(double x);$
 $float rintf(float x);$ 
 $long double rintl(long double x);$

Return~
x rounded according to rounding mode

Description~
These functions round x to an integer value according to the current rounding
mode (for modes see "II.6.3 Rounding" |crv-libFHRounding|). The default
rounding mode is to round to the nearest integer.
If x was not initially an integer, these functions raise the inexact
exception.


                                                               *crv-nearbyint*
nearbyint() Functions                        *crv-nearbyintf* *crv-nearbyintl*
---------------------
Synopsis~
 $#include <math.h>$
 $double nearbyint(double x);$
 $float nearbyintf(float x);$ 
 $long double nearbyintl(long double x);$

Return~
x rounded according to rounding mode

Description~
These functions return the same value as the$rint()$functions, but do not
raise the inexact exception if x is not an integer.



round() Functions                        *crv-round* *crv-roundf* *crv-roundl*
-----------------
Synopsis~
 $#include <math.h>$
 $double round(double x);$
 $float roundf(float x);$ 
 $long double roundl(long double x);$

Return~
see description

Description~
These functions are similar to$rint()$, but they round halfway cases away from
zero instead of to the nearest even integer.



lrint() Functions                        *crv-lrint* *crv-lrintf* *crv-lrintl*
-----------------
Synopsis~
 $#include <math.h>$
 $long int lrint(double x);$
 $long int lrintf(float x);$ 
 $long int lrintl(long double x);$

Return~
x rounded according to rounding mode

Description~
These functions are just like$rint()$, but they return a$long int$instead of
a floating-point number.



llrint() Functions                    *crv-llrint* *crv-llrintf* *crv-llrintl*
------------------
Synopsis~
 $#include <math.h>$
 $long long int llrint(double x);$
 $long long int llrintf(float x);$ 
 $long long int llrintl(long double x);$

Return~
x rounded according to rounding mode

Description~
These functions are just like$rint()$, but they return a$long long int$instead
of a floating-point number.



lround() Functions                    *crv-lround* *crv-lroundf* *crv-lroundl*
------------------
Synopsis~
 $#include <math.h>$
 $long int lround(double x);$
 $long int lroundf(float x);$ 
 $long int lroundl(long double x);$

Return~
x rounded

Description~
These functions are just like$round()$, but they return a$long int$instead of
a floating-point number.



llround() Functions                *crv-llround* *crv-llroundf* *crv-llroundl*
-------------------
Synopsis~
 $#include <math.h>$
 $long long int llround(double x);$
 $long long int llroundf(float x);$ 
 $long long int llroundl(long double x);$

Return~
x rounded

Description~
These functions are just like$round()$, but they return a$long long int$
instead of a floating-point number.



------------------------------------------------------------------------------
II.12.10  Remainder                                             *crv-libMHRem*


fmod() Functions                            *crv-fmod* *crv-fmodf* *crv-fmodl*
----------------
Synopsis~
 $#include <math.h>$
 $double fmod(double x, double y);$
 $float fmodf(float x, float y);$ 
 $long double fmodl(long double x, long double y);$

Return~
see description

Description~
These functions compute the remainder from the division of x by. Specifically,
the return value is x - n*y, where n is the quotient of x divided by y,
rounded towards zero to an integer. Thus,$fmod(6.5, 2.3)$ returns 1.9, which
is 6.5 minus 4.6.
The result has the same sign as x and has magnitude less than the magnitude
of y.
If y is zero,$fmod()$signals a domain error.


                                                               *crv-remainder*
remainder() Functions                        *crv-remainderf* *crv-remainderl*
---------------------
Synopsis~
 $#include <math.h>$
 $double remainder(double x, double y);$
 $float remainderf(float x, float y);$ 
 $long double remainderl(long double x, long double y);$

Return~
see description

Description~
These functions are like$fmod()$except that they rounds the internal quotient
n to the nearest integer instead of towards zero to an integer.
For example,$remainder(6.5, 2.3)$returns -0.4, which is 6.5 minus 6.9. 

The absolute value of the result is less than or equal to half the absolute
value of y. The difference between$fmod(x, y)$and$remainder(x, y)$is always
either y, -y, or zero. 
If denominator is zero,$remainder()$signals a domain error.



remquo() Functions                    *crv-remquo* *crv-remquof* *crv-remquol*
------------------
Synopsis~
 $#include <math.h>$
 $double remquo(double x, double y, int *quo);$
 $float remquof(float x, float y, int *quo);$ 
 $long double remquol(long double x, long double y, int *quo);$

Return~
see description

Description~
These functions compute the same remainder as the$remainder()$functions.
In *quo they store a value whose sign is the singe of x/y and whose
magnitude is congruent modulo 2^n to the magnitude of the integral quotient
of x/y, where n is an implementation-defined integer greater or equal to 3.



------------------------------------------------------------------------------
II.12.11  Manipulating                                         *crv-libMHMani*


                                                                *crv-copysign*
copysign() Functions                           *crv-copysignf* *crv-copysignl*
--------------------
Synopsis~
 $#include <math.h>$
 $double copysign(double x, double y);$
 $float copysignf(float x, float y);$ 
 $long double copysignl(long double x, long double y);$

Return~
x with sign of y

Description~
These functions return x but with the sign of y. They work even if x or y are
NaN or zero. Both of these can carry a sign (although not all implementations
support it).
$copysign()$never raises an exception. 



signbit() Macro                                                  *crv-signbit*
---------------
Synopsis~
 $#include <math.h>$
 $int signbit(float-type x);$

Return~
0: x has no negative sign
else x has negative sign

Description~
This is a generic macro which works on all floating-point types.
This macro returns a nonzero value if x is negative.
This is not the same as x < 0.0, because IEEE 754 floating point allows zero
to be signed. The comparison -0.0 < 0.0 is false, but$signbit(-0.0)$ will
return a nonzero value. 


                                                               *crv-nextafter*
nextafter() Functions                        *crv-nextafterf* *crv-nextafterl*
---------------------
Synopsis~
 $#include <math.h>$
 $double nextafter(double x, double y);$
 $float nextafterf(float x, float y);$ 
 $long double nextafetl(long double x, long double y);$

Return~
see description

Description~
These functions return the next representable neighbor of x in the direction
towards y. The size of the step between x and the result depends on the type
of the result. If x = y the function simply returns y. If either value is
NaN, NaN is returned. Otherwise a value corresponding to the value of the
least significant bit in the mantissa is added or subtracted, depending on
the direction.
$nextafter()$will signal overflow or underflow if the result goes outside of
the range of normalized numbers. 


                                                              *crv-nexttoward*
nexttoward() Functions                     *crv-nexttowardf* *crv-nexttowardl*
----------------------
Synopsis~
 $#include <math.h>$
 $double nexttoward(double x, long double y);$
 $float nexttowardf(float x, long double y);$ 
 $long double nexttowardl(long double x, long double y);$

Return~
see description

Description~
These functions are identical to the corresponding versions of$nextafter()$ 
except that their second argument is a long double. 



nan() Functions                                *crv-nan* *crv-nanf* *crv-nanl*
---------------
Synopsis~
 $#include <math.h>$
 $double nan(const char *tagp);$
 $float nanf(const char *tagp);$ 
 $long double nanl(const char *tagp);$

Return~
NaN

Description~
These functions return a representation of NaN, provided that NaN is supported
by the target platform.$nan("n-char-sequence")$is equivalent to
$strtod("NAN(n-char-sequence)")$. 

The argument tagp is used in an unspecified manner. On IEEE 754 systems, there
are many representations of NaN, and tagp selects one. On other systems it may
do nothing.




------------------------------------------------------------------------------
II.12.12  Miscellaneous                                        *crv-libMHMisc*


fdim() Functions                            *crv-fdim* *crv-fdimf* *crv-fdiml*
----------------
Synopsis~
 $#include <math.h>$
 $double fdim(double x, double y);$
 $float fdimf(float x, float y);$ 
 $long double fdiml(long double x, long double y);$

Return~
positive difference

Description~
These functions return the positive difference between x and y. The positive
difference is x - y if x is greater than y, and 0 otherwise.
If x, y, or both are NaN, NaN is returned. 



fmin() Functions                            *crv-fmin* *crv-fminf* *crv-fminl*
----------------
Synopsis~
 $#include <math.h>$
 $double fmin(double x, double y);$
 $float fminf(float x, float y);$ 
 $long double fminl(long double x, long double y);$

Return~
minimum of x and y

Description~
These functions return the lesser of the two values x and y. It is similar to
the expression ((x) < (y) ? (x) : (y)) except that x and y are only evaluated
once. 
If an argument is NaN, the other argument is returned. If both arguments are
NaN, NaN is returned. 



fmax() Functions                            *crv-fmax* *crv-fmaxf* *crv-fmaxl*
----------------
Synopsis~
 $#include <math.h>$
 $double fmax(double x, double y);$
 $float fmaxf(float x, float y);$ 
 $long double fmaxl(long double x, long double y);$

Return~
maximum of x and y

Description~
These functions return the greater of the two values x and y.
If an argument is NaN, the other argument is returned. If both arguments are
NaN, NaN is returned.



fma() Functions                                *crv-fma* *crv-fmaf* *crv-fmal*
----------------
Synopsis~
 $#include <math.h>$
 $double fma(double x, double y, double z);$
 $float fmaf(float x, float y, float z);$ 
 $long double fmal(long double x, long double y, long double z);$

Return~

Description~
These functions perform floating-point multiply-add. This is the operation
(x * y) + z, but the intermediate result is not rounded to the destination
type. This can sometimes improve the precision of a calculation.

This function was introduced because some processors have a special
instruction to perform multiply-add. The C compiler cannot use it directly,
because the expression x*y + z is defined to round the intermediate result.
$fma()$lets you choose when you want to round only once. 

                                                             *crv-FP_FAST_FMA*
                                         *crv-FP_FAST_FMAF* *crv-FP_FAST_FMAL*
On processors which do not implement multiply-add in hardware,$fma$can be
very slow since it must avoid intermediate rounding. 
math.h defines the symbols$FP_FAST_FMA$,$FP_FAST_FMAF$, and$FP_FAST_FMAL$ when
the corresponding version of$fma()$is no slower than the expression x*y + z.




==============================================================================
II.13  <setjmp.h> Nonlocal Jumps                              *crv-libSetjmpH*

This header file provides a function, a macro and a data type to perform
nonlocal exits. Typically this is used to do an intermediate return from a
nested function call.

Quicklink:
    $jmp_buf$   Type    |crv-libjmp_buf|
    $longjmp()$ Func    |crv-liblongjmp|
    $setjmp()$  Macro   |crv-libsetjmp|



jmp_buf Type                                                     *crv-jmp_buf*
------------
Objects of type$jmp_buf$hold the state information to be restored by a
nonlocal exit. The contents of a$jmp_buf$identify a specific place to return
to.



setjmp() Macro                                                    *crv-setjmp*
--------------
Synopsis~
 $#include <setjmp.h>$
 $int setjmp(jmp_buf state);$

Return~
0:   if normally executed
!=0: value passed to$longjmp()$

Description~
When called normally,$setjmp()$stores information about the execution state of
the program in$state$and returns zero. If$longjmp()$is later used to perform
a nonlocal exit to this state,$setjmp()$returns a nonzero value. 

Calls to$setjmp()$are safe in only the following contexts: 
  - As the test expression of a selection or iteration statement (such as$if,$
   $switch$, or$while$). 
  - As one operand of a equality or comparison operator that appears as the
    test expression of a selection or iteration statement. The other operand
    must be an integer constant expression. 
  - As the operand of a unary ! operator, that appears as the test expression
    of a selection or iteration statement. 
  - By itself as an expression statement. 

Return points are valid only during the dynamic extent of the function that
called$setjmp()$to establish them. If returned via$longjmp()$to a return point
that was established in a function that has already returned, unpredictable
and disastrous things are likely to happen.



longjmp() Function                                               *crv-longjmp*
------------------
Synopsis~
 $#include <setjmp.h>$
 $void longjmp(jmp_buf state, int value);$

Return~
none

Description~
This function restores current execution to the state saved in$state$, and
continues execution from the call to$setjmp()$that established that return
point. Returning from$setjmp()$by means of$longjmp()$returns the value
argument that was passed to$longjmp()$, rather than 0. 
(But if value is given as 0, setjmp returns 1). 



==============================================================================
II.14  <signal.h> Signal Handling                             *crv-libSignalH*

This header file defines macros and declares functions for handling signals.

Quicklink:
    $rais()$       Func   |crv-rais|
    $sig_atomic_t$ Type   |crv-sig_atomic_t|
    $SIG_DFL$      Macro  |crv-SIG_DFL| 
    $SIG_ERR$      Macro  |crv-SIG_ERR|
    $SIG_IGN$      Macro  |crv-SIG_IGN|
    $SIGABRT$      Macro  |crv-SIGABRT|  
    $SIGFPE$       Macro  |crv-SIGFPE|
    $SIGILL$       Macro  |crv-SIGILL|
    $SIGINT$       Macro  |crv-SIGINT|
    $signal()$     Func   |crv-signal|
    $SIGSEGV$      Macro  |crv-SIGSEGV|
    $SIGTERM$      Macro  |crv-SIGTERM|



------------------------------------------------------------------------------
II.14.1  Types                                                  *crv-libSHTyp*

sig_atomic_t Type                                           *crv-sig_atomic_t*
-----------------
This is an integer data type. Objects of this type are always accessed
atomically. Reading and writing this data type is guaranteed to happen in a
single instruction, so there's no way for a handler to run "in the middle"
of an access.
The type sig_atomic_t is always an integer data type, but which one it is,
and how many bits it contains, may vary from machine to machine.



------------------------------------------------------------------------------
II.14.2  Signals                                                *crv-libSHSig*

Valid signals are:

    Signal  |  Description
 -----------+---------------------------------------------------
  $SIGABRT$ | abnormal termination (e.g. call of$abort()$)        *crv-SIGABRT*  
  $SIGFPE$  | arithmetic error (e.g. division by zero,             *crv-SIGFPE*
            | overflow)
  $SIGILL$  | illegal instruction                                  *crv-SIGILL*
  $SIGINT$  | interactive attention signal (e.g. interrupt)        *crv-SIGINT*
  $SIGSEGV$ | invalid access to storage                           *crv-SIGSEGV*
  $SIGTERM$ | termination request sent to the program             *crv-SIGTERM*
      
Other signals my be specified by the compiler.

It depends on the machine whether this signals are generated by the system
itself.$raise()$function can be used to send them.



------------------------------------------------------------------------------
II.14.3  Functions                                             *crv-libSHFunc*


signal() Function                                                 *crv-signal*
-----------------
Synopsis~
 $#include <signal.h>$
 $void (*signal(int sig, void (*handler)(int)))(int);$

Return~
- pointer to previous handler, if call was successful
-$SIG_ERR$, if call failed

Description~
This function chooses one of three ways in which receipt of the signal$sig$is
to be handled, these ways are:
                                                   *crv-SIG_DFL* *crv-SIG_IGN*
  - If the value of$handler$is$SIG_DFL$, default handling for that signal
    occurs.
  - If the value of$handler$is$SIG_IGN$, the signal is ignored.
  - If the value of$handler$points to a function, that function is called
    with the argument of the type of signal.

For valid signals see II.14.2 (|crv-libSHSig|).
                                                                 *crv-SIG_ERR*
If the call to signal is successful, then it returns a pointer to the previous
signal handler for the specified signal type. If the call fails, then$SIG_ERR$
is returned and$errno$is set to a positive value.



rais() Function                                                     *crv-rais*
---------------
Synopsis~
 $#include <signal.h>$
 $int raise(int signum);$

Return~
0: signal sent successfully
else: failed

Description~
The raise function sends the signal$signum$to the calling process. 
About the only reason for failure would be if the value of signum is invalid. 




------------------------------------------------------------------------------
II.15  <stdarg.h> Arguments                                   *crv-libStdargH*

This header files defines macros which allow to handle functions with an
unknown number of arguments.
See |crv-fuDefVarPara| for an example.

Quicklink:
    $va_arg()$   Macro  |crv-libva_arg|
    $va_copy()$  Macro  |crv-libva_copy|
    $va_end()$   Macro  |crv-libva_end|
    $va_list$    Type   |crv-libva_list|
    $va_start()$ Macro  |crv-libva_start|


va_list Type                                                     *crv-va_list*
------------
This type is used for argument pointer variables. 


va_start() Macro                                                *crv-va_start*
----------------
Synopsis~
 $#include <signal.h>$
 $void va_start(va_list ap, last-required);$

Return~
none

Description~
This macro initializes the argument pointer variable ap to point to the first
of the optional arguments of the current function; last-required must be the
last required argument to the function. 



va_arg() Macro                                                    *crv-va_arg*
--------------
Synopsis~
 $#include <signal.h>$
 $type va_arg(va_list ap, type);$

Return~
value of next argument

Description~
This macro returns the value of the next optional argument, and modifies the
value of ap to point to the subsequent argument. Thus, successive uses of
$va_arg()$return successive optional arguments. 

The type of the value returned by$va_arg()$is$type$as specified in the call.



va_end() Macro                                                    *crv-va_end*
--------------
Synopsis~
 $#include <signal.h>$
 $void va_end(va_list ap);$

Return~
none

Description~
This ends the use of ap. After a$va_end()$call, further$va_arg()$calls with
the same ap may not work.$va_end()$should be invoked before returning from the
function in which$va_start()$was invoked with the same ap argument.



va_copy() Macro                                                  *crv-va_copy*
---------------
Synopsis~
 $#include <signal.h>$
 $void va_copy (va_list dest, va_list src);$

Return~
none

Description~
The$va_copy()$macro allows copying of objects of type$va_list$even if this is
not an integral type. 
The copies can be used to parse the list of parameters more than once.




==============================================================================
II.16  <stdbool.h> Boolean Type                              *crv-libStdboolH*


bool Macro                                                          *crv-bool*
----------
expands to$_Bool$


true Macro                                                          *crv-true*
----------
expands to integer constant 1


false Macro                                                        *crv-false*
-----------
expands to integer constant 0


__bool_true_false_are_defined Macro        *crv-__bool_true_false_are_defined*
-----------------------------------
expands to integer constant 1




==============================================================================
II.17  <stddef.h> Definitions                                 *crv-libStddefH*

This header file defines some macros and types (some of them are also defined
in other header files).

Quicklink:
     $prtdiff_t$  Type    |crv-prtdiff_t|
     $size_t$     Type    |crv-size_t|
     $wchar_t$    Type    |crv-wchar_t|
     $NULL$       Macro   |crv-NULL|
     $offsetof()$ Macro   |crv-offsetof|


prtdiff_t Type                                                 *crv-prtdiff_t*
--------------
This is the signed integer type of the result of subtracting two pointers.
For example, with the declaration$char *p1, *p2;$, the expression$p2 - p1$is
of type$ptrdiff_t$.


size_t Type                                                       *crv-size_t*
-----------
This is an unsigned integer type used to represent the sizes of objects.
Also declared in$<stdlib.h>$, see |crv-size_t2|.
Also declared in$<string.h>$, see |crv-size_t3|.
Also declared in$<time.h>$,   see |crv-size_t4|.
Also declared in$<stdio.h>$,  see |crv-size_t5|;
Also declared in$<wchar.h>$,  see |crv-size_t6|.


wchar_t Type                                                     *crv-wchar_t*
------------
This data type is used as the base type for wide character strings.
It's range of values can represent distinct codes for all members of the
largest extended character set specified among the supported locales.
Also declared in$<stdlib.h>$, see |crv-libwchar_t2|.
Also declared in$<wchar.h>$,  see |crv-libwchar_t3|.


NULL Macro                                                          *crv-NULL*
----------
Expands to an implementation-defined null pointer constant.
Also defined in$<stdlib.h>$, see |crv-NULL2|.
Also defined in$<string.h>$, see |crv-NULL3|.
Also defined in$<time.h>$,   see |crv-NULL4|.
Also defined in$<stdio.h>$,  see |crv-NULL5|.
Also defined in$<wchar.h>$,  see |crv-NULL6|.



offsetof() Macro                                                *crv-offsetof*
----------------
Synopsis~
 $#include <stddef.h>$
 $size_t offsetof (type, member);$

Return~
offset of$member$in structure$type$

Description~
This expands to an integer constant expression that is the offset of the
structure member named$member$in the structure type$type$.



==============================================================================
II.18  <stdint.h> Integer Type                                *crv-libStdintH*

This header file declares a set of integer types having specified widths and
defines a set of macros to handle them.

Types are defined in the following categories:
  - integer types with a certain exact width
  - integer types having at least a certain width
  - fastest integer types having at least a certain width
  - integer types wide enough to hold pointers
  - integer types having greatest width


------------------------------------------------------------------------------
II.18.1  Integer Types                                        *crv-libSdHType*

II.18.1.1 Exact-Width                                       *crv-libSdHTExact*
----------------------
There are integer types representing exactly N bits. The general form is:
intN_t   (signed width N bits width)
uintN_t  (unsigned width N bits width)

Common types are:
    $int8_t$   $uint8_t$                            *crv-int8_t* *crv-uint8_t*
    $int16_t$  $uint16_t$                         *crv-int16_t* *crv-uint16_t*
    $int32_t$  $uint32_t$                         *crv-int32_t* *crv-uint32_t*
    $int64_t$  $uint64_t$                         *crv-int64_t* *crv-uint64_t*
These types are optional. The compiler is free to declare others (e.g.
$int24_t$).


II.18.1.2 Minimum-Width                                       *crv-libSdHTMin*
-----------------------
There are integer types with at least N bits width. The general form is:
int_leastN_t    (signed with at least N bits width)
uint_leastN_t   (unsigned with at least N bits width)

Common types are:
    $int_least8_t$  $uint_least8_t$                         *crv-int_least8_t*
                                                           *crv-uint_least8_t*
    $int_least16_t$ $uint_least16_t$                       *crv-int_least16_t* 
                                                          *crv-uint_least16_t*
    $int_least32_t$ $uint_least32_t$                       *crv-int_least32_t*
                                                          *crv-uint_least32_t*
    $int_least64_t$ $uint_least64_t$                       *crv-int_least64_t*
                                                          *crv-uint_least64_t*

These types are required. Others may be declared by the compiler.


II.18.1.3 Fastest Minimum-Width                              *crv-libSdHTFast*
-------------------------------
These integer types allow the fastest access while having at least N bits.
The general form is:
int_fastN_t    (fast signed with at least N bits width)
uint_fastN_t   (fast unsigned with at least N bits width)

Common types are:
    $int_fast8_t$  $uint_fast8_t$                            *crv-int_fast8_t*
                                                            *crv-uint_fast8_t*
    $int_fast16_t$ $uint_fast16_t$                          *crv-int_fast16_t* 
                                                           *crv-uint_fast16_t*
    $int_fast32_t$ $uint_fast32_t$                          *crv-int_fast32_t*
                                                           *crv-uint_fast32_t*
    $int_fast64_t$ $uint_fast64_t$                          *crv-int_fast64_t*
                                                           *crv-uint_fast64_t*

These types are required. Others may be declared by the compiler.


II.18.1.4 Greatest-Width                                    *crv-libSdHTGreat*
------------------------
These integer types have the widest range possible on the platform on which
they are being used.
    $intmax_t$    (signed)                                      *crv-intmax_t*
    $uintmax_t$   (unsigned)                                   *crv-uintmax_t*
These types are required.


II.18.1.5 Hold Pointer                                        *crv-libSdHTPtr*
----------------------
These integer types are wide enough to store a pointer of type$void$.
    $intptr_t$    (signed)                                      *crv-intptr_t*
    $uintptr_t$   (unsigned)                                   *crv-uintptr_t*

These types are optional.



------------------------------------------------------------------------------
II.18.2  Limits                                               *crv-libSdHTLim*
                                                     *crv-__STDC_LIMIT_MACROS*
The following macros specify the minimum and maximum of the types declared
in$<stdint.h>$. They are defined only if$__STDC_LIMIT_MACROS$is defined before
including$<stdint.h>$.

II.18.2.1 Exact-Width                                       *crv-libSdHLExact*
---------------------
Signed integer minimum:
  INTN_MIN, N is the number of bits
  Value: -2^(N-1)
  Common macros:
   $INT8_MIN$                                                   *crv-INT8_MIN*
   $INT16_MIN$                                                 *crv-INT16_MIN*
   $INT32_MIN$                                                 *crv-INT32_MIN*
   $INT64_MIN$                                                 *crv-INT64_MIN*

Signed integer maximum:
  INTN_MAX, N is the number of bits
  Value: 2^(N-1) - 1
  Common macros:
   $INT8_MAX$                                                   *crv-INT8_MAX*
   $INT16_MAX$                                                 *crv-INT16_MAX*
   $INT32_MAX$                                                 *crv-INT32_MAX*
   $INT64_MAX$                                                 *crv-INT64_MAX*

Unsigned integer minimum:
  is always 0

Unsigned integer maximum:
  UINTN_MAX, N is the number of bits
  Value: 2^N - 1
  Common macros:
   $UINT8_MAX$                                                 *crv-UINT8_MAX*
   $UINT16_MAX$                                               *crv-UINT16_MAX*
   $UINT32_MAX$                                               *crv-UINT32_MAX*
   $UINT64_MAX$                                               *crv-UINT64_MAX*



II.18.2.2 Minimum-Width                                       *crv-libSdHLMin*
-----------------------
Signed integer minimum:
  INT_LEASTN_MIN, N is the number of bits
  Value: <= -2^(N-1)
  Common macros:
   $INT_LEAST8_MIN$                                       *crv-INT_LEAST8_MIN*
   $INT_LEAST16_MIN$                                     *crv-INT_LEAST16_MIN*
   $INT_LEAST32_MIN$                                     *crv-INT_LEAST32_MIN*
   $INT_LEAST64_MIN$                                     *crv-INT_LEAST64_MIN*

Signed integer maximum:
  INT_LEASTN_MAX, N is the number of bits
  Value: >= 2^(N-1) - 1
  Common macros:
   $INT_LEAST8_MAX$                                       *crv-INT_LEAST8_MAX*
   $INT_LEAST16_MAX$                                     *crv-INT_LEAST16_MAX*
   $INT_LEAST32_MAX$                                     *crv-INT_LEAST32_MAX*
   $INT_LEAST64_MAX$                                     *crv-INT_LEAST64_MAX*

Unsigned integer minimum:
  is always 0

Unsigned integer maximum:
  UINT_LEASTN_MAX, N is the number of bits
  Value: >= 2^N - 1
  Common macros:
   $UINT_LEAST8_MAX$                                     *crv-UINT_LEAST8_MAX*
   $UINT_LEAST16_MAX$                                   *crv-UINT_LEAST16_MAX*
   $UINT_LEAST32_MAX$                                   *crv-UINT_LEAST32_MAX*
   $UINT_LEAST64_MAX$                                   *crv-UINT_LEAST64_MAX*



II.18.2.3 Fastest Minimum-Width                              *crv-libSdHLFast*
-------------------------------
Signed integer minimum:
  INT_FASTN_MIN, N is the number of bits
  Value: <= -2^(N-1)
  Common macros:
   $INT_FAST8_MIN$                                         *crv-INT_FAST8_MIN*
   $INT_FAST16_MIN$                                       *crv-INT_FAST16_MIN*
   $INT_FAST32_MIN$                                       *crv-INT_FAST32_MIN*
   $INT_FAST64_MIN$                                       *crv-INT_FAST64_MIN*

Signed integer maximum:
  INT_FASTN_MAX, N is the number of bits
  Value: >= 2^(N-1) - 1
  Common macros:
   $INT_FAST8_MAX$                                         *crv-INT_FAST8_MAX*
   $INT_FAST16_MAX$                                       *crv-INT_FAST16_MAX*
   $INT_FAST32_MAX$                                       *crv-INT_FAST32_MAX*
   $INT_FAST64_MAX$                                       *crv-INT_FAST64_MAX*

Unsigned integer minimum:
  is always 0

Unsigned integer maximum:
  UINT_FASTN_MAX, N is the number of bits
  Value: >= 2^N - 1
  Common macros:
   $UINT_FAST8_MAX$                                       *crv-UINT_FAST8_MAX*
   $UINT_FAST16_MAX$                                     *crv-UINT_FAST16_MAX*
   $UINT_FAST32_MAX$                                     *crv-UINT_FAST32_MAX*
   $UINT_FAST64_MAX$                                     *crv-UINT_FAST64_MAX*



II.18.2.4 Greatest-Width                                    *crv-libSdHLGreat*
------------------------
Minimum value of greatest-width signed integer type:
$ INTMAX_MIN$   <= -(2^63)                                    *crv-INTMAX_MIN*

Maximum value of greatest-width signed integer type:
$ INTMAX_MAX$   >= 2^63 - 1                                   *crv-INTMAX_MAX*

Minimum value of greatest-width unsigned integer type:
  0
Maximum value of greatest-width unsigned integer type:
$ UINTMAX_MAX$  >= 2^64 - 1                                  *crv-UINTMAX_MAX*



II.18.2.5 Hold Pointer                                        *crv-libSdHLPtr*
----------------------
Minimum value of pointer holding signed integer type:
 $INTPTR_MIN$  <= -(2^15)                                     *crv-INTPTR_MIN*

Maximum value of pointer holding signed integer type:
 $INTPTR_MAX$  >= 2^15 - 1                                    *crv-INTPTR_MAX*

Minimum value of pointer holding unsigned integer type:
  0

Maximum value of pointer holding unsigned integer type:
 $UINTPTR_MAX$ >= 2^16 - 1                                   *crv-UINTPTR_MAX*



II.18.2.6 Others                                            *crv-libSdHLOther*
----------------
Limits of$ptrdiff_t$:
 $PTRDIFF_MIN$                                               *crv-PTRDIFF_MIN*
 $PTRDIFF_MAX$                                               *crv-PTRDIFF_MAX*

Limits of$sig_atomic_t$:
 $SIG_ATOMIC_MIN$                                         *crv-SIG_ATOMIC_MIN*
 $SIG_ATOMIC_MAX$                                         *crv-SIG_ATOMIC_MAX*

Limits of$size_t$:
 $SIZE_MAX$                                                     *crv-SIZE_MAX*

Limits of$wchar_t$:
 $WCHAR_MIN$                                                   *crv-WCHAR_MIN*
 $WCHAR_MAX$                                                   *crv-WCHAR_MAX*
  Also defined in$<wctype.h>$, see |crv-libWCHAR_MIN2|, |crv-libWCHAR_MAX2|.

Limits of$wint_t$:
 $WINT_MIN$                                                     *crv-WINT_MIN*
 $WINT_MAX$                                                     *crv-WINT_MAX*



-----------------------------------------------------------------------------
II.18.3 Macros                                                *crv-libSdHMac*


INTMAX_C() Macro                                               *crv-INTMAX_C*
----------------
Synopsis~
 $#include <stdint.h>$
 $INTMAX_C(val);$

Description~
expands to an integer constant value$val$of type$intmax_t$


UINTMAX_C() Macro                                              *crv-UINTMAX_C*
-----------------
Synopsis~
 $#include <stdint.h>$
 $UINTMAX_C(val);$

Description~
expands to an integer constant value$val$of type$uintmax_t$


                                                    *crv-INT8_C* *crv-INT16_C*
INTN_C() Macro                                     *crv-INT32_C* *crv-INT64_C*
--------------
Synopsis~
 $#include <stdint.h>$
 $INT8_C(val);$
 $INT16_C(val);$
 $INT32_C(val);$
 $INT64_C(val);$

Description~
expands to an integer constant value$val$of type$int_leastN_t$(N number of
bits)


                                                  *crv-UINT8_C* *crv-UINT16_C*
UINTN_C() Macro                                  *crv-UINT32_C* *crv-UINT64_C*
---------------
Synopsis~
 $#include <stdint.h>$
 $UINT8_C(val);$
 $UINT16_C(val);$
 $UINT32_C(val);$
 $UINT64_C(val);$

Description~
expands to an integer constant value$val$of type$uint_leastN_t$(N number of
bits)




==============================================================================
II.19  <stdio.h> Input/Output                                  *crv-libStdioH*

This header file declares types, macros and functions to perform input/output
operations.


------------------------------------------------------------------------------
II.19.1  Types                                               *crv-libSIOHType*

Quicklink:
    $size_t$ Type  |crv-size_t5|
    $FILE$   Type  |crv-FILE|
    $fpos_t$ Type  |crv-fpos_t|


size_t Type                                                      *crv-size_t5*
-----------
This is an unsigned integer type used to represent the sizes of objects.
Also declared in$<stddef.h>$, see |crv-size_t|.
Also declared in$<string.h>$, see |crv-size_t2|.
Also declared in$<stdlib.h>$, see |crv-size_t3|.
Also declared in$<time.h>$,   see |crv-size_t4|.
Also declared in$<wchar.h>$,  see |crv-size_t6|.


FILE Type                                                          *crv-FILE*
---------
This is the data type used to represent stream objects. A FILE object holds
all of the internal state information about the connection to the associated
file.


fpos_t Type                                                       *crv-fpos_t*
-----------
This is the type of an object that can encode information about the file
position of a stream.




------------------------------------------------------------------------------
II.19.2  Macros                                               *crv-libSIOHMac*

Quicklink:
    $_IOFBF$       Macro  |crv-_IOFBF|
    $_IOLBF$       Macro  |crv-_IOLBF|
    $_IONBF$       Macro  |crv-_IONBF|
    $BUFSIZ$       Macro  |crv-BUFSIZ|
    $BUFSIZ$       Macro  |crv-BUFSIZ|
    $FOPEN_MAX$    Macro  |crv-FOPEN_MAX|
    $FILENAME_MAX$ Macro  |crv-FILENAME_MAX|
    $L_tmpnam$     Macro  |crv-L_tmpnam|
    $NULL$         Macro  |crv-NULL5|
    $SEEK_SET$     Macro  |crv-SEEK_SET|
    $SEEK_CUR$     Macro  |crv-SEEK_CUR|
    $SEEK_END$     Macro  |crv-SEEK_END|
    $stderr$       Macro  |crv-stderr|
    $stdin$        Macro  |crv-stdin|
    $stdout$       Macro  |crv-stdout|



NULL Macro                                                         *crv-NULL5*
----------
Expands to an implementation-defined null pointer constant.
Also defined in$<stddef.h>$, see |crv-libNULL|.
Also defined in$<stdlib.h>$, see |crv-libNULL2|.
Also defined in$<string.h>$, see |crv-libNULL3|.
Also defined in$<time.h>$,   see |crv-libNULL4|.
Also defined in$<wchar.h>$,  see |crv-libNULL6|.



_IOFBF Macro                                                      *crv-_IOFBF*
_IOLBF Macro                                                      *crv-_IOLBF*
_IONBF Macro                                                      *crv-_IONBF*
------------
This macros expand to an constant integer expression that can be used as the
mode argument to the$setvbuf()$function.

 $_IOFBF$  specifies that the stream should be fully buffered
 $_IOLBF$  specifies that the stream should be line buffered
 $_IONBF$  specifies that the stream should be unbuffered



BUFSIZ Macro                                                     *crv-BUFSIZ*
------------
The value of this macro is an integer constant expression that is good to use
for the size argument to$setvbuf()$. This value is guaranteed to be at least
256.



EOF Macro                                                            *crv-EOF*
---------
This is returned by a number of narrow stream functions to indicate an
end-of-file condition, or some other error situation.



FOPEN_MAX Macro                                                *crv-FOPEN_MAX*
---------------
The value of this macro is an integer constant expression that represents the
minimum number of streams that the implementation guarantees can be open
simultaneously.



FILENAME_MAX Macro                                          *crv-FILENAME_MAX*
------------------
The value of this macro is an integer constant expression that represents
the maximum length of a file name string.



L_tmpnam Macro                                                  *crv-L_tmpnam*
--------------
The value of this macro is an integer constant expression that represents the
minimum size of a string large enough to hold a file name generated by the
$tmpnam()$function. 




SEEK_SET Macro                                                  *crv-SEEK_SET*
SEEK_CUR Macro                                                  *crv-SEEK_CUR*
SEEK_END Macro                                                  *crv-SEEK_END*
--------------
These are integer constants which are used as the whence argument to the
fseek() or fseeko() functions.

 $SEEK_SET$ specifies that the offset provided is relative to the beginning
            of the file
 $SEEK_CUR$ specifies that the offset provided is relative to the current
            file position
 $SEEK_END$ specifies that the offset provided is relative to the end of the
            file


TMP_MAX Macro                                                    *crv-TMP_MAX*
-------------
This is the maximum number of unique filenames that the function$tmpnam()$can
generate.



stderr Macro                                                      *crv-stderr*
stdin  Macro                                                       *crv-stdin*
stdout Macro                                                      *crv-stdout*
------------
These macros expand to pointers to$FILE$types which correspond to the standard
error, standard input and standard output streams. These streams are text
streams.

The standard input stream is the normal source of input for the program.
The standard output stream is the normal source of output from the program.
The standard error stream is used for error messages and diagnostics issued
by the program.



------------------------------------------------------------------------------
II.19.3  Streams and Files                               *crv-libSIOHStrmFile*

Streams provide a higher-level interface between program and input/output
device. There are two types of streams: text and binary streams.

Text and binary streams differ in several ways:

  - The data read from a text stream is divided into lines which are
    terminated by newline ('\n') characters, while a binary stream is simply a
    long series of characters. 
    A text stream might on some systems fail to handle lines more than 254
    characters long (including the terminating newline character).
    
  - On some systems, text files can contain only printing characters,
    horizontal tab characters, and newlines, and so text streams may not
    support other characters. However, binary streams can handle any character
    value. 

  - Space characters that are written immediately preceding a newline
    character in a text stream may disappear when the file is read in again.

  - More generally, there need not be a one-to-one mapping between characters
    that are read from or written to a text stream, and the characters in the
    actual file. 

Binary streams transfers data without changing (1:1 copy).

On some systems text and binary streams use different file formats, the only
way to read or write "an ordinary file of text" that can work with other
text-oriented programs is through a text stream.

At startup of a program there are three text streams available: standard
input, standard output and standard error. See |crv-libstdout| for further
information.


Files are associated with streams. A file must be opened to be used. One of
the attributes of an open file is its file position that keeps track of where
in the file the next character is to be read or written. 
The file position is normally set to the beginning of the file when it is
opened, and each time a character is read or written, the file position is
incremented, so access to the file is normally sequential. 

Ordinary files permit read or write operations at any position within the
file. Some other kinds of files may also permit this. Files which do permit
this are sometimes referred to as random-access files. The file position
can be changed using the$fseek()$function on a stream.

Streams that are opened for append access are treated specially for output:
output to such files is always appended sequentially to the end of the
file, regardless of the file position. However, the file position is still
used to control where in the file reading is done. 

Each opening of a file creates a separate file position. Thus, if a file is
opened twice - even in the same program - two streams with independent
file positions are generated.


An open file must be closed,$fclose()$can be used to do that. If$main()$
returns or$exit()$is called, all opened files are closed automatically.
Other path to program termination (e.g.$abort()$) do not need to close
files (dependes on compiler).



------------------------------------------------------------------------------
II.19.4  File Operations                                      *crv-libSIOHFOp*


remove() Function                                                 *crv-remove*
-----------------
Synopsis~
 $#include <stdio.h>$
 $int remove(const char *file_name);$

Return~
0:       successful
nonzero: failed

Description~
Remove the file (unlink it) with name$*file$points to. Any subsequent attempt
to open it again will fail. If the file is currently open, then the result is
implementation-defined.



rename() Function                                                 *crv-rename*
-----------------
Synopsis~
 $#include <stdio.h>$
 $int rename(const char *oldname, const char *newname);$

Return~
0:    successful
else: failed

Description~
This function renames the file$oldname$to$newname$. The file formerly
accessible under the name$oldname$is afterwards accessible as$newname$instead.
If the new file exists before renaming, then the result is
implementation-defined.



tmpfile() Function                                               *crv-tmpfile*
------------------
Synopsis~
 $#include <stdio.h>$
 $FILE *tmpfile(void);$

Return~
NULL:  failed
else:  pointer to stream of the created file

Description~
This function creates a temporary binary file for update mode, as if by
calling$fopen()$with mode "wb+". The file is deleted automatically when it is
closed or when the program terminates.



tmpnam() Function                                                 *crv-tmpnam*
-----------------
Synopsis~
 $#include <stdio.h>$
 $char *tmpnam(char *result);$

Return~
NULL:  failed
else:  pointer to name of file

Description~
This function constructs and returns a valid file name that does not refer to
any existing file. If the$result$argument is a null pointer, the return value
is a pointer to an internal static string, which might be modified by
subsequent calls. Otherwise, the$result$argument should be a pointer to an
array of at least$L_tmpnam$characters, and the result is written into that
array. In this case the value of the argument is returned.
Each call of$tmpnam()$generates a different name, up to$TMP_MAX$times.




------------------------------------------------------------------------------
II.19.5  File Access                                         *crv-libSIOHFAcc*


fclose() Function                                                 *crv-fclose*
-----------------
Synopsis~
 $#include <stdio.h>$
 $int fclose(FILE *stream);$

Return~
0:    success
EOF:  failed

Description~
This function causes$stream$to be closed and the connection to the
corresponding file to be broken. Any buffered output is written and any
buffered input is discarded.



fflush() Function                                                 *crv-fflush*
-----------------
Synopsis~
 $#include <stdio.h>$
 $int fflush(FILE *stream);$

Return~
0:    success
EOF:  failed

Description~
This function causes any buffered output on$stream$to be delivered to the
file. If$stream$is a null pointer, then$fflush()$causes buffered output on all
open output streams to be flushed.



fopen() Function                                                   *crv-fopen*
----------------
Synopsis~
 $#include <stdio.h>$
 $FILE *fopen(const char *file_name, const char *opentype);$

Return~
NULL:  failed
else:  pointer to stream of opened file

Description~
This function opens a stream for I/O to the file$file_name$, and returns a
pointer to the stream.
The$opentype$argument is a string that controls how the file is opened and
specifies attributes of the resulting stream. It must begin with one of the
following sequences of characters, other may follow (implementation-defined):

      Mode    |  Description
  ------------+--------------------------------------------------------------
      $r$     | open text file for reading
      $w$     | truncate to zero length or create text file for writing
      $a$     | append; open or create text file for writing at end-of-file
      $rb$    | open binary file for reading
      $wb$    | truncate to zero length or create binary file for writing
      $ab$    | append; open or create binary file for writing at end-of-file
      $r+$    | open text file for reading and writing
      $w+$    | truncate to zero length or create text file for reading and
              | writing
      $a+$    | append; open or create text file for reading and writing,
              | writing at end-of-file 
  $r+b or rb+$| open binary file for reading and writing
  $w+b or wb+$| truncate to zero length or create binary file for reading
              | and writing
  $a+b or ab+$| append; open or create binary file for reading and writing,
              | writing at end-of-file




freopen() Function                                               *crv-freopen*
------------------
Synopsis~
 $#include <stdio.h>$
 $FILE *freopen(const char *file_name, const char *opentype, FILE *stream);$

Return~
NULL:  failed
else:  pointer to stream of opened file

Description~
This function is like a combination of$fclose()$and$fopen()$. It first closes
the stream referred to by$stream$, ignoring any errors that are detected in
the process. Then the file named by$file_name$is opened with mode$opentype$as
for$fopen()$, and associated with the same stream object$stream$.

This is traditionally been used to connect a standard stream such as$stdin$
with a file.



setbuf() Function                                                 *crv-setbuf*
-----------------
Synopsis~
 $#include <stdio.h>$
 $void setbuf(FILE *stream, char *buf);$

Return~
none

Description~
If$buf$is a null pointer, the effect of this function is equivalent to calling
$setvbuf()$with a mode argument of$_IONBF$. Otherwise, it is equivalent to
calling$setvbuf()$with$buf$, and a mode of$_IOFBF$and a size argument of
$BUFSIZ$.

This function is provided for compatibility with old code; use$setvbuf()$in
all new programs.



setvbuf() Function                                               *crv-setvbuf*
------------------
Synopsis~
 $#include <stdio.h>$
 $int setvbuf(FILE *stream, char *buf, int mode, size_t size);$

Return~
0:       success
nonzero: failed

Description~
This function is used to specify that the stream$stream$should have the
buffering mode$mode$, which can be:

$_IOFBF$ full buffering              |crv-lib_IOFBF|
$_IOLBF$ line buffering              |crv-lib_IOLBF|
$_IONBF$ unbuffered input/output     |crv-lib_IONBF|

If a null pointer as the$buf$argument is specified, then$setvbuf()$allocates
a buffer itself. This buffer will be freed when closing the stream.

Otherwise,$buf$should be a character array that can hold at least$size$
characters. This space should not be freed as long as the stream remains open
and this array remains its buffer.




------------------------------------------------------------------------------
II.19.6  Formatted Input/Output                                *crv-libSIOHIO*


II.19.6.1 Format Control                                 *crv-libSIOHIOFormat*
------------------------

II.19.6.1.1  Output, printf()                              *crv-libSIOHIOFout*
-----------------------------
The family of printf() functions write output to a stream, under control of
the format string. The format specifies how subsequent arguments are converted
to output.
A format string for output has the following syntax:
 $%[flags][width][.precision][modifier]type$

[flags]       control convertion (optional)
[width]       number of characters to output (optional)
[.precision]  precision of number (optional)
[modifier]    overrides size (type) of argument (optional)
[type]        type of conversion (required)


[flag]  control convertion (optional)

   zero or more flags may be specified

   flag | Description
 -------+---------------------------------------------------------------------
   $-$  | value is left-justified (default is right-justified)
   $+$  | forces to show sign of value (+ or -)
        | default is to show only - for negative values, overrules space
  space | print " " in front of positive value, print - for negative value
   $#$  | convert to alternative form:
        |  $o$       increase precision to force the first digit to be a zero
        |
        |  $x$or$X$  nonzero result will have prefix "0x" or "0X"
        |
        |  $a$,$A$,
        |  $e$,$E$, 
        |  $f$,$F$,
        |  $g$or$G$  result will always have decimal point
        |
        |  $g$or$G$  trailing zeros are not removed
        |
   $0$  | for $d, i, o, u, x, X, a, A, e, E, f, F, g, G$conversions leading
        | zeros are used to pad to the field width instead of spaces


[width]  number of characters to output (optional)
  This is a decimal integer specifying the minimum field width. If the normal
  conversion produces fewer characters than this, the field is padded with
  spaces to the specified width. If the normal conversion produces more
  characters than this, the field is not truncated. Normally, the output is
  right-justified within the field.
  A field width of$*$may be specified. This means that the next argument
  in the argument list (before the actual value to be printed) is used as the
  field width. The value must be an integer of type$int$. If the value is
  negative, this means to set the$-$flag and to use the absolute value as
  the field width.

[.precision]  precision of number (optional)
  The precision specifies the number of digits to be written for the numeric
  conversions. If the precision is specified, it consists of a period ($.$)
  followed optionally by a decimal integer (which defaults to zero if
  omitted).

  A precision of$*$may be specified. This means that the next argument
  in the argument list (before the actual value to be printed) is used as the
  precision. The value must be an integer of type$int$, and is ignored if it
  is negative.
  If$*$is specified for both the field width and precision, the field width
  argument precedes the precision argument.


  precision | Description
 -----------+-----------------------------------------------------------------
    (none)  | default precision:
            | 1 for$d, i, o, u, x, X$types. Precision gives the minimum number
            | of digits to appear.
            | 6 for$f, F, e, E$types. Precision gives the number of digits to
            | appear after decimal point.
            | For$g, G$types all digits are printed.
            | For$s$type all characters of the string are printed, not
            | including the terminating null character.
            | For$a, A$and$FLT_RADIX$of 2: precision is sufficient for an
            | exact representation of the value.
            | For$a, A$and$FLT_RADIX$not equal to 2: precision is sufficient
            | to distinguish values of type$double$.
            |
  $.$or$.0$ | For$d, i, o, u, x, X$types the default precision is used, unless
            | the value is 0, then no characters are printed.
            | For$f, F, e, E$types no decimal-point and no decimal-digits are
            | printed..
            | For$g, G$types precision is assumed to be 1.
            | For$s$type nothing is printed.
            | For$a, A$types no decimal-point and no decimal-digits appear.
            |
    $.N$    | For$d, i, o, u, x, X$types. At least N digits appear, if 
            | necessary output is expanded with leading zeros.
            | For$f, F, e, E$types. N digits appear after decimal point.
            | For$g, G$types N digits are printed.
            | For$s$type a maximum of N characters of the string are printed,
            | not including the terminating null character.
            | For$a, A$types N specifies the number of digits after decimal 
            | point.
            |



[modifier]  overrides size (type) of argument (optional)
  The modifier character is used to specify the data type of the corresponding
  argument if it differs from the default type.


  modifier | Description
 ----------+------------------------------------------------------------------
    $hh$   | Specifies that the argument is a$signed char$or$unsigned char$, 
           | as appropriate. A$char$argument is converted to an$int$or
           |$unsigned int$by the default argument promotions anyway, but this
           | modifier says to convert it back to a$char$again.
           |
    $h$    | Specifies that the argument is a$short int$or$unsigned short int$
           | as appropriate. A$short$argument is converted to an$int$or
           |$unsigned int$by the default argument promotions anyway, but this
           | modifier says to convert it back to a$short$again.
           |
    $l$    | Specifies that the argument is a$long int$or$unsigned long int$,
           | as appropriate. Two l characters is like the L modifier, below
           | If used with$%c$or$%s$the corresponding parameter is considered
           | as a wide character or wide character string respectively.
           |
    $ll$   | Specifies that a following$d, i, o, u, x, X$applies to a
           |$long long int$or$unsigned long long int$argument; or that a
           |$n$applies to a pointer to$long long int$.
           |
    $L$    | Specifies that a following$a, A, e, E, f, F, g, G$conversion
           | specifier applies to a$long double$argument.
           |
    $j$    | Specifies that a following$d, i, o, u, x, X$applies to$intmax_t$
           | or$uintmax_t$, or that a following$n$applies to pointer to
           |$intmax_t$.
           |
    $t$    | Specifies that a following$d, i, o, u, x, X$applies to a
           |$ptrdiff_t$or the corresponding unsigned integer type argument;
           | or that a$n$applies to a pointer to a$ptrdiff_t$argument.
           |
    $z$    | Specifies that the following$d, i, o, u, x, X$applies to a
           |$size_t$or the corresponding singed integer type argument;
           | or that a$n$applies to a pointer to a signed integer type
           | corresponding to$size_t$argument.


[type]  type of conversion (required)

  The conversion specifier specifies the conversion to be applied.

   type  | Description
 --------+------------------------------------------------------------------
 $ d, i$ | type$signed int$,   output decicmal, style [-]dddd
    $o$  | type$unsigned int$, output octal,    style:  dddd
    $u$  | type$unsigned int$, output decimal,  style   dddd
    $x$  | type$unsigned int$, output hexadecimal, style dddd using a...f
    $X$  | type$unsigned int$, output hexadecimal, style dddd using A...F
  $f, F$ | type$double$, output decimal, style [-]ddd.ddd
    $e$  | type$double$, output decimal, style [-]d.ddde+/-dd
    $E$  | type$double$, output decimal, style [-]d.dddE+/-dd
    $g$  | type$double$, printed as type$e$if exponent is less than -4
         | or greater than or equal to the precision. Otherwise$f$is used.
    $G$  | type$double$, printed as type$E$if exponent is less than -4
         | or greater than or equal to the precision. Otherwise$F$is used.
    $a$  | type$double$, style [-]0xh.hhhhp+/-d
         |                          h: hexadecimal digit 0...9, a...f
         |                          d: decimal digit
    $A$  | type$double$, style [-]0Xh.hhhhP+/-d
         |                          h: hexadecimal digit 0...9, A...F
         |                          d: decimal digit
    $c$  | no$l$modifier:   type$char$, single character is printed
         | with$l$modifier: type$wchar_t$, single character is printed 
    $s$  | no$l$modifier:   pointer to array of$char$, string is printed
         | with$l$modifier: pointer to array of$char$, string is printed 
    $p$  | type pointer to$void$, value of pointer is printed in an
         | implementation-defined way
    $n$  | argument is a pointer to$signed int$into which is written the
         | number of characters written to the output stream so far
    $%$  | a % is printed




II.19.6.1.2  Input, scanf()                                 *crv-libSIOHIOFin*
---------------------------
The family of scanf() functions read input from a stream, under control of
the format string. The format specifies how the input is to be stored in
the appropriate variable(s).
A white-space character may match with any whitespace character (space, tab,
carriage return, new line, vertical tab, or formfeed).
Other characters in the format string that are not part of conversion
specifications must match characters in the input stream exactly; if this is
not the case, a matching failure occurs and scanning is stopped.

A format string for input has the following syntax:
 $%[*][width][modifier]type$

[*]          assignment suppressor (optional)
[width]      maximum number of characters to be read (optional)
[modifier]   overrides size (type) of argument (optional)
[type]       type of conversion (required)


[*]  assignment suppressor (optional)
  The assignment suppressor$*$says to ignore the text read for this
  specification. When scanf() finds a conversion specification that uses this
  flag, it reads input as directed by the rest of the conversion
  specification, but it discards this input, does not use a pointer argument,
  and does not increment the count of successful assignments.


[width]  maximum number of characters to be read (optional)
  This is a decimal integer that specifies the maximum field width. Reading of
  characters from the input stream stops either when this maximum is reached
  or when a non-matching character is found, whichever happens first. Then
  what was read so far is converted and stored in the variable.

  Most conversions discard initial whitespace characters (those that don't are
  explicitly documented), and these discarded characters don't count towards
  the maximum field width. String input conversions store a null character 
  to mark the end of the input; the maximum field width does not include this
  terminator.


[modifier]  overrides size (type) of argument (optional)
  The modifier character is used to specify the data type of the corresponding
  argument if it differs from the default type.

  
  modifier | Description
 ----------+------------------------------------------------------------------
    $hh$   | Specifies that a following$d, i, o, u, x, X, n$conversion applies
           | to an argument with type pointer to$signed char$or
           | $unsigned char$
           |
    $h$    | Specifies that a following$d, i, o, u, x, X, n$conversion applies
           | to an argument with type pointer to$short int$or$unsigned short$.
           |
    $l$    | Specifies that a following$d, i, o, u, x, X, n$conversion applies
           | to an argument with type pointer to$long int$or
           |$unsigned long int$; or that a following$a, A, e, E, f, F, g, G$
           | converstion applies to an argument with type pointer to$double$;
           | or that a following$c, s, [$conversion applies to an argument 
           | with type pointer to$wchar_t$.
           |
    $ll$   | Specifies that a following$d, i, o, u, x, X, n$argument applies
           | to an argument with type pointer to$long long int$or
           | $unsigned long long int$.
           |
    $L$    | Specifies that a following$a, A, e, E, f, F, g, G$conversion
           | applies to an argument of type pointer to$long double$argument.
           |
    $j$    | Specifies that a following$d, i, o, u, x, X, n$conversion applies
           | to an argument with type pointer to$intmax_t$or$uintmax_t$.
           |
    $t$    | Specifies that a following$d, i, o, u, x, X, n$conversion applies
           | to an argument of type pointer to$ptrdiff_t$or the corresponding
           | unsigned integer type.
           |
    $z$    | Specifies that a following$d, i, o, u, x, X, n$conversion applies
           | to an argument of type pointer to$size_t$or the corresponding
           | singed integer type.



[type]  type of conversion (required)

  The conversion specifier specifies the conversion to be applied.

   type  | Description
 --------+--------------------------------------------------------------------
 $   d $ | type$signed int$,  matches an optionally signed integer written
         | in decimal
         |
    $i$  | type$signed int$,  matches an optionally signed integer in any of
         | the formats that the C language defines for specifying an integer
         | constant. The based used depends on the first two characters:
         |  - first character 1...9, then base 10 (decimal)
         |  - first digit 0, followed by 0..7, then base 8 (octal)
         |  - first digit 0, followed by x or X, then base 16 (hexadecimal)
         |
    $o$  | type$unsigned int$, matches octal numbers (digits 0...7 only)
         |
    $u$  | type$unsigned int$, matches decimal numbers (digits 0...9 only)
         |
  $x, X$ | type$unsigned int$, matches hexadecimal numbers (characters 0...9,
         | a-f, A-F only). The number may be prefixed with 0x or 0X.
         |
  $f, F$ | matches an optionally signed floating point number
  $e, E$ |
  $g, G$ |
  $a, A$ |
         |
    $c$  | Matches a string of one or more characters; the number of
         | characters read is controlled by the maximum field width given for
         | the conversion. No null character is appended.
         | no$l$modifier:   argument is of type pointer to array of$char$
         | with$l$modifier: argument is of type pointer to array of$wchar_t$ 
         |
    $s$  | Matches a sequence of non-white-space characters. A null
         | character is appended.
         | no$l$modifier:   argument is of type pointer to array of$char$
         | with$l$modifier: argument is of type pointer to array of$wchar_t$
         |
 $ [...]$| Matches a nonempty sequence of characters from a set of expected
         | characters enclosed in brackets [...] (scanset). If the first
         | character is a circumflex (^), the selection is inverted, in that
         | case the scanset contains all characters that do NOT appear in the
         | list between [^ and ].
         | A null character is appended.
         | no$l$modifier:   argument is of type pointer to array of$char$
         | with$l$modifier: argument is of type pointer to array of$wchar_t$
         |
    $p$  | Matches a pointer value in the same implementation-defined format
         | used by the$%p$output conversion for printf().
         |
    $n$  | No input is consumed. It records the number of characters read so
         | far by this call. Argument is a pointer to$signed int$into which is
         | written the number of characters read from the input stream so far.
         |
    $%$  | Matches a single %. No conversion or assignment occurs.




II.19.6.2 Functions                                        *crv-libSIOHIOFunc*
-------------------

Quicklink
    $printf()$   Func  |crv-printf|
    $fprintf()$  Func  |crv-fprintf|
    $sprintf()$  Func  |crv-sprintf|
    $snprintf()$ Func  |crv-snprintf|
    $vfprintf()$ Func  |crv-vfprintf|
    $vprintf()$  Func  |crv-vprintf|
    $vsprintf()$ Func  |crv-vsprintf|
    $vsnprintf()$Func  |crv-vsnprintf|
    
    $fscanf()$   Func  |crv-fscanf|
    $scanf()$    Func  |crv-scanf|
    $sscanf()$   Func  |crv-sscanf|
    $vfscanf()$  Func  |crv-vfscanf|
    $vscanf()$   Func  |crv-vscanf|
    $vsscanf()$  Func  |crv-vsscanf|



printf() Function                                                 *crv-printf*
-----------------
Synopsis~
 $#include <stdio.h>$
 $int printf(const char *format, ...);$

Return~
<0:      output error occurred
>= 0:    number of transmitted characters

Description~
This function prints the optional arguments under the control of the format 
string$format$to the standard output stream$stdout$.
For format string see |crv-libSIOHIOFout|.



fprintf() Function                                               *crv-fprintf*
------------------
Synopsis~
 $#include <stdio.h>$
 $int fprintf(FILE *stream, const char *format, ...);$

Return~
<0:      output error occurred
>= 0:    number of transmitted characters

Description~
This function is equivalent to$printf()$, except that the output is written
to the stream$stream$instead of$stdout$.



sprintf() Function                                               *crv-sprintf*
------------------
Synopsis~
 $#include <stdio.h>$
 $int sprintf(char *s, const char *format, ...);$

Return~
<0: error occurred
number of characters stored in array, not including terminating null character

Description~
This is like$printf()$, except that the output is stored in the character
array$s$instead of written to a stream. A null character is written to mark
the end of the string.



snprintf() Function                                             *crv-snprintf*
-------------------
Synopsis~
 $#include <stdio.h>$
 $int snprintf(char *s, size_t size, const char *format, ...);$

Return~
<0: error occurred
The return value is the number of characters which would be generated for the
given input, excluding the trailing null. If this value is greater or equal
to$size$, not all characters from the result have been stored in$s$.

Description~
This function is similar to$sprintf()$, except that the$size$argument
specifies the maximum number of characters to produce. The trailing null
character is counted towards this limit. 



vprintf() Function                                               *crv-vprintf*
------------------
Synopsis~
 $#include <stdarg.h>$
 $#include <stdio.h>$
 $int vprintf(const char *format, va_list ap);$

Return~
<0:      output error occurred
>= 0:    number of transmitted characters

Description~
This function is similar to$printf()$except that, instead of taking a variable
number of arguments directly, it takes an argument list pointer$ap$, which
must have been initialized by the$va_start()$macro. The$vprintf()$function
does not invoke the$va_end()$macro.



vfprintf() Function                                             *crv-vfprintf*
-------------------
Synopsis~
 $#include <stdarg.h>$
 $#include <stdio.h>$
 $int vfprintf(FILE *stream, const char *format, va_list ap);$

Return~
<0:      output error occurred
>= 0:    number of transmitted characters

Description~
This function is similar to$fprintf()$except that, instead of taking a
variable number of arguments directly, it takes an argument list pointer$ap$,
which must have been initialized by the$va_start()$macro. The$vfprintf()$
function does not invoke the$va_end()$macro.



vsprintf() Function                                             *crv-vsprintf*
-------------------
Synopsis~
 $#include <stdarg.h>$
 $#include <stdio.h>$
 $int vsnprintf(char *s, size_t size, const char *format, va_list ap);$

Return~
<0: error occurred
number of characters stored in array, not including terminating null character

Description~
This function is similar to$sprintf()$except that, instead of taking a
variable number of arguments directly, it takes an argument list pointer$ap$,
which must have been initialized by the$va_start()$macro. The$vsprintf()$
function does not invoke the$va_end()$macro.



vsnprintf() Function                                           *crv-vsnprintf*
--------------------
Synopsis~
 $#include <stdarg.h>$
 $#include <stdio.h>$
 $int vsnprintf(char *s, size_t size, const char *format, va_list ap);$

Return~
<0: error occurred
The return value is the number of characters which would be generated for the
given input, excluding the trailing null. If this value is greater or equal
to$size$, not all characters from the result have been stored in$s$.

Description~
This function is similar to$snprintf()$except that, instead of taking a
variable number of arguments directly, it takes an argument list pointer$ap$,
which must have been initialized by the$va_start()$macro. The$vsnprintf()$
function does not invoke the$va_end()$macro.



scanf() Function                                                   *crv-scanf*
----------------
Synopsis~
 $#include <stdio.h>$
 $int scanf(const char *format, ...);$

Return~
The return value is the number of successful assignments. If there is a match
error, this number can be fewer than provided. If an input error occurs
before any matches are performed, then$EOF$is returned.

Description~
This function reads formatted input from the standard input stream$stdin$under
the control of the format string$format$. The optional arguments are pointers
to the places which receive the resulting values. 
For format string see |crv-libSIOHIOFin|.



fscanf() Function                                                 *crv-fscanf*
-----------------
Synopsis~
 $#include <stdio.h>$
 $int fscanf(FILE *stream, const char *format, ...);$

Return~

Description~
This function is equivalent to$scanf()$, except that the input is read from
the stream$stream$instead of$stdin$.



sscanf() Function                                                 *crv-sscanf*
-----------------
Synopsis~
 $#include <stdio.h>$
 $int sscanf(const char *s, const char *format, ...);$

Return~

Description~
This function is similar to$scanf()$, except that the characters are taken
from the null-terminated string$s$instead of from$stdin$. Reaching the end of
the string is treated as an end-of-file condition.


vscanf() Function                                                 *crv-vscanf*
-----------------
Synopsis~
 $#include <stdio.h>$
 $int vscanf(const char *format, va_list ap);$

Return~

Description~
This function is similar to$scanf()$except that, instead of taking a
variable number of arguments directly, it takes an argument list pointer$ap$,
which must have been initialized by the$va_start()$macro. The$vscanf()$
function does not invoke the$va_end()$macro.



vfscanf() Function                                               *crv-vfscanf*
------------------
Synopsis~
 $#include <stdio.h>$
 $int vfscanf(FILE *stream, const char *format, va_list ap);$

Return~

Description~
This function is similar to$fscanf()$except that, instead of taking a
variable number of arguments directly, it takes an argument list pointer$ap$,
which must have been initialized by the$va_start()$macro. The$vfscanf()$
function does not invoke the$va_end()$macro.



vsscanf() Function                                               *crv-vsscanf*
------------------
Synopsis~
 $#include <stdio.h>$
 $int vsscanf(const char *s, const char *format, va_list ap);$

Return~

Description~
This function is similar to$sscanf()$except that, instead of taking a
variable number of arguments directly, it takes an argument list pointer$ap$,
which must have been initialized by the$va_start()$macro. The$vsscanf()$
function does not invoke the$va_end()$macro.





------------------------------------------------------------------------------
II.19.7  Character Input/Output                               *crv-libSIOHCIO*

This section describes functions for performing character-oriented input and
output.

Quicklink:
    $fgetc()$   Func   |crv-fgetc|
    $fgets()$   Func   |crv-fgets|
    $fputc()$   Func   |crv-fputc|
    $fputs()$   Func   |crv-fputs|
    $getc()$    Macro  |crv-getc|
    $getchar()$ Func   |crv-getchar|
    $gets()$    Func   |crv-gets|
    $putc()$    Macro  |crv-putc|
    $putchar()$ Func   |crv-putchar|
    $puts()$    Func   |crv-puts|
    $ungetc()$  Func   |crv-ungetc|



fgetc() Function                                                   *crv-fgetc*
----------------
Synopsis~
 $#include <stdio.h>$
 $int fgetc(FILE *stream);$

Return~
character read from stream
error or end-of-file:$EOF$

Description~
This function reads the next character as an$unsigned char$from the stream
$stream$and returns its value, converted to an$int$. If an end-of-file
condition or read error occurs,$EOF$is returned instead.



fgets() Function                                                   *crv-fgets*
----------------
Synopsis~
 $#include <stdio.h>$
 $char *fgets(char *s, int count, FILE *stream);$

Return~
If the system is already at end of file when fgets() is called, then the
contents of the array$s$are unchanged and a null pointer is returned.
A null pointer is also returned if a read error occurs. Otherwise, the
return value is the pointer$s$.

Description~
This function reads characters from the stream$stream$up to and including a
newline character and stores them in the string$s$, adding a null character
to mark the end of the string.$count$characters must be supplied worth of
space in$s$, but the number of characters read is at most$count$- 1.
The extra character space is used to hold the null character at the end of
the string. 



getc() Macro                                                        *crv-getc*
------------
Synopsis~
 $#include <stdio.h>$
 $int getc(FILE *stream);$

Return~
character read from stream
error or end-of-file:$EOF$

Description~
This is just like$fgetc()$, except that it is permissible (and typical) for
it to be implemented as a macro that evaluates the stream argument more
than once.$getc()$is often highly optimized, so it is usually the best
function to use to read a single character.



getchar() Function                                               *crv-getchar*
------------------
Synopsis~
 $#include <stdio.h>$
 $int getchar(void);$

Return~
character read from stream
error or end-of-file:$EOF$

Description~
This function is equivalent to$getc()$with$stdin$as the value of the stream
argument.



gets() Function                                                     *crv-gets*
---------------
Synopsis~
 $#include <stdio.h>$
 $char *gets(char *s);$

Return~
If$gets()$encounters a read error or end-of-file, it returns a null pointer;
otherwise it returns$s$.

Description~
This function reads characters from the stream$stdin$up to the next newline
character, and stores them in the string$s$. The newline character is
discarded (note that this differs from the behavior of$fgets()$, which copies
the newline character into the string). 


 
ungetc() Function                                                 *crv-ungetc*
-----------------
Synopsis~
 $#include <stdio.h>$
 $int ungetc(int c, FILE *stream);$

Return~
$c$pushed back after conversion or$EOF$if the operation fails

Description~
This function pushes back the character$c$onto the input stream$stream$. So
the next input from$stream$will read$c$before anything else. 

If$c$is$EOF$,$ungetc()$does nothing and just returns$EOF$. This allows to
call$ungetc()$with the return value of$getc()$without needing to check for an
error from$getc()$. 

The character that is pushed back doesn't have to be the same as the last
character that was actually read from the stream. In fact, it isn't necessary
to actually read any characters from the stream before unreading them with
$ungetc()$. But that is a strange way to write a program; usually$ungetc()$
is used only to unread a character that was just read from the same stream.

Pushing back characters doesn't alter the file; only the internal buffering
for the stream is affected. If a file positioning function (such as$fseek()$,
$fseeko()$ or$rewind()$) is called, any pending pushed-back characters are
discarded. 

Unreading a character on a stream that is at end of file clears the
end-of-file indicator for the stream, because it makes the character of
input available. After reading that character, trying to read again will
encounter end of file.



fputc() Function                                                   *crv-fputc*
----------------
Synopsis~
 $#include <stdio.h>$
 $int fputc(int c, FILE *stream);$

Return~
$EOF$is returned if a write error occurs; otherwise the character$c$is
returned

Description~
This function converts the character$c$to type$unsigned char$, and writes it
to the stream$stream$.



fputs() Function                                                   *crv-fputs*
----------------
Synopsis~
 $#include <stdio.h>$
 $int fputs(const char *s, FILE *stream);$

Return~
This function returns$EOF$if a write error occurs, and otherwise a
non-negative value. 

Description~
This function writes the string$s$to the stream$stream$. The terminating
null character is not written. This function does not add a newline character,
either. It outputs only the characters in the string.



putc() Macro                                                        *crv-putc*
------------
Synopsis~
 $#include <stdio.h>$
 $int putc(int c, FILE *stream);$

Return~
This function returns$EOF$if a write error occurs, and otherwise the
character written. 

Description~
This is just like$fputc()$, except that most systems implement it as a
macro, making it faster. One consequence is that it may evaluate the stream
argument more than once, which is an exception to the general rule for
macros.$putc()$is usually the best function to use for writing a single
character.



putchar() Function                                               *crv-putchar*
------------------
Synopsis~
 $#include <stdio.h>$
 $int putchar(int c);$

Return~
This function returns$EOF$if a write error occurs, and otherwise the
character written. 

Description~
This function is equivalent to$putc()$with$stdout$as the value of the stream
argument.



puts() Function                                                     *crv-puts*
---------------
Synopsis~
 $#include <stdio.h>$
 $int puts(const char *s);$

Return~
This function returns$EOF$if a write error occurs, and otherwise a
non-negative value. 

Description~
This function writes the string$s$to the stream$stdout$followed by a newline.
The terminating null character of the string is not written. (Note that
$fputs()$does not write a newline as this function does.)

$puts()$is the most convenient function for printing simple messages.



------------------------------------------------------------------------------
II.19.8  Direct Input/Output                                  *crv-libSIOHDIO*

This section describes how to do input and output operations on blocks of
data. This functions can be used to read and write binary data, as well as to
read and write text in fixed-size blocks instead of by characters or lines.

Binary files are typically used to read and write blocks of data in the same
format as is used to represent the data in a running program. In other words,
arbitrary blocks of memory--not just character or string objects--can be
written to a binary file, and meaningfully read in again by the same program.

Storing data in binary form is often considerably more efficient than using
the formatted I/O functions. Also, for floating-point numbers, the binary form
avoids possible loss of precision in the conversion process. On the other
hand, binary files can't be examined or modified easily using many standard
file utilities (such as text editors), and are not portable between
different implementations of the language, or different kinds of computers.


fread() Function                                                   *crv-fread*
----------------
Synopsis~
 $#include <stdio.h>$
 $size_t fread(void *data, size_t size, size_t count, FILE *stream);$

Return~
It returns the number of objects actually read, which might be less than
$count$if a read error occurs or the end of the file is reached. This
function returns a value of zero (and doesn't read anything) if
either$size$or$count$is zero. 
If$fread()$encounters end of file in the middle of an object, it returns
the number of complete objects read, and discards the partial object.
Therefore, the stream remains at the actual end of the file.

Description~
This function reads up to$count$objects of size$size$into the array$data$,
from the stream$stream$. 


fwrite() Function                                                 *crv-fwrite*
-----------------
Synopsis~
 $#include <stdio.h>$
 $size_t fwrite(const void *data, size_t size, size_t count, FILE *stream);$

Return~
The return value is normally$count$, if the call succeeds.
Any other value indicates some sort of error, such as running out of space.

Description~
This function writes up to count objects of size$size$from the array$data$,
to the stream$stream$.
   



------------------------------------------------------------------------------
II.19.9  File Positioning                                    *crv-libSIOHFPos*

The file position of a stream describes where in the file the stream is
currently reading or writing. I/O on the stream advances the file position
through the file.

Quicklink:
    $fgetpos()$ Func  |crv-fgetpos|
    $fseek()$   Func  |crv-fseek|
    $fsetpos()$ Func  |crv-fsetpos|
    $ftell()$   Func  |crv-ftell|
    $rewind()$  Func  |crv-rewind|



fgetpos() Function                                               *crv-fgetpos*
------------------
Synopsis~
 $#include <stdio.h>$
 $int fgetpos(FILE *stream, fpos_t *position);$

Return~
If successful,$fgetpos()$ returns zero; otherwise it returns a nonzero value
and stores an implementation-defined positive value in$errno$.

Description~
This function stores the value of the file position indicator for the stream
$stream$in the$fpos_t$object pointed to by$position$. 



fseek() Function                                                   *crv-fseek*
----------------
Synopsis~
 $#include <stdio.h>$
 $int fseek(FILE *stream, long int offset, int whence);$

Return~
0 if successful,
else failed

Description~
This function is used to change the file position of the stream$stream$. The
value of$whence$must be one of the constants$SEEK_SET$,$SEEK_CUR$, or
$SEEK_END$, to indicate whether the offset is relative to the beginning of the
file, the current file position, or the end of the file, respectively.



fsetpos() Function                                               *crv-fsetpos*
------------------
Synopsis~
 $#include <stdio.h>$
 $int fsetpos(FILE *stream, const fpos_t *position);$

Return~
If successful,$fsetpos()$clears the end-of-file indicator on the stream,
discards any characters that were "pushed back" by the use of$ungetc()$, and
returns a value of zero.
Otherwise, it returns a nonzero value and stores an implementation-defined
positive value in$errno$.

Description~
This function sets the file position indicator for the stream$stream$to the
position$position$, which must have been set by a previous call to$fgetpos()$
on the same stream. 



ftell() Function                                                   *crv-ftell*
----------------
Synopsis~
 $#include <stdio.h>$
 $long int ftell(FILE *stream);$

Return~
This function can fail if the stream doesn't support file positioning, or if
the file position can't be represented in a$long int$, and possibly for other
reasons as well. If a failure occurs, a value of -1L is returned and an
implementation-defined positive value is stored in$errno$.

Description~
This function returns the current file position of the stream$stream$.



rewind() Function                                                 *crv-rewind*
-----------------
Synopsis~
 $#include <stdio.h>$
 $void rewind(FILE *stream);$

Return~
none

Description~
This function positions the stream$stream$at the beginning of the file. It is
equivalent to calling$fseek()$on the stream with an offset argument of 0L and a
whence argument of$SEEK_SET$, except that the return value is discarded and the
error indicator for the stream is reset.




------------------------------------------------------------------------------
II.19.10 Error Handling                                       *crv-libSIOHErr*

Quicklink:
    $clearerr()$ Func  |crv-libclearerr|
    $feof()$     Func  |crv-libfeof|
    $ferror()$   Func  |crv-libferror|
    $perror()$   Func  |crv-libperror|



clearerr() Function                                             *crv-clearerr*
-------------------
Synopsis~
 $#include <stdio.h>$
 $void clearerr(FILE *stream);$

Return~
none

Description~
This function clears the end-of-file and error indicators for the stream
$stream$.
The file positioning functions also clear the end-of-file indicator for the
stream.



feof() Function                                                     *crv-feof*
---------------
Synopsis~
 $#include <stdio.h>$
 $int feof(FILE *stream);$

Return~
0: no EOF
else: EOF

Description~
This function returns nonzero if and only if the end-of-file indicator for the
stream$stream$ is set.



ferror() Function                                                 *crv-ferror*
-----------------
Synopsis~
 $#include <stdio.h>$
 $int ferror(FILE *stream);$

Return~
0: no error
else: error indicator is set

Description~
This function returns nonzero if and only if the error indicator for the
stream $stream$is set, indicating that an error has occurred on a previous
operation on the stream.



perror() Function                                                 *crv-perror*
-----------------
Synopsis~
 $#include <stdio.h>$
 $void perror(const char *msg);$

Return~
none

Description~
This function prints an error message to the stream$stderr$. The orientation
of$stderr$is not changed. 

If$perror()$is called with a message that is either a null pointer or an empty
string,$perror()$just prints the error message corresponding to$errno$, adding
a trailing newline.

If it's called with a non-null message argument, then$perror()$prefixes its
output with this string. It adds a colon and a space character to separate the
message from the error string corresponding to$errno$.




==============================================================================
II.20  <stdlib.h> Utilities                                   *crv-libStdlibH*

This header file declares types, macros and functions of general utility.



------------------------------------------------------------------------------
II.20.1  Types                                                *crv-libSLHType*

Quicklink:
    $dif_t$    Type   |crv-libdif_t|
    $ldif_t$   Type   |crv-libldif_t|
    $lldif_t$  Type   |crv-liblldif_t|
    $size_t$   Type   |crv-libsize_t2|
    $wchar_t$  Type   |crv-libwchar_t2|



dif_t Type                                                         *crv-dif_t*
----------
This is a structure type used to hold the result returned by the$div()$
function. It has the following members:
  $int quot$: The quotient from the division. 
  $int rem$ : The remainder from the division.


ldif_t Type                                                       *crv-ldif_t*
-----------
This is a structure type used to hold the result returned by the$ldiv()$
function. It has the following members:
  $long int quot$: The quotient from the division. 
  $long int rem$ : The remainder from the division.


lldif_t Type                                                     *crv-lldif_t*
------------
This is a structure type used to hold the result returned by the$ldiv()$
function. It has the following members:
  $long long int quot$: The quotient from the division. 
  $long long int rem$ : The remainder from the division.


size_t Type                                                      *crv-size_t2*
-----------
This is an unsigned integer type used to represent the sizes of objects.
Also declared in$<stddef.h>$, see |crv-libsize_t|.
Also declared in$<string.h>$, see |crv-libsize_t3|.
Also declared in$<time.h>$,   see |crv-libsize_t4|.
Also declared in$<stdio.h>$,  see |crv-libsize_t5|.
Also declared in$<wchar.h>$,  see |crv-libsize_t6|.


wchar_t Type                                                    *crv-wchar_t2*
------------
This data type is used as the base type for wide character strings.
It's range of values can represent distinct codes for all members of the
largest extended character set specified among the supported locales.
Also declared in$<stddef.h>$, see |crv-libwchar_t|.
Also declared in$<wchar.h>$,  see |crv-libwchar_t3|.




------------------------------------------------------------------------------
II.20.2  Macros                                                *crv-libSLHMac*

Quicklink:
    $EXIT_SUCCESS$ Macro  |crv-libEXIT_SUCCESS|
    $EXIT_FAILURE$ Macro  |crv-libEXIT_FAILURE|
    $MB_CUR_MAX$   Macro  |crv-libMB_CUR_MAX|
    $NULL$         Macro  |crv-libNULL2|
    $RAND_MAX$     Macro  |crv-libRAND_MAX|



RAND_MAX Macro                                                   *crv-RAND_MAX*
--------------
The value of this macro is an integer constant representing the largest value
the rand function can return. Its value is implementation-defined, but at
least 32767.



EXIT_SUCCESS Macro                                           *crv-EXIT_SUCCESS*
------------------
This macro can be used with the$exit()$function to indicate successful program
completion.



EXIT_FAILURE Macro                                           *crv-EXIT_FAILURE*
------------------
This macro can be used with the$exit()$function to indicate unsuccessful
program completion in a general sense.



NULL Macro                                                         *crv-NULL2*
----------
Expands to an implementation-defined null pointer constant.
Also defined in$<stddef.h>$, see |crv-NULL|.
Also defined in$<string.h>$, see |crv-NULL3|.
Also defined in$<time.h>$,   see |crv-NULL4|.
Also defined in$<stdio.h>$,  see |crv-NULL5|.
Also defined in$<wchar.h>$,  see |crv-NULL6|.



MB_CUR_MAX Macro                                              *crv-MB_CUR_MAX*
----------------
This macro expands into a positive integer expression that is the maximum
number of bytes in a multibyte character in the current locale. The value
is never greater than$MB_LEN_MAX$.




------------------------------------------------------------------------------
II.20.3  Numeric Conversion                                    *crv-libSLHnum*

Quicklink:
    $atof()$    Func  |crv-atof|
    $atoi()$    Func  |crv-atoi|
    $atol()$    Func  |crv-atol|
    $atoll()$   Func  |crv-atoll|
    $strtod()$  Func  |crv-strtod|
    $strtof()$  Func  |crv-strtof|
    $strtol()$  Func  |crv-strtol|
    $strtold()$ Func  |crv-strtold|
    $strtoll()$ Func  |crv-strtoll|
    $stroul()$  Func  |crv-stroul|
    $strtoull()$Func  |crv-strtoull|



atof() Function                                                     *crv-atof*
---------------
Synopsis~
 $#include <stdlib.h>$
 $double atof(const char *string);$

Return~
result of conversion

Description~
This function converts the initial portion of the string$string$to a$double$
representation. This function is similar to the$strtod()$function, except that
it need not detect overflow and underflow errors. 
The atof function is provided mostly for compatibility with existing code;
using$strtod()$is more robust.



atol() Function                                                     *crv-atol*
---------------
Synopsis~
 $#include <stdlib.h>$
 $long int atol(const char *string);$

Return~
result of conversion

Description~
This function converts the string$string$to an$long int$value.
This function is similar to the$strtol()$function with a base argument of 10,
except that it need not detect overflow errors. The$atol()$function is
provided mostly for compatibility with existing code; using$strtol()$is more
robust. 



atoi() Function                                                     *crv-atoi*
---------------
Synopsis~
 $#include <stdlib.h>$
 $int atoi(const char *string);$

Return~
result of conversion

Description~
This function converts the string$string$to an$int$value.
The$atoi()$function is considered obsolete; use$strtol()$instead. 



atoll() Function                                                   *crv-atoll*
----------------
Synopsis~
 $#include <stdlib.h>$
 $long long int atoll(const char *string);$

Return~
result of conversion

Description~
This function converts the string$string$to an$long long int$value.
The$atoll()$function was introduced in ISO C99. It is obsolete (despite having
just been added); use$strtoll()$instead. 




strtol() Function                                                 *crv-strtol*
-----------------
Synopsis~
 $#include <stdlib.h>$
 $long int strtol(const char *restrict string, char **restrict tailptr,$
                 $int base);$

Return~
no error:       value of conversion
no conversion:  0 is returned
out of range:   result is$LONG_MAX$or$LONG_MIN$(according to sign),
              $ errno$is set to$ERANGE$

Description~
The$strtol()$("string-to-long") function converts the initial part of string to
a signed integer, which is returned as a value of type$long int$.

This function attempts to decompose$string$as follows:

  - A (possibly empty) sequence of whitespace characters. Which characters are
    whitespace is determined by the$isspace()$function. These are discarded.
  - An optional plus or minus sign (+ or -).
  - A nonempty sequence of digits in the radix specified by$base$.
    If$base$is zero, decimal radix is assumed unless the series of digits
    begins with 0 (specifying octal radix), or 0x or 0X (specifying
    hexadecimal radix); in other words, the same syntax used for integer
    constants in C.
    Otherwise$base$must have a value between 2 and 36. If$base$is 16, the
    digits may optionally be preceded by 0x or 0X. If$base$has no legal value
    the value returned is 0l and the global variable$errno$is set to$EINVAL$.
  - Any remaining characters in the string. If$tailptr$is not a null pointer,
   $strtol()$stores a pointer to this tail in$*tailptr$.

If the string is empty, contains only whitespace, or does not contain an
initial substring that has the expected syntax for an integer in the specified
$base$, no conversion is performed. In this case,$strtol()$returns a value of
zero and the value stored in$*tailptr$is the value of$string$. 

In a locale other than the standard "C" locale, this function may recognize
additional implementation-dependent syntax.

Checking for errors by examining the return value of$strtol()$should not be
done, because the string might be a valid representation of 0l,$LONG_MAX$,
or$LONG_MIN$. Instead, check whether$tailptr$points to what is expected after
the number (e.g. '\0' if the string should end after the number). $errno$needs
also to be cleared before the call and checked afterwards, in case there was
overflow.



strtoll() Function                                               *crv-strtoll*
------------------
Synopsis~
 $#include <stdlib.h>$
 $long long int strtoll(const char *restrict string, char **restrict tailptr,$
                       $int base);$

Return~
no error:       value of conversion
no conversion:  0 is returned
out of range:   result is$LONG_LONG_MAX$or$LONG_LONG_MIN$(according to sign),
               $errno$is set to$ERANGE$

Description~
This function is like$strtol()$except that it returns a$long long int$value,
and accepts numbers with a correspondingly larger range.



stroul() Function                                                 *crv-stroul*
-----------------
Synopsis~
 $#include <stdlib.h>$
 $unsigned long int strtoul(const char *retrict string,$
                           $char **restrict tailptr, int base);$

Return~
no error:       value of conversion
no conversion:  0 is returned
out of range:   result is$ULONG_MAX$,$errno$is set to$ERANGE$

Description~
The$strtoul()$("string-to-unsigned-long") function is like$strtol()$except it
converts to an$unsigned long int$value. The syntax is the same as described
for$strtol$.



strtoull() Function                                             *crv-strtoull*
-------------------
Synopsis~
 $#include <stdlib.h>$
 $unsigned long long int strtoull(const char *restrict string,$
                                 $char **restrict tailptr, int base);$

Return~
no error:      value of conversion
no conversion: 0 is returned
out of range:  result is$ULONG_LONG_MAX$,$errno$is set to$ERANGE$

Description~
This function is like$strtol()$except that it returns an
$unsigned long long int$value, and accepts numbers with a correspondingly
larger range.




strtod() Function                                                 *crv-strtod*
-----------------
Synopsis~
 $#include <stdlib.h>$
 $double strtod(const char *restrict string, char **restrict tailptr);$

Return~
no error:       value of conversion
no conversion:  0 is returned
out of range:   result is $-HUGE_VAL$or$+HUGH_VAL$(according to sign),
               $errno$is set to$ERANGE$

Description~
The$strtod()$("string-to-double") function converts the initial part of string
to a floating-point number, which is returned as a value of type$double$.

This function attempts to decompose$string$as follows:

  - A (possibly empty) sequence of whitespace characters. Which characters are
    whitespace is determined by the$isspace()$function. These are discarded.
  - An optional plus or minus sign (+ or -).
  - A floating point number in decimal or hexadecimal format. The decimal
    format is:
      o A nonempty sequence of digits optionally containing a decimal-point
        character - normally, but it depends on the locale. 
      o An optional exponent part, consisting of a character e or E, an
        optional sign, and a sequence of digits.

    The hexadecimal format is as follows:
      o A 0x or 0X followed by a nonempty sequence of hexadecimal digits
        optionally containing a decimal-point character - normally, but it
        depends on the locale.
      o An optional binary-exponent part, consisting of a character p or P,
        an optional sign, and a sequence of digits.
        
  - Any remaining characters in the string. If$tailptr$is not a null pointer,
    a pointer to this tail of the string is stored in$*tailptr$.

If the string is empty, contains only whitespace, or does not contain an
initial substring that has the expected syntax for a floating-point number, no
conversion is performed. In this case,$strtod()$returns a value of zero
and the value returned in$*tailptr$is the value of$string$.

In a locale other than the standard "C", this function may recognize
additional locale-dependent syntax.

If the string has valid syntax for a floating-point number but the value
is outside the range of a$double$,$strtod()$will signal overflow or
underflow as described in II.12.1 Error Conditions (|crv-libMHErr|).

$strtod()$recognizes four special input strings. The strings "inf"
and "infinity" are converted to &infin;, or to the largest representable
value if the floating-point format doesn't support infinities. You can
prepend a "+" or "-" to specify the sign. Case is ignored when scanning
these strings. 

The strings "nan" and "nan(chars...)" are converted to NaN. Again, case is
ignored. If chars... are provided, they are used in some unspecified fashion
to select a particular representation of NaN (there can be several).

Since zero is a valid result as well as the value returned on error, you
should check for errors in the same way as for$strtol()$, by examining
$errno$and$tailptr$.



strtof() Function                                                 *crv-strtof*
-----------------
Synopsis~
 $#include <stdlib.h>$
 $float strtof(const char *string, char **tailptr);$

Return~
no error:       value of conversion
no conversion:  0 is returned
out of range:   result is $-HUGE_VALF$or$+HUGH_VALF$(according to sign),
               $errno$is set to$ERANGE$

Description~
This function is analogous to$strtod()$, but return$float$values respectively;
it reports errors in the same way.



strtold() Function                                               *crv-strtold*
------------------
Synopsis~
 $#include <stdlib.h>$
 $long double strtold(const char *string, char **tailptr);$

Return~
no error:       value of conversion
no conversion:  0 is returned
out of range:   result is $-HUGE_VALL$or$+HUGH_VALL$(according to sign),
               $errno$is set to$ERANGE$

Description~
This function is analogous to$strtod()$, but return$long double$values
respectively; it reports errors in the same way.




------------------------------------------------------------------------------
II.20.4  Pseudo-Random                                        *crv-libSLHrand*

This section describes the random number functions.

Quicklink:
    $rand()$   Func   |crv-rand|
    $srand()$  Func   |crv-srand|



rand() Function                                                     *crv-rand*
---------------
Synopsis~
 $#include <stdlib.h>$
 $int rand(void);$

Return~
pseudo-random number

Description~
This function returns the next pseudo-random number in the series. The value
ranges from 0 to$RAND_MAX$.



srand() Function                                                   *crv-srand*
----------------
Synopsis~
 $#include <stdlib.h>$
 $void srand(unsigned int seed);$

Return~
none

Description~
This function establishes$seed$as the seed for a new series of pseudo-random
numbers. 
If$rand()$is called before a seed has been established with$srand()$, it uses
the value 1 as a default seed. 

To produce a different pseudo-random series each time program starts, do
$srand (time (0))$.




------------------------------------------------------------------------------
II.20.5  Memory Management                                     *crv-libSLHmem*

Quicklink:
    $calloc()$ Func  |crv-calloc|
    $free()$   Func  |crv-free|
    $malloc()$ Func  |crv-malloc|
    $realloc()$Func  |crv-realloc|


calloc() Function                                                 *crv-calloc*
-----------------
Synopsis~
 $#include <stdlib.h>$
 $void *calloc(size_t count, size_t eltsize);$

Return~
pointer to allocated space or null pointer, if failed

Description~
This function allocates a block long enough to contain a vector of$count$
elements, each of size$eltsize$. Its contents are cleared to zero before
$calloc()$returns.



free() Function                                                     *crv-free*
----------------
Synopsis~
 $#include <stdlib.h>$
 $void free(void *ptr);$

Return~
none

Description~
This function deallocates the block of memory pointed at by$ptr$that was
allocated by$calloc()$,$malloc()$or$realloc()$.
It is allowed for$ptr$to be a null pointer.



malloc() Function                                                 *crv-malloc*
-----------------
Synopsis~
 $#include <stdlib.h>$
 $void *malloc(size_t size);$

Return~
pointer to allocated space or null pointer, if failed

Description~
This function returns a pointer to a newly allocated block$size$bytes long.
The contents of the block is undefined.



realloc() Function                                               *crv-realloc*
------------------
Synopsis~
 $#include <stdlib.h>$
 $void *realloc(void *ptr, size_t newsize);$

Return~
pointer to new block or null pointer, if failed

Description~
This function changes the size of the block whose address is$ptr$to be
$newsize$.
Since the space after the end of the block may be in use,$realloc()$may find
it necessary to copy the block to a new address where more free space is
available. If the block needs to be moved,$realloc()$copies the old contents.

If a null pointer is passed for$ptr$,$realloc()$behaves just like
$malloc(newsize)$.
If memory for the new block cannot be allocated the old block is not
deallocated and its value is unchanged.




------------------------------------------------------------------------------
II.20.6  Communication                                         *crv-libSLHcom*

Quicklink:
    $_Exit()$  Func  |crv-_Exit|
    $abort()$  Func  |crv-abort|
    $atexit()$ Func  |crv-atexit|
    $exit()$   Func  |crv-exit|
    $getenv()$ Func  |crv-getenv|
    $system()$ Func  |crv-system|



abort() Function                                                   *crv-abort*
----------------
Synopsis~
 $#include <stdlib.h>$
 $void abort(void);$

Return~
this function does not return to its caller

Description~
This function causes abnormal program termination. This does not execute
cleanup functions registered with$atexit()$. This function actually terminates
the process by raising a SIGABRT signal.



atexit() Function                                                 *crv-atexit*
-----------------
Synopsis~
 $#include <stdlib.h>$
 $int atexit(void (*function) (void));$

Return~
0:    successful
else: failed to register function

Description~
This function registers the function$function$to be called at normal program
termination. The$function$is called with no arguments.



exit() Function                                                     *crv-exit*
---------------
Synopsis~
 $#include <stdlib.h>$
 $void exit(int status);$

Return~
this function does not return to its caller

Description~
This function tells the system that the program is done, which causes it to
terminate the process. The value of$status$is returned to the environment.

Normal termination causes the following actions:
  - Functions that were registered with the$atexit()$function are called in
    the reverse order of their registration. This mechanism allows the
    application to specify its own "cleanup" actions to be performed at
    program termination.
  - All open streams are closed, writing out any buffered output data. 
    In addition, temporary files opened with the$tmpfile()$function are
    removed. 
  - Control is returned to the host environment. If$status$is zero or
   $EXIT_SUCCESS$, then this signifies a successful termination. If$status$
    is$EXIT_FAILURE$, then this signifies an unsuccessful termination.
    Other values are implementation-defined.



_Exit() Function                                                   *crv-_Exit*
----------------
Synopsis~
 $#include <stdlib.h>$
 $void _Exit(int status);$

Return~
this function does not return to its caller

Description~
This function is the primitive for causing a process to terminate with status
$status$. Calling this function does not execute cleanup functions registered
with$atexit()$.

Termination causes the following actions:
  - All open streams are closed, writing out any buffered output data. 
    In addition, temporary files opened with the$tmpfile()$function are
    removed. 
  - Control is returned to the host environment. If$status$is zero or
   $EXIT_SUCCESS$, then this signifies a successful termination. If$status$
    is$EXIT_FAILURE$, then this signifies an unsuccessful termination.
    Other values are implementation-defined.



getenv() Function                                                 *crv-getenv*
------------------
Synopsis~
 $#include <stdlib.h>$
 $char * getenv(const char *name);$

Return~
null pointer: environment variable not found
else:         pointer to string representing the value of the environment
              variable
Description~
This function returns a string that is the value of the environment variable
$name$. This string must not be modified. 



system() Function                                                 *crv-system*
-----------------
Synopsis~
 $#include <stdlib.h>$
 $int system(const char *command);$

Return~
If the$command$argument is a null pointer, a return value of zero indicates
that no command processor is available. 
If the$command$argument is not a null pointer and the$system()$function does
return, it returns an implementation-defined value.

Description~
This function executes$command$as a shell command (shell = command processor).
If$command$is a null pointer, the$system()$function determines whether the
host environment has a command processor.




------------------------------------------------------------------------------
II.20.7  Searching and Sorting                              *crv-libSLHsearch*

Quicklink:
    $bsearch()$ Func  |crv-bsearch|
    $qsort()$   Func  |crv-qsort|


bsearch() Function                                               *crv-bsearch*
------------------
Synopsis~
 $#include <stdlib.h>$
 $void *bsearch(const void *key, const void *array, size_t count,$
               $size_t size, int (* compare)(const void *, const void *));$

Return~
The return value is a pointer to the matching array element, or a null pointer
if no match is found. If the array contains more than one element that
matches, the one that is returned is unspecified.

Description~
This function ("binary-search") searches the sorted array$array$for an object
that is equivalent to$key$. The array contains$count$elements, each of which
is of size$size$bytes.

The$compare$function is used to perform the comparison. This function is
called with two pointer arguments and should return an integer less than,
equal to, or greater than zero corresponding to whether its first argument
is considered less than, equal to, or greater than its second argument. The
elements of the$array$must already be sorted in ascending order according to
this comparison function.



qsort() Function                                                   *crv-qsort*
----------------
Synopsis~
 $#include <stdlib.h>$
 $void qsort(void *array, size_t count, size_t size,$
            $int (* compare)(const void *, const void *));$

Return~
none

Description~
This function sorts the array$array$. The array contains$count$elements, each
of which is of size$size$. 

The$compare$function is used to perform the comparison on the array elements.
This function is called with two pointer arguments and should return an
integer less than, equal to, or greater than zero corresponding to whether its
first argument is considered less than, equal to, or greater than its second
argument.

If two objects compare as equal, their order after sorting is unpredictable.
That is to say, the sorting is not stable. This can make a difference when
the comparison considers only part of the elements. Two elements with the
same sort key may differ in other respects.




------------------------------------------------------------------------------
II.20.8  Integer Arithmetic                               *crv-libSLHintarith*

Quicklink:
    $abs()$   Func  |crv-abs|
    $labs()$  Func  |crv-labs|
    $llabs()$ Func  |crv-llabs|
    $div()$   Func  |crv-div|
    $ldiv()$  Func  |crv-ldiv|
    $lldiv()$ Func  |crv-lldiv|



abs() Function                                                       *crv-abs*
--------------
Synopsis~
 $#include <stdlib.h>$
 $int abs(int number);$

Return~
absolute value

Description~
Evaluates the absolute value of$number$.



labs() Function                                                     *crv-labs*
---------------
Synopsis~
 $#include <stdlib.h>$
 $long int labs(long int number);$

Return~
absolute value

Description~
Evaluates the absolute value of$number$.



llabs() Function                                                   *crv-llabs*
----------------
Synopsis~
 $#include <stdlib.h>$
 $long long int labs(long long int number);$

Return~
absolute value

Description~
Evaluates the absolute value of$number$.



div() Function                                                       *crv-div*
--------------
Synopsis~
 $#include <stdlib.h>$
 $div_t div(int numerator, int denominator);$

Return~
return the result in a structure of type$div_t$
If the result cannot be represented (as in a division by zero), the
behavior is undefined.

Description~
This function computes the quotient and remainder from the division of
$numerator$by$denominator$.



ldiv() Function                                                     *crv-ldiv*
---------------
Synopsis~
 $#include <stdlib.h>$
 $ldiv_t ldiv(long int numerator, long int denominator);$

Return~
return the result in a structure of type$ldiv_t$
If the result cannot be represented (as in a division by zero), the
behavior is undefined.

Description~
This function computes the quotient and remainder from the division of
$numerator$by$denominator$.



lldiv() Function                                                   *crv-lldiv*
----------------
Synopsis~
 $#include <stdlib.h>$
 $lldiv_t lldiv(long long int numerator, long long int denominator);$

Return~
return the result in a structure of type$lldiv_t$
If the result cannot be represented (as in a division by zero), the
behavior is undefined.

Description~
This function computes the quotient and remainder from the division of
$numerator$by$denominator$.




------------------------------------------------------------------------------
II.20.9  Multibyte/Wide Character                          *crv-libSLHmulchar*

Quicklink:
    $mblen()$  Func  |crv-mblen|
    $mbtowc()$ Func  |crv-mbtowc|
    $wctomb()$ Func  |crv-wctomb|



mblen() Function                                                   *crv-mblen*
----------------
Synopsis~
 $#include <stdlib.h>$
 $int mblen(const char *string, size_t size);$

Return~
see description

Description~
The$mblen()$function with a non-null string argument returns the number of
bytes that make up the multibyte character beginning at$string$, never
examining more than$size$bytes. 

The return value of$mblen()$distinguishes three possibilities: the first$size$
bytes at$string$start with valid multibyte characters, they start with an
invalid byte sequence or just part of a character, or$string$points to an
empty string (a null character).

For a valid multibyte character,$mblen()$returns the number of bytes in that
character (always at least 1 and never more than$size$). For an invalid byte
sequence,$mblen()$returns -1. For an empty string, it returns 0.

If the multibyte character code uses shift characters, then$mblen()$maintains
and updates a shift state as it scans. If$mblen()$is called with a null
pointer for$string$, that initializes the shift state to its standard initial
value. It also returns a nonzero value if the multibyte character code in use
actually has a shift state.



mbtowc() Function                                                 *crv-mbtowc*
-----------------
Synopsis~
 $#include <stdlib.h>$
 $int mbtowc(wchar_t *restrict result, const char *restrict string,$
            $size_t size);$

Return~
see description

Description~
The$mbtowc()$("multibyte to wide character") function when called with
non-null$string$converts the first multibyte character beginning at$string$to
its corresponding wide character code. It stores the result in$*result$.
$mbtowc()$never examines more than$size$bytes. 

$mbtowc()$with non-null$string$distinguishes three possibilities: the first
size bytes at$string$start with valid multibyte characters, they start with
an invalid byte sequence or just part of a character, or string points to an
empty string (a null character).

For a valid multibyte character,$mbtowc()$converts it to a wide character and
stores that in$*result$, and returns the number of bytes in that character
(always at least 1 and never more than$size$).

For an invalid byte sequence,$mbtowc()$returns -1. For an empty string, it
returns 0, also storing '\0' in$*result$.

If the multibyte character code uses shift characters, then$mbtowc()$
maintains and updates a shift state as it scans. If$mbtowc()$is called with a
null pointer for$string$, that initializes the shift state to its standard
initial value. It also returns nonzero if the multibyte character code in use
actually has a shift state.



wctomb() Function                                                 *crv-wctomb*
-----------------
Synopsis~
 $#include <stdlib.h>$
 $int wctomb(char *string, wchar_t wchar);$

Return~
see description

Description~
The$wctomb()$("wide character to multibyte") function converts the wide
character code$wchar$to its corresponding multibyte character sequence, and
stores the result in bytes starting at$string$. At most$MB_CUR_MAX$characters
are stored.

$wctomb()$with non-null string distinguishes three possibilities for$wchar$: a
valid wide character code (one that can be translated to a multibyte
character), an invalid code, and L'\0'.

Given a valid code,$wctomb()$converts it to a multibyte character, storing the
bytes starting at$string$. Then it returns the number of bytes in that
character (always at least 1 and never more than$MB_CUR_MAX$).

If$wchar$is an invalid wide character code,$wctomb()$returns -1. If$wchar$is
L'\0', it returns 0, also storing '\0' in$*string$.

If the multibyte character code uses shift characters, then$wctomb()$maintains
and updates a shift state as it scans. If$wctomb()$is called with a null
pointer for$string$, that initializes the shift state to its standard initial
value. It also returns nonzero if the multibyte character code in use
actually has a shift state.




------------------------------------------------------------------------------
II.20.10  Multibyte/Wide String                           *crv-libSLHmulstrng*

Quicklink:
$mbstowcs()$ Func  |crv-mbstowcs|
$wcstombs()$ Func  |crv-wcstombs|



mbstowcs() Function                                             *crv-mbstowcs*
-------------------
Synopsis~
 $#include <stdlib.h>$
 $size_t mbstowcs(wchar_t *wstring, const char *string, size_t size);$

Return~
see description

Description~
The$mbstowcs()$("multibyte string to wide character string") function converts
the null-terminated string of multibyte characters$string$to an array of wide
character codes, storing not more than$size$wide characters into the array
beginning at$wstring$. The terminating null character counts towards the size,
so if$size$is less than the actual number of wide characters resulting from
$string$, no terminating null character is stored.

The conversion of characters from$string$begins in the initial shift state.

If an invalid multibyte character sequence is found, the$mbstowcs()$function
returns a value of -1. Otherwise, it returns the number of wide characters
stored in the array$wstring$. This number does not include the terminating
null character, which is present if the number is less than$size$.



wcstombs() Function                                             *crv-wcstombs*
-------------------
Synopsis~
 $#include <stdlib.h>$
 $size_t wcstombs(char *string, const wchar_t *wstring, size_t size);$

Return~
see description

Description~
The$wcstombs()$("wide character string to multibyte string") function converts
the null-terminated wide character array$wstring$into a string containing
multibyte characters, storing not more than$size$bytes starting at$string$,
followed by a terminating null character if there is room.

The conversion of characters begins in the initial shift state.

The terminating null character counts towards the size, so if$size$is less
than or equal to the number of bytes needed in$wstring$, no terminating null
character is stored.

If a code that does not correspond to a valid multibyte character is found,
the$wcstombs()$function returns a value of -1. Otherwise, the return value is
the number of bytes stored in the array$string$. This number does not include
the terminating null character, which is present if the number is less than
$size$.



==============================================================================
II.21  <string.h> String                                      *crv-libStringH*



------------------------------------------------------------------------------
II.21.1  Types                                                *crv-libSRHType*

size_t Type                                                      *crv-size_t3*
-----------
This is an unsigned integer type used to represent the sizes of objects.
Also declared in$<stddef.h>$, see |crv-size_t|.
Also declared in$<stdlib.h>$, see |crv-size_t2|.
Also declared in$<time.h>$,   see |crv-size_t4|.
Also declared in$<stdio.h>$,  see |crv-size_t5|.
Also declared in$<wchar.h>$,  see |crv-size_t6|.




------------------------------------------------------------------------------
II.21.2  Macros                                                *crv-libSRHMac*

NULL Macro                                                         *crv-NULL3*
----------
Expands to an implementation-defined null pointer constant.
Also defined in$<stddef.h>$, see |crv-NULL|.
Also defined in$<stdlib.h>$, see |crv-NULL2|.
Also defined in$<time.h>$,   see |crv-NULL4|.
Also defined in$<stdio.h>$,  see |crv-NULL5|.
Also defined in$<wchar.h>$,  see |crv-NULL6|.





------------------------------------------------------------------------------
II.21.3  Copying                                              *crv-libSRHCopy*

The functions described in this section can be used to copy the contents of
strings and arrays.

Quicklink:
    $memcpy()$  Func  |crv-memcpy|
    $memmove()$ Func  |crv-memmove|
    $strcpy()$  Func  |crv-strcpy|
    $strncpy()$ Func  |crv-strncpy|



memcpy() Function                                                 *crv-memcpy*
-----------------
Synopsis~
 $#include <string.h>$
 $void *memcpy(void *restrict to, const void *restrict from, size_t size);$

Return~
value of$to$

Description~
This function copies$size$bytes from the object beginning at$from$into the
object beginning at$to$. The behavior of this function is undefined if the two
arrays$to$and$from$overlap; $memmove()$can be used instead if overlapping is
possible.



memmove() Function                                               *crv-memmove*
------------------
Synopsis~
 $#include <string.h>$
 $void *memmove(void *to, const void *from, size_t size);$

Return~
value of$to$

Description~
This function copies the$size$bytes at$from$into the$size$bytes at$to$, even
if those two blocks of space overlap. In the case of overlap,$memmove()$is
careful to copy the original values of the bytes in the block at$from$,
including those bytes which also belong to the block at$to$.



strcpy() Function                                                 *crv-strcpy*
-----------------
Synopsis~
 $#include <string.h>$
 $char *strcpy(char *restrict to, const char *restrict from);$

Return~
value of$to$

Description~
This copies characters from the string$from$(up to and including the
terminating null character) into the string$to$. Like$memcpy()$, this function
has undefined results if the strings overlap.



strncpy() Function                                               *crv-strncpy*
------------------
Synopsis~
 $#include <string.h>$
 $char *strncpy(char *restrict to, const char *restrict from, size_t size);$

Return~
value of$to$

Description~
This function is similar to$strcpy()$but always copies exactly$size$characters
into$to$. 

If the length of$from$is more than$size$, then$strncpy()$copies just the first
size characters. In this case there is no null terminator written into$to$. 

If the length of$from$is less than$size$, then$strncpy()$copies all of$from$,
followed by enough null characters to add up to$size$characters in all.

The behavior of$strncpy()$is undefined if the strings overlap.

NOTE: Using$strncpy()$as opposed to$strcpy()$is a way to avoid bugs relating
to writing past the end of the allocated space for$to$. However, it can also
make your program much slower in one common case: copying a string which is
probably small into a potentially large buffer. In this case, size may be
large, and when it is,$strncpy()$ will waste a considerable amount of time
copying null characters.




------------------------------------------------------------------------------
II.21.4  Concatenation                                      *crv-libSRHConcat*

Quicklink:
    $strcat()$  Func  |crv-strcat|
    $strncat()$ Func  |crv-strncat|


strcat() Function                                                 *crv-strcat*
-----------------
Synopsis~
 $#include <string.h>$
 $char *strcat(char *restrict to, const char *restrict from);$

Return~
value of$to$

Description~
This function is similar to$strcpy()$, except that the characters from$from$
are concatenated or appended to the end of$to$, instead of overwriting it.
That is, the first character from$from$overwrites the null character marking
the end of$to$.
This function has undefined results if the strings overlap.



strncat() Function                                               *crv-strncat*
------------------
Synopsis~
 $#include <string.h>$
 $char *strncat(char *restrict to, const char *restrict from, size_t size);$

Return~
value of$to$

Description~
This function is like$strcat()$except that not more than$size$characters from
$from$are appended to the end of$to$. A single null character is also always
appended to$to$, so the total allocated size of$to$must be at least
$size + 1$bytes longer than its initial length.
The behavior of this function is undefined if the strings overlap.




------------------------------------------------------------------------------
II.21.5  Comparison                                            *crv-libSRHCmp*

Quicklink:
    $memcmp()$  Func  |crv-memcmp|
    $strcmp()$  Func  |crv-strcmp|
    $strcoll()$ Func  |crv-strcoll|
    $strncmp()$ Func  |crv-strncmp|
    $strxfrm()$ Func  |crv-strxfrm|



memcmp() Function                                                 *crv-memcmp*
-----------------
Synopsis~
 $#include <string.h>$
 $int memcmp(const void *a1, const void *a2, size_t size);$

Return~
The value returned is greater than, equal to, or less than zero, accordingly
as the object pointed to by$a1$is greater than, equal to, or less than the
object pointed to by$a2$.

Description~
This function compares the$size$bytes of memory beginning at$a1$against the
$size$bytes of memory beginning at$a2$. 



strcmp() Function                                                 *crv-strcmp*
-----------------
Synopsis~
 $#include <string.h>$
 $int strcmp(const char *s1, const char *s2);$

Return~
The value returned is greater than, equal to, or less than zero, accordingly
as the string pointed to by$s1$is greater than, equal to, or less than the
string pointed to by$s2$.

Description~
This function compares the string$s1$against$s2$.



strcoll() Function                                               *crv-strcoll*
------------------
Synopsis~
 $#include <string.h>$
 $int strcoll(const char *s1, const char *s2);$

Return~
The value returned is greater than, equal to, or less than zero, accordingly
as the string pointed to by$s1$is greater than, equal to, or less than the
string pointed to by$s2$.


Description~
This function is similar to$strcmp()$but uses the collating sequence of the
current locale for collation (the$LC_COLLATE$locale).



strncmp() Function                                               *crv-strncmp*
------------------
Synopsis~
 $#include <string.h>$
 $int strncmp(const char *s1, const char *s2, size_t size);$

Return~
The value returned is greater than, equal to, or less than zero, accordingly
as the string pointed to by$s1$is greater than, equal to, or less than the
string pointed to by$s2$.

Description~
This function is the similar to$strcmp()$, except that no more than$size$wide
characters are compared. In other words, if the two strings are the same in
their first$size$wide characters, the return value is zero.



strxfrm() Function                                               *crv-strxfrm*
------------------
Synopsis~
 $#include <string.h>$
 $size_t strxfrm(char *restrict to, const char *restrict from, size_t size);$

Return~
The return value is the length of the entire transformed string. 
This value is not affected by the value of$size$, but if it is greater or 
equal than$size$, it means that the transformed string did not entirely fit
in the array$to$. In this case, only as much of the string as actually fits
was stored.

Description~
This function transforms the string$from$using the collation transformation
determined by the locale currently selected for collation, and stores the
transformed string in the array$to$. Up to$size$characters (including a
terminating null character) are stored.

If$size$is zero, no characters are stored in$to$. In this case,$strxfrm()$
simply returns the number of characters that would be the length of the
transformed string. 
This is useful for determining what size the allocated array should be.
It does not matter what$to$is if$size$is zero;$to$may even be a null pointer.

The transformed string may be longer than the original string, and it may
also be shorter.

The behavior is undefined if the strings$to$and$from$overlap. 




------------------------------------------------------------------------------
II.21.6  Search                                             *crv-libSRHSearch*

This section describes library functions which perform various kinds of
searching operations on strings and arrays.

Quicklink:
    $memchr()$  Func  |crv-memchr|
    $strchr()$  Func  |crv-strchr|
    $strcspn()$ Func  |crv-strcspn|
    $strpbrk()$ Func  |crv-strpbrk|
    $strrchr()$ Func  |crv-strrchr|
    $strspn()$  Func  |crv-strspn|
    $strstr()$  Func  |crv-strstr|
    $strtok()$  Func  |crv-strtok|




memchr() Function                                                 *crv-memchr*
-----------------
Synopsis~
 $#include <string.h>$
 $void *memchr(const void *block, int c, size_t size);$

Return~
pointer to the located byte, or null pointer if no match was found

Description~
This function finds the first occurrence of the byte$c$(converted to an
$unsigned char$) in the initial$size$bytes of the object beginning at$block$.



strchr() Function                                                 *crv-strchr*
-----------------
Synopsis~
 $#include <string.h>$
 $char *strchr(const char *string, int c);$

Return~
pointer to the located byte, or null pointer if no match was found

Description~
This function finds the first occurrence of the character$c$(converted to a
$char$) in the null-terminated string beginning at$string$.



strcspn() Function                                               *crv-strcspn*
------------------
Synopsis~
 $#include <string.h>$
 $size_t strcspn(const char *string, const char *stopset);$

Return~
length of substring

Description~
The$strcspn()$("string complement span") function returns the length of the
initial substring of$string$that consists entirely of characters that are not
members of the set specified by the string$stopset$. 
(In other words, it returns the offset of the first character in$string$that
is a member of the set$stopset$.)



strpbrk() Function                                               *crv-strpbrk*
------------------
Synopsis~
 $#include <string.h>$
 $char *strpbrk(const char *string, const char *stopset);$

Return~
returns a pointer to the character, or null pointer if no such character
is found

Description~
The$strpbrk()$("string pointer break") function is related to$strcspn()$,
except that it returns a pointer to the first character in$string$that is a
member of the set$stopset$instead of the length of the initial substring.



strrchr() Function                                               *crv-strrchr*
------------------
Synopsis~
 $#include <string.h>$
 $char *strrchr(const char *string, int c);$

Return~
pointer to the located byte, or null pointer if no match was found

Description~
The function$strrchr()$is like$strchr()$, except that it searches backwards
from the end of the string$string$(instead of forwards from the front).



strspn() Function                                                 *crv-strspn*
-----------------
Synopsis~
 $#include <string.h>$
 $size_t strspn(const char *string, const char *skipset);$

Return~
length of substring

Description~
The$strspn()$("string span") function returns the length of the initial
substring of$string$that consists entirely of characters that are members of
the set specified by the string$skipset$. The order of the characters in
$skipset$is not important.



strstr() Function                                                 *crv-strstr*
-----------------
Synopsis~
 $#include <string.h>$
 $char *strstr(const char *haystack, const char *needle);$

Return~
It returns a pointer into the string$haystack$that is the first character of
the substring, or a null pointer if no match was found. If$needle$is an empty
string, the function returns$haystack$.

Description~
This is like$strchr()$, except that it searches$haystack$for a substring
$needle$rather than just a single character.



strtok() Function                                                 *crv-strtok*
-----------------
Synopsis~
 $#include <string.h>$
 $char *strtok(char *restrict newstring, const char *restrict delimiters);$

Return~
see description

Description~
A string can be split into tokens by making a series of calls to the function
$strtok()$.

The string to be split up is passed as the$newstring$argument on the first
call only. The$strtok()$function uses this to set up some internal state
information. Subsequent calls to get additional tokens from the same string
are indicated by passing a null pointer as the$newstring$argument. Calling
$strtok()$with another non-null$newstring$argument reinitializes the state
information. It is guaranteed that no other library function ever calls
$strtok()$behind your back (which would mess up this internal state
information). 

The$delimiters$argument is a string that specifies a set of delimiters that
may surround the token being extracted. All the initial characters that are
members of this set are discarded. The first character that is not a member
of this set of delimiters marks the beginning of the next token. The end of
the token is found by looking for the next character that is a member of the
$delimiter$set. This character in the original string$newstring$is
overwritten by a null character, and the pointer to the beginning of the token
in$newstring$ is returned.

On the next call to$strtok()$, the searching begins at the next character
beyond the one that marked the end of the previous token. 
Note that the set of delimiters$delimiters$do not have to be the same on every
call in a series of calls to$strtok()$.

If the end of the string$newstring$is reached, or if the remainder of$string$
consists only of delimiter characters,$strtok()$returns a null pointer.

Note that "character" is here used in the sense of byte. In a string using a
multibyte character encoding (abstract) character consisting of more than one
byte are not treated as an entity. Each byte is treated separately. The
function is not locale-dependent.




------------------------------------------------------------------------------
II.21.7  Miscellaneous                                        *crv-libSRHMisc*

Quicklink:
      $memset()$   Func  |crv-memset|
      $strerror()$ Func  |crv-strerror|
      $strlen()$   Func  |crv-strlen|



memset() Function                                                 *crv-memset*
-----------------
Synopsis~
 $#include <string.h>$
 $void *memset(void *block, int c, size_t size);$

Return~
value of$block$

Description~
This function copies the value of$c$(converted to an$unsigned char$) into each
of the first$size$bytes of the object beginning at$block$.



strerror() Function                                             *crv-strerror*
-------------------
Synopsis~
 $#include <string.h>$
 $char *strerror(int errnum);$

Return~
The return value is a pointer to error message, which string should not be
modified. Also, if subsequent calls to$strerror()$are done, the string might
be overwritten. But it's guaranteed that no library function ever calls
$strerror()$.

Description~
This function maps the error code specified by the$errnum$argument to a
descriptive error message string. 
The value$errnum$normally comes from the variable$errno$.



strlen() Function                                                 *crv-strlen*
-----------------
Synopsis~
 $#include <string.h>$
 $size_t strlen(const char *s);$

Return~
length of string

Description~
The$strlen()$function returns the length of the null-terminated string$s$in bytes.




==============================================================================
II.22  <tgmath.h> Type-Generic                                *crv-libTgmathH*

This header file includes$<math.h>$and$<complex.h>$and defines several
type-generic macros.

A type-generic macro expands to a function according to the type of the
macro's parameter(s).
E.g. there is a type-generic macro$fabs(parameter)$.This macro expands to:
  -$fabs()$  if$parameter$is of type$double$
  -$fabsf()$ if$parameter$is of type$float$
  -$fabsl()$ if$parameter$is of type$long double$
  -$cabs()$  if$parameter$is of type$double complex$
  -$cabsf()$ if$parameter$is of type$float complex$
  -$cabsl()$ if$parameter$is of type$long double complex$

For each function declared in$<math.h>$and$<complex.h>$which has no f ($float$)
or l ($long double$) suffix, and which has one or more parameters of type
$double$a type-generic macro is defined (except for$mdof()$).

For each function declared in$<math.h>$which has no suffix and for which there
is a corresponding function in$<complex.h>$with prefix c, a type-generic macro
is defined for both functions that has the name of the function declared
in$<math.h>$.

The type-generic macros determine the real type as follows:
  - if any parameter is of type$long double$, the type determined is
    $long double$
  - otherwise, if any parameter is of type$double$or is of integer type, the
    determined type is$double$
  - otherwise, the type determined is$float$




==============================================================================
II.23  <time.h> Date and Time                                   *crv-libTimeH*

This header defines macros and declares types and functions for manipulating
time.



------------------------------------------------------------------------------
II.23.1  Types                                                 *crv-libTHType*

Quicklink:
    $size_t$  Type  |crv-size_t4|
    $clock_t$ Type  |crv-clock_t|
    $time_t$  Type  |crv-time_t|
    $tm$      Type  |crv-tm|



size_t Type                                                      *crv-size_t4*
-----------
This is an unsigned integer type used to represent the sizes of objects.
Also declared in$<stddef.h>$, see |crv-size_t|.
Also declared in$<stdlib.h>$, see |crv-size_t2|.
Also declared in$<string.h>$, see |crv-size_t3|.
Also declared in$<stdio.h>$,  see |crv-size_t5|.
Also declared in$<wchar.h>$,  see |crv-size_t6|.



clock_t Type                                                     *crv-clock_t*
------------
This is the type of the value returned by the$clock()$function. Values of
type$clock_t$are numbers of clock ticks.



time_t Type                                                       *crv-time_t*
-----------
This is the data type used to represent simple time. Sometimes, it also
represents an elapsed time. When interpreted as a calendar time value, it
represents the number of seconds elapsed since 00:00:00 on January 1, 1970,
Coordinated Universal Time. (This calendar time is sometimes referred to as
the epoch.). 

NOTE: A simple time has no concept of local time zone. Calendar Time T
is the same instant in time regardless of where on the globe the computer is.



struct tm Type                                                        *crv-tm*
--------------
This is the data type used to represent a broken-down time. The structure
contains at least the following members, which can appear in any order. 

$int tm_sec$
   This is the number of full seconds since the top of the minute (normally
   in the range 0 through 59, but the actual upper limit is 60, to allow for
   leap seconds if leap second support is available).

$int tm_min$
   This is the number of full minutes since the top of the hour (in the range
   0 through 59).

$int tm_hour$
   This is the number of full hours past midnight (in the range 0 through 23).

$int tm_mday$
   This is the ordinal day of the month (in the range 1 through 31).

$int tm_mon$
   This is the number of full calendar months since the beginning of the year
   (in the range 0 through 11). 

$int tm_year$
   This is the number of full calendar years since 1900.

$int tm_wday$
   This is the number of full days since Sunday (in the range 0 through 6).

$int tm_yday$
   This is the number of full days since the beginning of the year (in the
   range 0 through 365).

$int tm_isdst$
   This is a flag that indicates whether Daylight Saving Time is (or was, or
   will be) in effect at the time described. The value is positive if
   Daylight Saving Time is in effect, zero if it is not, and negative if the
   information is not available.

Also declared in$<wchar.h>$, see |crv-tm2|.




------------------------------------------------------------------------------
II.23.2  Macros                                                 *crv-libTHMac*

Quicklink:
$CLOCKS_PER_SEC$ Macro  |crv-CLOCKS_PER_SEC|
$NULL$           Macro  |crv-NULL4|



NULL Macro                                                         *crv-NULL4*
----------
Expands to an implementation-defined null pointer constant.
Also defined in$<stddef.h>$, see |crv-NULL|.
Also defined in$<stdlib.h>$, see |crv-NULL2|.
Also defined in$<string.h>$, see |crv-NULL3|.
Also defined in$<stdio.h>$,  see |crv-NULL5|.
Also defined in$<wchar.h>$,  see |crv-NULL6|.



CLOCKS_PER_SEC Macro                                      *crv-CLOCKS_PER_SEC*
--------------------
The value of this macro is the number of clock ticks per second measured by
the$clock()$function.



------------------------------------------------------------------------------
II.23.3  Time Manipulation                                     *crv-libTHMani*

Quicklink:
    $clock()$    Func  |crv-clock|
    $difftime()$ Func  |crv-difftime|
    $mktime()$   Func  |crv-mktime|
    $time()$     Func  |crv-time|



clock() Function                                                   *crv-clock*
----------------
Synopsis~
 $#include <time.h>$
 $clock_t clock(void);$

Return~
CPU time ot (clock_t)(-1) if an error occurred

Description~
This function returns the calling process' current CPU time. If the CPU time
is not available or cannot be represented, clock returns the value
(clock_t)(-1).
Time in seconds can be determined by dividing the result of$clock()$by
$CLOCKS_PER_SECOND$.



difftime() Function                                             *crv-difftime*
-------------------
Synopsis~
 $#include <time.h>$
 $double difftime(time_t time1, time_t time0);$

Return~
seconds elapsed

Description~
This function returns the number of seconds of elapsed time between calendar
time$time1$and calendar time$time0$, as a value of type$double$. The
difference ignores leap seconds unless leap second support is enabled.



mktime() Function                                                 *crv-mktime*
-----------------
Synopsis~
 $#include <time.h>$
 $time_t mktime(struct tm *brokentime);$

Return~
Simple time, or if the specified broken-down time cannot be represented as a
simple time,$mktime()$returns a value of (time_t)(-1) and does not modify the
contents of$brokentime$.

Description~
The$mktime()$function is used to convert a broken-down time structure to a
simple time representation. It also "normalizes" the contents of the
broken-down time structure, by filling in the day of week and day of year
based on the other date and time components.

The$mktime()$function ignores the specified contents of the$tm_wday$and
$tm_yday$members of the broken-down time structure. It uses the values of the
other components to determine the calendar time; it's permissible for these
components to have unnormalized values outside their normal ranges. The last
thing that$mktime()$does is adjust the components of the brokentime structure
(including the$tm_wday$and$tm_yday$).



time() Function                                                     *crv-time*
---------------
Synopsis~
 $#include <time.h>$
 $time_t time(time_t *result);$

Return~
current calenar time or if the current calendar time is not available, 
the value (time_t)(-1)

Description~
The$time()$function returns the current calendar time as a value of type
$time_t$. If the argument$result$is not a null pointer, the calendar time
value is also stored in$*result$. 




------------------------------------------------------------------------------
II.23.4  Time Conversion                                       *crv-libTHConv*

Quicklink:
    $asctime()$   Func  |crv-asctime|
    $ctime()$     Func  |crv-ctime|
    $gmtime()$    Func  |crv-gmtime|
    $localtime()$ Func  |crv-localtime|
    $strftime()$  Func  |crv-strftime|



asctime() Function                                               *crv-asctime*
------------------
Synopsis~
 $#include <time.h>$
 $char *asctime(const struct tm *brokentime);$

Return~
The return value points to a statically allocated string, which might be
overwritten by subsequent calls to$asctime()$or$ctime$. But no other library
function overwrites the contents of this string.

Description~
This function converts the broken-down time value that$brokentime$points to
into a string in a standard format:
  "Tue May 21 13:46:22 1991\n"

The abbreviations for the days of week are: Sun, Mon, Tue, Wed, Thu, Fri, and
Sat.

The abbreviations for the months are: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug,
Sep, Oct, Nov, and Dec. 



ctime() Function                                                   *crv-ctime*
----------------
Synopsis~
 $#include <time.h>$
 $char *ctime(const time_t *time);$

Return~
The return value points to a statically allocated string, which might be
overwritten by subsequent calls to$asctime()$or$ctime$. But no other library
function overwrites the contents of this string.

Description~
The$ctime()$function is similar to$asctime()$, except that calendar time
is specified as a$time_t$simple time value rather than in broken-down local
time format. It is equivalent to:
 $asctime (localtime (time))$



gmtime() Function                                                 *crv-gmtime*
-----------------
Synopsis~
 $#include <time.h>$
 $struct tm *gmtime(const time_t *time);$

Return~
returns pointer to the broken-down time, or a null pointer if the specified
time cannot be converted to UTC

Description~
This function is similar to$localtime()$, except that the broken-down time is
expressed as Coordinated Universal Time (UTC) (formerly called Greenwich Mean
Time (GMT)) rather than relative to a local time zone.



localtime() Function                                           *crv-localtime*
--------------------
Synopsis~
 $#include <time.h>$
 $struct tm *localtime (const time_t *time);$

Return~
returns pointer to the broken-down time, or a null pointer if the specified
time cannot be converted to local time

Description~
The$localtime()$function converts the simple time pointed to by$time$to
broken-down time representation, expressed relative to the user's specified
time zone. 



strftime() Function                                             *crv-strftime*
-------------------
Synopsis~
 $#include <time.h>$
 $size_t strftime(char *s, size_t size, const char *format,$
                 $const struct tm *brokentime;$

Return~
number of characters placed in$s$, not including the terminating null
character
if this number is greater than$size$, zero is returned

Description~
This function is similar to the$sprintf()$function, but the conversion
specifications that can appear in the format$format$are specialized for
printing components of the date and time$brokentime$according to the locale
currently specified for time conversion.

Ordinary characters appearing in the format are copied to the output
string$s$; this can include multibyte character sequences. Conversion
specifiers are introduced by a$%$character, followed by an optional
modifier. The modifier extensions are: 

 - E  Use the locale's alternate representation for date and time. This
      modifier applies to the$%c, %C, %x, %X, %y, %Y$format specifiers.
 - O  Use the locale's alternate numeric symbols for numbers. This modifier
      applies only to numeric format specifiers.


If the format supports the modifier but no alternate representation is
available, it is ignored.

The conversion specifier ends with a format specifier taken from the following
list. The whole % sequence is replaced in the output string as follows:

$%a$ The abbreviated weekday name according to the current locale.
$%A$ The full weekday name according to the current locale.
$%b$ The abbreviated month name according to the current locale.
$%B$ The full month name according to the current locale.
$%c$ The preferred calendar time representation for the current locale.
$%C$ The century of the year. This is equivalent to the greatest integer
     not greater than the year divided by 100.
$%d$ The day of the month as a decimal number (range 01 through 31).
$%D$ The date using the format$%m/%d/%y$.
$%e$ The day of the month like with %d, but padded with blank (range 1
     through 31).
$%F$ The date using the format$%Y-%m-%d$.
$%g$ The year corresponding to the ISO week number, but without the century
     (range 00 through 99). This has the same format and value as$%y$,
     except that if the ISO week number (see$%V$) belongs to the previous
     or next year, that year is used instead.
$%G$ The year corresponding to the ISO week number. This has the same format
     and value as$%Y$, except that if the ISO week number (see %V) belongs
     to the previous or next year, that year is used instead.
$%h$ The abbreviated month name according to the current locale. The action
     is the same as for$%b$.
$%H$ The hour as a decimal number, using a 24-hour clock (range 00 through
     23).
$%I$ The hour as a decimal number, using a 12-hour clock (range 01 through
     12). 
$%j$ The day of the year as a decimal number (range 001 through 366).
$%k$ The hour as a decimal number, using a 24-hour clock like$%H$, but padded
     with blank (range 0 through 23).
$%l$ The hour as a decimal number, using a 12-hour clock like$%I$, but padded
     with blank (range 1 through 12).
$%m$ The month as a decimal number (range 01 through 12).
$%M$ The minute as a decimal number (range 00 through 59).
$%n$ A single \n (newline) character.
$%p$ Either AM or PM, according to the given time value; or the corresponding
     strings for the current locale. Noon is treated as PM and midnight as AM.
$%r$ The complete calendar time using the AM/PM format of the current locale.
$%R$ The hour and minute in decimal numbers using the format$%H:%M$.
$%S$ The seconds as a decimal number (range 00 through 60).
$%t$ A single \t (tabulator) character.
$%T$ The time of day using decimal numbers using the format$%H:%M:%S$.
$%u$ The day of the week as a decimal number (range 1 through 7), Monday
     being 1.
$%U$ The week number of the current year as a decimal number (range 00 through
     53), starting with the first Sunday as the first day of the first week.
     Days preceding the first Sunday in the year are considered to be in week
     00.
$%V$ The ISO 8601:1988 week number as a decimal number (range 01 through 53).
     ISO weeks start with Monday and end with Sunday. Week 01 of a year is the
     first week which has the majority of its days in that year; this is
     equivalent to the week containing the year's first Thursday, and it is
     also equivalent to the week containing January 4. Week 01 of a year can
     contain days from the previous year. The week before week 01 of a year
     is the last week (52 or 53) of the previous year even if it contains days
     from the new year.
$%w$ The day of the week as a decimal number (range 0 through 6), Sunday
     being 0.
$%W$ The week number of the current year as a decimal number (range 00 through
     53), starting with the first Monday as the first day of the first week.
     All days preceding the first Monday in the year are considered to be in
     week 00.
$%x$ The preferred date representation for the current locale.
$%X$ The preferred time of day representation for the current locale.
$%y$ The year without a century as a decimal number (range 00 through 99).
     This is equivalent to the year modulo 100.
$%Y$ The year as a decimal number, using the Gregorian calendar. Years before
     the year 1 are numbered 0, -1, and so on.
$%z$ RFC 822/ISO 8601:1988 style numeric time zone (e.g., -0600 or +0100), or
     nothing if no time zone is determinable.
     A full RFC 822 timestamp is generated by the format
     $"%a, %d %b %Y %H:%M:%S %z"$ (or the equivalent$"%a, %d %b %Y %T %z"$).
$%Z$ The time zone abbreviation (empty if the time zone can't be determined).
$%%$ A literal % character.


The$size$parameter can be used to specify the maximum number of characters to
be stored in the array$s$, including the terminating null character. If the
formatted time requires more than$size$characters,$strftime()$returns zero
and the contents of the array$s$are undefined. Otherwise the return value
indicates the number of characters placed in the array$s$, not including
the terminating null character.

Warning: This convention for the return value which is prescribed in ISO C
can lead to problems in some situations. For certain format strings and
certain locales the output really can be the empty string and this cannot
be discovered by testing the return value only. E.g., in most locales the
AM/PM time format is not supported (most of the world uses the 24 hour
time representation). In such locales$"%p"$will return the empty string,
i.e., the return value is zero. To detect situations like this something 
similar to the following code should be used:
>
  buf[0] = '\1';
  len = strftime (buf, bufsize, format, tp);
  if (len == 0 && buf[0] != '\0')
  {
    /* Something went wrong in the strftime call.  */
    ...
  }


If$s$is a null pointer,$strftime()$does not actually write anything, but
instead returns the number of characters it would have written.




==============================================================================
II.24  <wchar.h> Wide Utilities                                *crv-libWcharH*


------------------------------------------------------------------------------
II.24.1  Types                                                *crv-libWCHType*

Quicklink:
    $mbstate_t$ Type  |crv-mbstate_t|
    $tm$        Type  |crv-tm2|
    $size_t$    Type  |crv-size_t6|
    $wchar_t$   Type  |crv-wchar_t3|
    $wint_t$    Type  |crv-wint_t2|



mbstate_t Type                                                 *crv-mbstate_t*
--------------
A variable of type$mbstate_t$can contain all the information about the shift
state needed from one call to a conversion function to another.


struct tm Type                                                       *crv-tm2*
--------------
Also declared in$<time.h>$, for description see |crv-tm|.


size_t Type                                                      *crv-size_t6*
-----------
This is an unsigned integer type used to represent the sizes of objects.
Also declared in$<stddef.h>$, see |crv-size_t|.
Also declared in$<stdlib.h>$, see |crv-size_t2|.
Also declared in$<string.h>$, see |crv-size_t3|.
Also declared in$<time.h>$,   see |crv-size_t4|.
Also declared in$<stdio.h>$,  see |crv-size_t5|.


wchar_t Type                                                    *crv-wchar_t3*
------------
This data type is used as the base type for wide character strings.
It's range of values can represent distinct codes for all members of the
largest extended character set specified among the supported locales.
Also declared in$<stddef.h>$, see |crv-wchar_t|.
Also declared in$<stdlib.h>$, see |crv-wchar_t2|.


wint_t Type                                                      *crv-wint_t2*
-----------
This is a data type used for parameters and variables that contain a single
wide character.
Also declared in$<wctype.h>$, see |crv-wint_t|.




------------------------------------------------------------------------------
II.24.2  Macros                                                *crv-libWCHMac*

Quicklink:
    $NULL$      Macro  |crv-NULL6|
    $WCHAR_MIN$ Macro  |crv-WCHAR_MIN2|
    $WCHAR_MAX$ Macro  |crv-WCHAR_MAX2|
    $WEOF$      Macro  |crv-WEOF2|


NULL Macro                                                         *crv-NULL6*
----------
Expands to an implementation-defined null pointer constant.
Also defined in$<stddef.h>$, see |crv-NULL|.
Also defined in$<stdlib.h>$, see |crv-NULL2|.
Also defined in$<string.h>$, see |crv-NULL3|.
Also defined in$<time.h>$,   see |crv-NULL4|.
Also defined in$<stdio.h>$,  see |crv-NULL5|.


WCHAR_MIN Macro                                               *crv-WCHAR_MIN2*
WCHAR_MAX Macro                                               *crv-WCHAR_MAX2*
---------------
Minimum and maximum value representable by an object of type$wchar_t$.
Also defined in$<wctype.h>$,  see |crv-libWCHAR_MIN|, |crv-libWCHAR_MAX|.


WEOF Macro                                                         *crv-WEOF2*
----------
This macro expands to an expression of type$wint_t$that is returned by a
number of wide stream functions to indicate an end-of-file condition, or some
other error situation.
Also declared in$<wctype.t>$, see |crv-libWEOF|.




------------------------------------------------------------------------------
II.24.3  Formatted Input/Output                                 *crv-libWCHIO*

Quicklink:
    $fwprintf()$  Func  |crv-fwprintf|
    $swprintf()$  Func  |crv-swprintf|
    $wprintf()$   Func  |crv-wprintf|
    $wscanf()$    Func  |crv-wscanf|
    $fwscanf()$   Func  |crv-fwscanf|
    $swscanf()$   Func  |crv-swscanf|
    $vfwprintf()$ Func  |crv-vfwprintf|
    $vswprintf()$ Func  |crv-vswprintf|
    $vwprintf()$  Func  |crv-vwprintf|
    $vfwscanf()$  Func  |crv-vfwscanf|
    $vswscanf()$  Func  |crv-vswscanf|
    $vwscanf()$   Func  |crv-vwscanf|



wprintf() Function                                               *crv-wprintf*
------------------
Synopsis~
 $#include <wchar.h>$
 $int wprintf(const wchar_t *format, ...);$

Return~
<0:      output error occurred
>= 0:    number of transmitted characters

Description~
This function prints the optional arguments under the control of the wide
format string$format$to the standard output stream$stdout$.
For format string see |crv-libSIOHIOFout|.



fwprintf() Function                                             *crv-fwprintf*
-------------------
Synopsis~
 $#include <stdio.h>$
 $#include <wchar.h>$
 $int fwprintf(FILE *stream, const wchar_t *format, ...);$

Return~
<0:      output error occurred
>= 0:    number of transmitted characters

Description~
This function is just like$wprintf()$, except that the output is written to
the stream$stream$instead of standard output stream$stdout$.



swprintf() Function                                             *crv-swprintf*
-------------------
Synopsis~
 $#include <wchar.h>$
 $int swprintf(wchar_t *s, size_t size, const wchar_t *format, ...);$

Return~
The return value is the number of characters generated for the given input,
excluding the trailing null. If not all output fits into the provided
buffer or an error occurred a negative value is returned. 

Description~
This is like$wprintf()$, except that the output is stored in the wide
character array$s$instead of written to a stream. A null wide character is
written to mark the end of the string. The$size$argument specifies the maximum
number of characters to produce. The trailing null character is counted
towards this limit. 



vwprintf() Function                                             *crv-vwprintf*
-------------------
Synopsis~
 $#include <stdarg.h>$
 $#include <wchar.h>$
 $int vwprintf(const wchar_t *format, va_list ap);$

Return~

Description~
This function is similar to$wprintf()$except that, instead of taking a
variable number of arguments directly, it takes an argument list pointer$ap$.



vfwprintf() Function                                           *crv-vfwprintf*
--------------------
Synopsis~
 $#include <stdarg.h>$
 $#include <stdio.h>$
 $#include <wchar.h>$
 $int vfwprintf(FILE *stream, const wchar_t *format, va_list ap);$

Return~

Description~
This is the equivalent of$fwprintf()$with the variable argument list specified
directly as for$vwprintf()$.



vswprintf() Function                                           *crv-vswprintf*
--------------------
Synopsis~
 $#include <stdarg.h>$
 $#include <stdio.h>$
 $#include <wchar.h>$
 $int vswprintf(wchar_t *s, size_t size, const wchar_t *format, va_list ap);$

Return~

Description~
This is the equivalent of$swprintf()$with the variable argument list specified
directly as for$vwprintf()$.



wscanf() Function                                                 *crv-wscanf*
-----------------
Synopsis~
 $#include <wchar.h>$
 $int wscanf(const wchar_t *format, ...);$

Return~
The return value is normally the number of successful assignments. If an
end-of-file condition is detected before any matches are performed, including
matches against whitespace and literal characters in the template, then$WEOF$
is returned.

Description~
The$wscanf()$function reads formatted input from the stream$stdin$under the
control of the format string$format$. The optional arguments are pointers to
the places which receive the resulting values.
For format string see |crv-libSIOHIOFin|.



fwscanf() Function                                               *crv-fwscanf*
------------------
Synopsis~
 $#include <stdio.h>$
 $#include <wchar.h>$
 $int fwscanf(FILE *stream, const wchar_t *format, ...);$

Return~

Description~
This function is just like$wscanf()$, except that the input is read from the
stream$stream$instead of$stdin$.



swscanf() Function                                               *crv-swscanf*
------------------
Synopsis~
 $#include <wchar.h>$
 $int swscanf (const wchar_t *ws, const char *format, ...);$

Return~

Description~
This is like$wscanf()$, except that the characters are taken from the
null-terminated string$ws$instead of from a$stream$. Reaching the end of the
string is treated as an end-of-file condition.

The behavior of this function is undefined if copying takes place between
objects that overlap.



vwscanf() Function                                               *crv-vwscanf*
------------------
Synopsis~
 $#include <stdarg.h>$
 $#include <wchar.h>$
 $int vwscanf(const wchar_t *format, va_list ap);$

Return~

Description~
This function is similar to$wscanf()$, but instead of taking a variable number
of arguments directly, it takes an argument list pointer ap of type$va_list$.



vfwscanf() Function                                             *crv-vfwscanf*
-------------------
Synopsis~
 $#include <stdarg.h>$
 $#include <stdio.h>$
 $#include <wchar.h>$
 $int vfwscanf(FILE *stream, const wchar_t *format, va_list ap);$

Return~

Description~
This is the equivalent of$fwscanf()$with the variable argument list specified
directly as for$vwscanf()$.



vswscanf() Function                                             *crv-vswscanf*
-------------------
Synopsis~
 $#include <stdarg.h>$
 $#include <wchar.h>$
 $int vswscanf(const wchar_t *s, const wchar_t *format, va_list ap);$

Return~

Description~
This is the equivalent of$swscanf()$with the variable argument list specified
directly as for$vwscanf()$.




------------------------------------------------------------------------------
II.24.4  Character Input/Output                                *crv-libWCHCIO*

Quicklink:
    $fgetwc()$   Func    |crv-fgetwc|
    $fgetws()$   Func    |crv-fgetws|
    $getwc()$    Macro   |crv-getwc|
    $getwchar()$ Macro   |crv-getwchar|
    $ungetwc()$  Func    |crv-ungetwc|
    $fputwc()$   Func    |crv-fputwc|
    $fputws()$   Func    |crv-fputws|
    $putwc()$    Macro   |crv-putwc|
    $putwchar()$ Macro   |crv-putwchar|
    $fwide()$    Func    |crv-fwide|



fgetwc() Function                                                 *crv-fgetwc*
-----------------
Synopsis~
 $#include <stdio.h>$
 $#include <wchar.h>$
 $wint_t fgetwc(FILE *stream);$

Return~
wide character read from stream, or$WEOF$if an error or an end-of-file
condition occurred

Description~
This function reads the next wide character from the stream$stream$and returns
its value.



fgetws() Function                                                 *crv-fgetws*
-----------------
Synopsis~
 $#include <stdio.h>$
 $#include <wchar.h>$
 $wchar_t *fgetws(wchar_t *ws, int count, FILE *stream);$

Return~
If the system is already at end of file when$fgetws()$is called, then the
contents of the array$ws$are unchanged and a null pointer is returned. A null
pointer is also returned if a read error occurs. Otherwise, the return value
is the pointer$ws$. 

Description~
This function reads wide characters from the stream$stream$up to and including
a newline character and stores them in the string$ws$, adding a null wide
character to mark the end of the string.$count$wide characters worth of space
in$ws$must be supplied, but the number of characters read is at most
$count - 1$. The extra character space is used to hold the null wide character
at the end of the string.



getwc() Macro                                                      *crv-getwc*
-------------
Synopsis~
 $#include <stdio.h>$
 $#include <wchar.h>$
 $wint_t getwc(FILE *stream);$

Return~
wide character read from stream, or$WEOF$if an error or an end-of-file
condition occurred

Description~
This is just like$fgetwc()$, except that it is permissible for it to be
implemented as a macro that evaluates the$stream$argument more than once.
$getwc()$can be highly optimized, so it is usually the best function to use
to read a single wide character.



getwchar() Macro                                                *crv-getwchar*
----------------
Synopsis~
 $#include <wchar.h>$
 $wint_t getwchar(void);$

Return~
wide character read from stream, or$WEOF$if an error or an end-of-file
condition occurred

Description~
This function is equivalent to$getwc()$with$stdin$as the value of the stream
argument.



ungetwc() Function                                               *crv-ungetwc*
------------------
Synopsis~
 $#include <stdio.h>$
 $#include <wchar.h>$
 $wint_t ungetwc(wint_t wc, FILE *stream);$

Return~

Description~
The$ungetwc()$function behaves just like$ungetc()$just that it pushes back a
wide character.



fputwc() Function                                                 *crv-fputwc*
-----------------
Synopsis~
 $#include <stdio.h>$
 $#include <wchar.h>$
 $wint_t fputwc(wchar_t wc, FILE *stream);$

Return~
$WEOF$is returned if a write error occurs; otherwise the character$wc$is
returned 

Description~
This function writes the wide character$wc$to the stream$stream$.



fputws() Function                                                 *crv-fputws*
-----------------
Synopsis~
 $#include <stdio.h>$
 $#include <wchar.h>$
 $int fputws(const wchar_t *ws, FILE *stream);$

Return~
$WEOF$is returned if a write error occurs, otherwise a non-negative value

Description~
The function$fputws()$writes the wide character string$ws$to the stream
$stream$. The terminating null character is not written. This function does
not add a newline character, either. It outputs only the characters in the
string.



putwc() Macro                                                      *crv-putwc*
-------------
Synopsis~
 $#include <stdio.h>$
 $#include <wchar.h>$
 $wint_t putwc(wchar_t wc, FILE *stream);$

Return~
$WEOF$is returned if a write error occurs; otherwise the character$wc$is
returned 

Description~
This is just like$fputwc()$, except that it can be implement as a macro, 
making it faster. One consequence is that it may evaluate the$stream$argument
more than once, which is an exception to the general rule for macros.$putwc()$
is usually the best function to use for writing a single wide character.



putwchar() Macro                                                *crv-putwchar*
----------------
Synopsis~
 $#include <wchar.h>$
 $wint_t putwchar(wchar_t wc);$

Return~
$WEOF$is returned if a write error occurs; otherwise the character$wc$is
returned 

Description~
The$putwchar()$function is equivalent to$putwc()$with$stdout$as the value
of the stream argument.



fwide() Function                                                   *crv-fwide*
----------------
Synopsis~
 $#include <stdio.h>$
 $#include <wchar.h>$
 $int fwide(FILE *stream, int mode);$

Return~
The$fwide()$function returns a negative value, zero, or a positive value if
the stream is narrow, not at all, or wide oriented respectively.

Description~
The$fwide()$function can be used to set and query the state of the orientation
of the stream$stream$. If the$mode$parameter has a positive value the streams
get wide oriented, for negative values narrow oriented. It is not possible
to overwrite previous orientations with$fwide()$. I.e., if the stream$stream$
was already oriented before the call nothing is done.

If$mode$is zero the current orientation state is queried and nothing is
changed.




------------------------------------------------------------------------------
II.24.5  String Utilities                                    *crv-libWCHStrng*


II.24.5.1  Numeric Conversions                                 *crv-libWCHNum*
------------------------------

Quicklink:
    $wcstod()$   Func   |crv-wcstod|
    $wcstof()$   Func   |crv-wcstof|
    $wcstold()$  Func   |crv-wcstold|
    $wcstol()$   Func   |crv-wcstol|
    $wcstoll()$  Func   |crv-wcstoll|
    $wcstoul()$  Func   |crv-wcstoul|
    $wcstoull()$ Func   |crv-wcstoull|



wcstod()  Function                                                *crv-wcstod*
wcstof()  Function                                                *crv-wcstof*
wcstold() Function                                               *crv-wcstold*
------------------
Synopsis~
 $#include <wchar.h>$
 $double wcstod(const wchar_t *restrict string, wchar_t **restrict tailptr);$
 $float wcstof(const wchar_t *string, wchar_t **tailptr);$
 $long double wcstold(const wchar_t *string, wchar_t **tailptr);$

Description~
The$wcstod()$,$wcstof()$, and$wcstol()$functions are equivalent in nearly all
aspect to the$strtod()$,$strtof()$, and$strtold()$functions but it handles
wide character string.



wcstol()   Function                                               *crv-wcstol*
wcstoll()  Function                                              *crv-wcstoll*
wcstoul()  Function                                              *crv-wcstoul*
wcstoull() Function                                             *crv-wcstoull*
-------------------
Synopsis~
 $#include <wchar.h>$
 $long int wcstol(const wchar_t *restrict string,$
                 $wchar_t **restrict tailptr, int base);$
 $long long int wcstoll(const wchar_t *restrict string,$
                 $wchar_t **restrict tailptr, int base);$
 $unsigned long int wcstoul(const wchar_t *restrict string,$
                           $wchar_t **restrict tailptr, int base);$
 $unsigned long long int wcstoull(const wchar_t *restrict string,$
                                 $wchar_t **restrict tailptr, int base);$
  
Description~
The$wcstol()$,$wcstoll()$,$wcstoul()$,$wcstoull()$functions are equivalent in
nearly all aspectes to$strtol()$,$strstoll()$,$strtoul()$,$strtoull()$
functions but handels wide character string.




II.24.5.2  Copying                                            *crv-libWCHCopy*
------------------

Quicklink:
    $wcscpy()$   Func  |crv-wcscpy|
    $wcsncpy()$  Func  |crv-wcsncpy|
    $wmemcpy()$  Func  |crv-wmemcpy|
    $wmemmove()$ Func  |crv-wmemmove|


wcscpy() Function                                                 *crv-wcscpy*
-----------------
Synopsis~
 $#include <wchar.h>$
 $wchar_t *wcscpy(wchar_t *restrict wto, const wchar_t *restrict wfrom);$

Return~
value is the value of$wto$

Description~
This copies wide characters from the string$wfrom$(up to and including the
terminating null wide character) into the string$wto$. Like$wmemcpy()$, this
function has undefined results if the strings overlap. 



wcsncpy() Function                                               *crv-wcsncpy*
------------------
Synopsis~
 $#include <wchar.h>$
 $wchar_t *wcsncpy(wchar_t *restrict wto, const wchar_t *restrict wfrom,$
                  $size_t size);$

Return~
value is the value of$wto$

Description~
This function is similar to$wcscpy()$but always copies exactly$size$wide
characters into$wto$.

If the length of$wfrom$is more than$size$, then$wcsncpy()$copies just the
first$size$wide characters. Note that in this case there is no null
terminator written into$wto$.

If the length of$wfrom$is less than$size$, then$wcsncpy()$copies all of
$wfrom$, followed by enough null wide characters to add up to$size$wide
characters in all. 

The behavior of$wcsncpy()$is undefined if the strings overlap.



wmemcpy() Function                                               *crv-wmemcpy*
------------------
Synopsis~
 $#include <wchar.h>$
 $wchar_t *wmemcpy(wchar_t *restrict wto, const wchar_t *restruct wfrom,$
                  $size_t size);$

Return~
value is the value of$wto$

Description~
The$wmemcpy()$function copies$size$wide characters from the object beginning
at$wfrom$into the object beginning at$wto$. The behavior of this function is
undefined if the two arrays$wto$and$wfrom$overlap; use$wmemmove()$instead if
overlapping is possible.



wmemmove() Function                                             *crv-wmemmove*
-------------------
Synopsis~
 $#include <wchar.h>$
 $wchar_t *wmemmove(wchar *wto, const wchar_t *wfrom, size_t size);$

Return~
value is the value of$wto$

Description~
This function copies the$size$wide characters at$wfrom$into the$size$wide
characters at$wto$, even if those two blocks of space overlap. In the case of
overlap,$memmove()$is careful to copy the original values of the wide
characters in the block at$wfrom$, including those wide characters which also
belong to the block at$wto$.




II.24.5.3  Concatenation                                    *crv-libWCHConcat*
------------------------

Quicklink:
    $wcscat()$  Func  |crv-wcscat|
    $wcsncat()$ Func  |crv-wcsncat|


wcscat() Function                                                 *crv-wcscat*
-----------------
Synopsis~
 $#include <wchar.h>$
 $wchar_t *wcscat(wchar_t *restrict wto, const wchar_t *restrict wfrom);$

Return~
value is the value of$wto$

Description~
The$wcscat()$function is similar to$wcscpy()$, except that the characters
fromw$from$are concatenated or appended to the end of$wto$, instead of
overwriting it. That is, the first character from$wfrom$overwrites the null
character marking the end of$wto$.



wcsncat() Function                                               *crv-wcsncat*
------------------
Synopsis~
 $#include <wchar.h>$
 $wchar_t *wcsncat(wchar_t *restrict wto, const wchar_t *restrict wfrom,$
                  $size_t size);$

Return~
value is the value of$wto$

Description~
This function is like$wcscat()$except that not more than$size$characters
from$from$are appended to the end of$wto$. A single null character is also
always appended to$wto$, so the total allocated size of$wto$ must be at least
$size + 1$bytes longer than its initial length.




II.24.5.4  Comparison                                          *crv-libWCHCmp*
---------------------

Quicklink:
    $wcscmp()$  Func  |crv-wcscmp|
    $wcscoll()$ Func  |crv-wcscoll|
    $wcsncmp()$ Func  |crv-wcsncmp|
    $wcsxfrm()$ Func  |crv-wcsxfrm|
    $wmemcmp()$ Func  |crv-wmemcmp|



wcscmp() Function                                                 *crv-wcscmp*
-----------------
Synopsis~
 $#include <wchar.h>$
 $int wcscmp(const wchar_t *ws1, const wchar_t *ws2);$

Return~
The value returned is greater than, equal to, or less than zero, accordingly
as the string pointed to by$ws1$is greater than, equal to, or less than the
string pointed to by$ws2$.

A consequence of the ordering used by$wcscmp()$is that if$ws1$is an initial
substring of$ws2$, then$ws1$is considered to be "less than"$ws2$.

Description~
The$wcscmp()$function compares the wide character string$ws1$against$ws2$. 



wcscoll() Function                                               *crv-wcscoll*
------------------
Synopsis~
 $#include <wchar.h>$
 $int wcscoll(const wchar_t *ws1, const wchar_t *ws2);$

Return~
The value returned is greater than, equal to, or less than zero, accordingly
as the string pointed to by$ws1$is greater than, equal to, or less than the
string pointed to by$ws2$.

Description~
The$wcscoll()$function is similar to$wcscmp()$but uses the collating sequence
of the current locale for collation (the$LC_COLLATE$locale).



wcsncmp() Function                                               *crv-wcsncmp*
------------------
Synopsis~
 $#include <wchar.h>$
 $int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t size);$

Return~
The value returned is greater than, equal to, or less than zero, accordingly
as the string pointed to by$ws1$is greater than, equal to, or less than the
string pointed to by$ws2$.

Description~
This function is the similar to$wcscmp()$, except that no more than$size$wide
characters are compared. In other words, if the two strings are the same in
their first$size$wide characters, the return value is zero.



wcsxfrm() Function                                               *crv-wcsxfrm*
------------------
Synopsis~
 $#include <wchar.h>$
 $size_t wcsxfrm(wchar_t *restrict wto, const wchar_t *wfrom, size_t size);$

Description~
This function is the similar to$strxfrm()$but handles wide characters.
See |crv-libstrxfrm| for further information on$strxfrm()$.



wmemcmp() Function                                               *crv-wmemcmp*
------------------
Synopsis~
 $#include <wchar.h>$
 $int wmemcmp(const wchar_t *a1, const wchar_t *a2, size_t size);$

Return~
The value returned is greater than, equal to, or less than zero, accordingly
as the string pointed to by$a1$is greater than, equal to, or less than the
string pointed to by$a2$.

Description~
The function$wmemcmp()$compares the$size$wide characters beginning at$a1$
against the$size$wide characters beginning at$a2$.




II.24.5.5  Search                                           *crv-libWCHSearch*
-----------------

Quicklink:
    $wcschr()$  Func  |crv-wcschr|
    $wcscspn()$ Func  |crv-wcscspn|
    $wcspbrk()$ Func  |crv-wcspbrk|
    $wcsrchr()$ Func  |crv-wcsrchr|
    $wcsspn()$  Func  |crv-wcsspn|
    $wcsstr()$  Func  |crv-wcsstr|
    $wcstok()$  Func  |crv-wcstok|
    $wmemchr()$ Func  |crv-wmemchr|



wcschr() Function                                                 *crv-wcschr*
-----------------
Synopsis~
 $#include <wchar.h>$
 $wchar_t * wcschr(const wchar_t *wstring, int wc);$

Description~
This function is the similar to$strchr()$but handles wide character.



wcscspn() Function                                               *crv-wcscspn*
------------------
Synopsis~
 $#include <wchar.h>$
 $size_t wcscspn(const wchar_t *wstring, const wchar_t *stopset);$

Description~
This function is the similar to$strspn()$but handles wide character.



wcspbrk() Function                                               *crv-wcspbrk*
------------------
Synopsis~
 $#include <wchar.h>$
 $wchar_t *wcspbrk (const wchar_t *wstring, const wchar_t *stopset);$

Description~
This function is the similar to$strpbrk()$but handles wide character.



wcsrchr() Function                                               *crv-wcsrchr*
------------------
Synopsis~
 $#include <wchar.h>$
 $wchar_t *wcsrchr (const wchar_t *wstring, wchar_t c);$

Description~
This function is the similar to$strrchr()$but handles wide character.



wcsspn() Function                                                 *crv-wcsspn*
-----------------
Synopsis~
 $#include <wchar.h>$
 $size_t wcsspn(const wchar_t *wstring, const wchar_t *skipset);$

Description~
This function is the similar to$strspn()$but handles wide character.



wcsstr() Function                                                 *crv-wcsstr*
-----------------
Synopsis~
 $#include <wchar.h>$
 $wchar_t *wcsstr(const wchar_t *haystack, const wchar_t *needle);$

Description~
This function is the similar to$strstr()$but handles wide character.



wcstok() Function                                                 *crv-wcstok*
-----------------
Synopsis~
 $#include <wchar.h>$
 $wchar_t *wcstok(wchar_t *newstring, const char *delimiters);$

Description~
This function is the similar to$strtok()$but handles wide character.



wmemchr() Function                                               *crv-wmemchr*
------------------
Synopsis~
 $#include <wchar.h>$
 $wchar_t *wmemchr(const wchar_t *block, wchar_t wc, size_t size);$

Description~
This function is the similar to$memchr()$but handles wide character.




II.24.5.6  Miscellaneous                                      *crv-libWCHMisc*
------------------------

Quicklink:
    $wmemset()$ Func  |crv-wmemset|
    $wcslen()$  Func  |crv-wcslen|



wcslen() Function                                                 *crv-wcslen*
-----------------
Synopsis~
 $#include <wchar.h>$
 $size_t wcslen(const wchar_t *ws);$

Description~
This function is the similar to$strlen()$but handles wide character.



wmemset() Function                                               *crv-wmemset*
------------------
Synopsis~
 $#include <wchar.h>$
 $wchar_t *wmemset(wchar_t *block, wchar_t wc, size_t size);$

Description~
This function is the similar to$memset()$but handles wide character.




------------------------------------------------------------------------------
II.24.6  Time Conversions                                 *crv-libWCHTimeConv*

Quicklink:
    $wcsftime()$ Func  |crv-wcsftime|



wcsftime() Function                                             *crv-wcsftime*
-------------------
Synopsis~
 $#include <time.h>$
 $#include <wchar.h>$
 $size_t wcsftime(wchar_t *s, size_t size, const wchar_t *template,$
                 $const struct tm *brokentime);$

Description~
This function is the similar to$strftime()$but handles wide character.




------------------------------------------------------------------------------
II.24.7  Character Conversions                            *crv-libWCHCharConv*

Quicklink:
    $btowc()$     Func  |crv-btowc|
    $wctob()$     Func  |crv-wctob|
    $mbsinit()$   Func  |crv-mbsinit|
    $mbrlen()$    Fucn  |crv-mbrlen|
    $mbrtowc()$   Func  |crv-mbrtowc|
    $wcrtomb()$   Func  |crv-wcrtomb|
    $mbsrtowc()$  Func  |crv-mbsrtowc|
    $wcsrtombs()$ Func  |crv-wcsrtombs|



btowc() Function                                                   *crv-btowc*
----------------
Synopsis~
 $#include <stdio.h>$
 $#include <wchar.h>$
 $wint_t btowc(int c);$

Return~
If ($unsigned char$)$c$is no valid single byte multibyte character or if$c$
is$EOF$, the function returns$WEOF$. Otherwise the wide character
representation of$c$is returned.

Description~
The$btowc()$function ("byte to wide character") converts a valid single byte
character$c$in the initial shift state into the wide character equivalent
using the conversion rules from the currently selected locale of the$LC_CTYPE$
category.



wctob() Function                                                   *crv-wctob*
----------------
Synopsis~
 $#include <stdio.h>$
 $#include <wchar.h>$
 $int wctob(wint_t c);$

Return~
If the multibyte representation for this character in the initial state is
exactly one byte long, the return value of this function is this character.
Otherwise the return value is$EOF$.

Description~
The$wctob()$function ("wide character to byte") takes as the parameter a valid
wide character. 



mbsinit() Function                                               *crv-mbsinit*
------------------
Synopsis~
 $#include <wchar.h>$
 $int mbsinit(const mbstate_t *ps);$

Return~
If$ps$is a null pointer or the object is in the initial state the return value
is nonzero. Otherwise it is zero.

Description~
The$mbsinit()$function determines whether the state object pointed to by$ps$is
in the initial state.



mbrlen() Fucntion                                                 *crv-mbrlen*
-----------------
Synopsis~
 $#include <wchar.h>$
 $size_t mbrlen(const char *restrict s, size_t n, mbstate_t *ps);$

Return~
see description

Description~
The$mbrlen()$function ("multibyte restartable length") computes the number of
at most$n$bytes starting at$s$, which form the next valid and complete
multibyte character.

If the next multibyte character corresponds to the NUL wide character, the
return value is 0. If the next$n$bytes form a valid multibyte character, the
number of bytes belonging to this multibyte character byte sequence is
returned.

If the the first$n$bytes possibly form a valid multibyte character but the
character is incomplete, the return value is$(size_t) - 2$. Otherwise the
multibyte character sequence is invalid and the return value
is$(size_t) - 1$.

The multibyte sequence is interpreted in the state represented by the object
pointed to by$ps$. If$ps$ is a null pointer, a state object local
to$mbrlen()$is used.



mbrtowc() Function                                               *crv-mbrtowc*
------------------
Synopsis~
 $#include <wchar.h>$
 $size_t mbrtowc(wchar_t *restrict pwc, const char *restrict s,$
                $size_t n, mbstate_t *restrict ps);$

Return~
see description

Description~
The$mbrtowc()$function ("multibyte restartable to wide character") converts
the next multibyte character in the string pointed to by$s$into a wide
character and stores it in the wide character string pointed to by$pwc$. The
conversion is performed according to the locale currently selected for
the$LC_CTYPE$category. If the conversion for the character set used in the
locale requires a state, the multibyte string is interpreted in the state
represented by the object pointed to by$ps$. If$ps$is a null pointer, a
static, internal state variable used only by the$mbrtowc()$function is used.

If the next multibyte character corresponds to the NUL wide character, the
return value of the function is 0 and the state object is afterwards in the
initial state. If the next$n$or fewer bytes form a correct multibyte
character, the return value is the number of bytes starting from$s$that form
the multibyte character. The conversion state is updated according to the
bytes consumed in the conversion. In both cases the wide character (either
the L'\0' or the one found in the conversion) is stored in the string
pointed to by$pwc$if$pwc$is not null.

If the first$n$bytes of the multibyte string possibly form a valid multibyte
character but there are more than$n$bytes needed to complete it, the return
value of the function is$(size_t) - 2$and no value is stored. Please note
that this can happen even if$n$has a value greater than or equal
to$MB_CUR_MAX$since the input might contain redundant shift sequences.

If the first$n$bytes of the multibyte string cannot possibly form a valid
multibyte character, no value is stored, the global variable$errno$is set to
the value$EILSEQ$, and the function returns$(size_t) - 1$. The conversion
state is afterwards undefined.



wcrtomb() Function                                               *crv-wcrtomb*
-----------------
Synopsis~
 $#include <stdio.h>$
 $#include <wchar.h>$
 $size_t wcrtomb(char *restrict s, wchar_t wc, mbstate_t *restrict ps);$

Return~
see description

Description~
The$wcrtomb()$function ("wide character restartable to multibyte") converts a
single wide character into a multibyte string corresponding to that wide
character.

If$s$is a null pointer, the function resets the state stored in the objects
pointed to by$ps$(or the internal$mbstate_t$object) to the initial state. This
can also be achieved by a call like this:

 $wcrtombs(temp_buf, L'\0', ps)$

since, if$s$is a null pointer,$wcrtomb()$performs as if it writes into an
internal buffer, which is guaranteed to be large enough.

If$wc$is the NUL wide character,$wcrtomb()$emits, if necessary, a shift
sequence to get the state$ps$into the initial state followed by a single
$NULL$byte, which is stored in the string$s$.

Otherwise a byte sequence (possibly including shift sequences) is written into
the string$s$. This only happens if$wc$is a valid wide character. If$wc$is no
valid wide character, nothing is stored in the strings$s$,$errno$is set
to$EILSEQ$, the conversion state in$ps$is undefined and the return value
is$(size_t) - 1$.

If no error occurred the function returns the number of bytes stored in the
string$s$. This includes all bytes representing shift sequences.



mbsrtowc() Function                                             *crv-mbsrtowc*
-------------------
Synopsis~
 $#include <stdio.h>$
 $#include <wchar.h>$
 $size_t mbsrtowcs(wchar_t *restrict dst, const char **restrict src,$
                  $size_t len, mbstate_t *restrict ps);$

Return~
see description

Description~
The$mbsrtowcs()$function ("multibyte string restartable to wide character
string") converts an NUL-terminated multibyte character string at$*src$into an
equivalent wide character string, including the NUL wide character at the end.
The conversion is started using the state information from the object pointed
to by$ps$or from an internal object of$mbsrtowcs()$if$ps$is a null pointer.
Before returning, the state object is updated to match the state after the
last converted character. The state is the initial state if the terminating
NUL byte is reached and converted.

If$dst$is not a null pointer, the result is stored in the array pointed to
by$dst$; otherwise, the conversion result is not available since it is stored
in an internal buffer.

If$len$wide characters are stored in the array$dst$before reaching the end of
the input string, the conversion stops and$len$is returned. If$dst$is a null
pointer,$len$is never checked.

Another reason for a premature return from the function call is if the input
string contains an invalid multibyte sequence. In this case the global
variable$errno$is set to$EILSEQ$and the function returns$(size_t) - 1$.

In all other cases the function returns the number of wide characters
converted during this call. If$dst$is not null,$mbsrtowcs()$stores in the
pointer pointed to by$src$either a null pointer (if the NUL byte in the
input string was reached) or the address of the byte following the last
converted multibyte character.



wcsrtombs() Function                                           *crv-wcsrtombs*
--------------------
Synopsis~
 $#include <stdio.h>$
 $#include <wchar.h>$
 $size_t wcsrtombs(char *restrict dst, const wchar_t **restrict src,$
                  $size_t len, mbstate_t *restrict ps);$

Return~
see description

Description~
The$wcsrtombs()$function ("wide character string restartable to multibyte
string") converts the NUL-terminated wide character string at$*src$ into an
equivalent multibyte character string and stores the result in the array
pointed to by$dst$. The NUL wide character is also converted. The conversion
starts in the state described in the object pointed to by$ps$or by a state
object locally to$wcsrtombs()$in case$ps$is a null pointer. If$dst$is a
null pointer, the conversion is performed as usual but the result is not
available. If all characters of the input string were successfully converted
and if$dst$is not a null pointer, the pointer pointed to by$src$gets assigned
a null pointer.

If one of the wide characters in the input string has no valid multibyte
character equivalent, the conversion stops early, sets the global variable
$errno$to$EILSEQ$, and returns$(size_t) - 1$.

Another reason for a premature stop is if$dst$is not a null pointer and the
next converted character would require more than$len$bytes in total to the
array$dst$. In this case (and if$dest$is not a null pointer) the pointer
pointed to by$src$is assigned a value pointing to the wide character right
after the last one successfully converted.

Except in the case of an encoding error the return value of the$wcsrtombs()$
function is the number of bytes in all the multibyte character sequences
stored in$dst$. Before returning the state in the object pointed to by$ps$
(or the internal object in case$ps$is a null pointer) is updated to reflect
the state after the last conversion. The state is the initial shift state
in case the terminating NUL wide character was converted.




==============================================================================
II.25  <wctype.h> Wide Character                              *crv-libWctypeH*

In this section wide character classification and mapping utilities are
described.


------------------------------------------------------------------------------
II.25.1  Types                                                *crv-libWTHType*

Quicklink:
    $wctrans_t$ Type  |crv-wctrans_t|
    $wctype_t$  Type  |crv-wctype_t|
    $wint_t$    Type  |crv-wint_t|



wint_t Type                                                       *crv-wint_t*
-----------
This is a data type used for parameters and variables that contain a single
wide character.
Also declared in$<wchar.h>$, see |crv-libwint_t2|.



wctrans_t Type                                                 *crv-wctrans_t*
--------------
This data type is defined as a scalar type which can hold a value representing
the locale-dependent character mapping. There is no way to construct such a
value apart from using the return value of the$wctrans()$function.



wctype_t Type                                                   *crv-wctype_t*
-------------
This type can hold a value which represents a character class. The only
defined way to generate such a value is by using the$wctype()$function.




------------------------------------------------------------------------------
II.25.2  Macros                                                *crv-libWTHMac*


WEOF Macro                                                          *crv-WEOF*
----------
This macro expands to an expression of type$wint_t$that is returned by a
number of wide stream functions to indicate an end-of-file condition, or some
other error situation.
Also declared in$<wchar.t>$, see |crv-WEOF2|.



------------------------------------------------------------------------------
II.25.3  Classification                                      *crv-libWTHClass*


II.25.3.1  Wide Character                                    *crv-libWTHCwide*
-------------------------

Quicklink:
    $iswalnum()$  Func  |crv-iswalnum|
    $iswalpha()$  Func  |crv-iswalpha|
    $iswblank()$  Func  |crv-iswblank|
    $iswcntrl()$  Func  |crv-iswcntrl|
    $iswdigit()$  Func  |crv-iswdigit|
    $iswgraph()$  Func  |crv-iswgraph|
    $iswlower()$  Func  |crv-iswlower|
    $iswprint()$  Func  |crv-iswprint|
    $iswpunct()$  Func  |crv-iswpunct|
    $iswspace()$  Func  |crv-iswspace|
    $iswupper()$  Func  |crv-iswupper|
    $iswxdigit()$ Func  |crv-iswxdigit|



iswalnum() Function                                             *crv-iswalnum*
-------------------
Synopsis~
 $#include <wctype.h>$
 $int iswalnum(wint_t wc);$

Description~
This function returns a nonzero value if$wc$is an alphanumeric character (a
letter or number); in other words, if either$iswalpha()$or$iswdigit()$is true
of a character, then$iswalnum()$is also true.



iswalpha() Function                                             *crv-iswalpha*
-------------------
Synopsis~
 $#include <wctype.h>$
 $int iswalpha(wint_t wc);$

Description~
Returns true if$wc$is an alphabetic character (a letter). If$iswlower()$or
$iswupper()$is true of a character, then$iswalpha()$is also true.



iswblank() Function                                             *crv-iswblank*
-------------------
Synopsis~
 $#include <wctype.h>$
 $int iswblank(wint_t wc);$

Description~
Returns true if$wc$is a blank character; that is, a space or a tab.



iswcntrl() Function                                             *crv-iswcntrl*
-------------------
Synopsis~
 $#include <wctype.h>$
 $int iswcntrl(wint_t wc);$

Description~
Returns true if$wc$is a control character (that is, a character that is not a
printing character).



iswdigit() Function                                             *crv-iswdigit*
-------------------
Synopsis~
 $#include <wctype.h>$
 $int iswdigit(wint_t wc);$

Description~
Returns true if$wc$is a digit (e.g., 0 through 9). Please note that this
function does not only return a nonzero value for decimal digits, but for
all kinds of digits.



iswgraph() Function                                             *crv-iswgraph*
-------------------
Synopsis~
 $#include <wctype.h>$
 $int iswgraph(wint_t wc);$

Description~
Returns true if$wc$is a graphic character; that is, a character that has a
glyph associated with it. The whitespace characters are not considered
graphic.
In other words: returns true if$iswprint()$is true and if$iswspace()$is false.



iswlower() Function                                             *crv-iswlower*
-------------------
Synopsis~
 $#include <wctype.h>$
 $int iswlower(wint_t wc);$

Description~
Returns true if$wc$is a lower-case letter.



iswprint() Function                                             *crv-iswprint*
-------------------
Synopsis~
 $#include <wctype.h>$
 $int iswprint(wint_t wc);$

Description~
Returns true if$wc$is a printing character. Printing characters include all
the graphic characters, plus the space (" ") character.



iswpunct() Function                                             *crv-iswpunct*
-------------------
Synopsis~
 $#include <wctype.h>$
 $int iswpunct(wint_t wc);$

Description~
Returns true if$wc$is a punctuation character. This means any printing
character that is not alphanumeric or a space character.



iswspace() Function                                             *crv-iswspace*
-------------------
Synopsis~
 $#include <wctype.h>$
 $int iswspace(wint_t wc);$

Description~
Returns true if$wc$is a whitespace character. In the standard "C" locale,
$iswspace()$returns true for only the standard whitespace characters:

 $L' '$  space
 $L'\f'$ formfeed
 $L'\n'$ newline 
 $L'\r'$ carriage return 
 $L'\t'$ horizontal tab 
 $L'\v'$ vertical tab



iswupper() Function                                             *crv-iswupper*
-------------------
Synopsis~
 $#include <wctype.h>$
 $int iswupper(wint_t wc);$

Description~
Returns true if$wc$is an upper-case letter.



iswxdigit() Function                                           *crv-iswxdigit*
--------------------
Synopsis~
 $#include <wctype.h>$
 $int iswxdigit(wint_t wc);$

Description~
Returns true if$wc$is a hexadecimal digit. Hexadecimal digits include the
normal decimal digits 0 through 9 and the letters A through F and a through f.





II.25.3.2  Extensible Wide Char                            *crv-libWTHCextens*
-------------------------------

Quicklink:
    $iswctype()$ Func  |crv-iswctype|
    $wctype()$   Func  |crv-wctype|


iswctype() Function                                             *crv-iswctype*
-------------------
Synopsis~
 $#include <wctype.h>$
 $int iswctype(wint_t wc, wctype_t desc);$

Description~
This function returns a nonzero value if$wc$is in the character class
specified by$desc$.$desc$must previously be returned by a successful call
to$wctype()$.



wctype() Function                                                 *crv-wctype*
-----------------
Synopsis~
 $#include <wctype.h>$
 $wctype_t wctype(const char *property);$

Description~
The$wctype()$returns a value representing a class of wide characters which is
identified by the string$property$. Beside some standard properties each
locale can define its own ones. In case no$property$with the given name is
known for the current locale selected for the$LC_CTYPE$category, the function
returns zero.

The properties known in every locale are: 
$"alnum"$
$"alpha"$
$"cntrl"$
$"digit"$
$"graph"$
$"lower"$
$"print"$
$"punct"$
$"space"$
$"upper"$
$"xdigit"$



------------------------------------------------------------------------------
II.25.4  Mapping                                               *crv-libWTHMap*


II.25.4.1  Wide Character                                    *crv-libWTHMwide*
-------------------------

Quicklink:
    $towlower()$ Func  |crv-towlower|
    $towupper()$ Func  |crv-towupper|



towlower() Function                                             *crv-towlower*
-------------------
Synopsis~
 $#include <wctype.h>$
 $wint_t towlower(wint_t wc);$

Return~
lower-case letter

Description~
If$wc$is an upper-case letter,$towlower()$returns the corresponding lower-case
letter. Otherwise$wc$is returned unchanged.  



towupper()  Function                                            *crv-towupper*
-------------------
Synopsis~
 $#include <wctype.h>$
 $wint_t towupper(wint_t wc);$

Return~
upper-case letter

Description~
If$wc$is a lower-case letter,$towupper()$returns the corresponding upper-case
letter. Otherwise$wc$is returned unchanged. 




II.25.4.2  Extensible Wide Char                            *crv-libWTHMextens*
-------------------------------

Quicklink:
    $towctrans()$ Func  |crv-towctrans|
    $wctrans()$   Func  |crv-wctrans|



towctrans() Function                                           *crv-towctrans*
--------------------
Synopsis~
 $#include <wctype.h>$
 $wint_t towctrans(wint_t wc, wctrans_t desc);$

Return~
mapped value of$wc$

Description~
This function maps the input character$wc$according to the rules of the
mapping for which$desc$is a descriptor, and returns the value it finds.$desc$
must be obtained by a successful call to$wctrans()$.



wctrans() Function                                               *crv-wctrans*
------------------
Synopsis~
 $#include <wctype.h>$
 $wctrans_t wctrans(const char *property);$

Return~
0:    mapping unknown
else: mapping known

Description~
This function has to be used to find out whether a named mapping is defined in
the current locale selected for the$LC_CTYPE$category. If the returned value
is non-zero, it can be used afterwards in calls to$towctrans()$. If the return
value is zero no such mapping is known in the current locale.

Beside locale-specific mappings there are two mappings which are guaranteed
to be available in every locale:
$"tolower"$
$"toupper"$




==============================================================================
Appendix A  GLOSSARY                                            *crv-glossary*


                                                            *crv-gloAlignment*
Alignment     Requirement that objects of a particular type be located on
              storage boundaries with addresses that are particular 
              multiples of a byte address.

                                                             *crv-gloArgument*
Argument      An argument is an expression in a comma-separated list bounded
              by parentheses in a function call or macro invocation.

                                                                *crv-gloArray*
Array         Set of elements that have the same data type.

                                                               *crv-gloBinary*
Binary        see Operator |crv-gloOperator|

                                                                *crv-gloBlock*
Block         C statements enclosed within braces ({...})

                                                            *crv-gloCompState*
Compound      A compound statement is a block (see |crv-gloBlock|)
Statement
                                                             *crv-gloDataType*
Data Type     see Type |crv-gloType|

                                                          *crv-gloDeclaration*
Declaration   A C construct that associates the attributes of a variable, 
              type or function with a name. A declaration does not need 
              memory, opposed to a definition (-> Definition).

              Example:
>
                struct MeasVar {
                   int   nCntr;
                   int   nNumOfCycles;
                   float fResult;
                };
<
                                                           *crv-gloDefinition*
Definition    A C construct that specifies the name, formal parameters, body
              and return type of a function or that initializes and allocates
              storage for a variable. A definition needs memory, opposed 
              to a declaration (-> Declaration).

              Example:
>
                struct MeasVar mv;
<
                                                           *crv-gloExpression*
Expression    An expression is a sequence of operators and operands that
              specifies computation of a value or that designates an object
              or function.
              See |crv-gloOperand|, |crv-gloOperator|


False / True  see |crv-gloTrueFalse|

                                                           *crv-gloIdentifier*
Identifier    An identifier is a name of a variable, function, macro...
              Valid identifiers consists of uppercase and lowercase Latin
              letters [a-z], [A-Z] and digits [0-9] and the underscore _.
              They must start with a letter or underscore and must be 
              different to keywords.

                                                             *crv-gloLifetime*
Lifetime      The lifetime of a variable is the portion of program execution
              during which storage is guaranteed to be reserved for it.
              Throughout its lifetime a variable exists, has a fix address 
              and retains its last assigned value.

                                                              *crv-gloLinkage*
Linkage       Linkage is used to extend the scope of a variable or function
              to the actual context. The keyword$extern$is used for that.
              
                                                               *crv-gloLvalue*
lvalue        A lvalue is an epxression that describes the location of an
              object. The location is the object's lvalue. The object's rvalue
              is the value stored at the location described by the lvalue.

                                                            *crv-gloLvalueMod*
lvalue,       A modifiable lvalue is an expression representing an object that
modifialbe    can be changed.
              A lvalue is a modifiable lvalue if:
                - it has no array type
                - it has no incomplete type
                - it has no$const$type
                - it has struct or union type and no$const$member

                                                                *crv-gloMacro*
Macro         An identifier that is equated to a text or symbolic expression 
              to which it is to be expanded by the preprocessor.

                                                               *crv-gloObject*
Object        An area of memory used by a variable, the contents represents
              values.

                                                              *crv-gloOperand*
Operand       Parameter of an operator.
              Example:
               $a = b * c$

               $*$is the operator, $a$and$b$are the operands
               $b * c$is an expression

                                                             *crv-gloOperator*
Operator      An operator is used with operands to build an expression.
              Example:
               $a = b * c$

               $*$is the operator, $a$and$b$are the operands
               $b * c$is an expression

              An operator with two operands is called binary *crv-gloOpBinary*
                e.g. *, /, +, ...
              An operator with one operand is called unary.   *crv-gloOpUnary*
                e.g. - (sign), ++, --, ....

                                                            *crv-gloParameter*
Parameter     A parameter is the value that is passed to a function or macro.
              In principle there are two ways parameters can be passed:
                - By Value
                    This means that the function/macro works with a copy of
                    the parameter. Thus the value of the parameter can be
                    changed within the function/macro, but from caller's
                    view the parameter will keep its original value.
                - By Reference
                    This means that the function/macro works with the 
                    original parameter. Thus a caller of a function/macro
                    will "see" changes done to the parameter within
                    the function/macro.
              C always uses pass by value. Use pointers to simulate a pass
              by reference.

                                                              *crv-gloPointer*
Pointer       A variable that contains the address of a C element (variable, 
              structure, function) or memory area.

                                                         *crv-gloPreprocessor*
Preprocessor  A preprocessor is the first pass of a compiler. It does:
                - read include files 
                - expand macros
                - replace defines by their contents
                - pass control directives to the compiler

                                                              *crv-gloPromote*
Promote       Promoting is a type cast from a "lower" type to a "higher" 
              type, e.g. from int to long. 

                                                             *crv-gloPrototype*
Prototype     A function prototype is a declaration of a function that declares
              the types of its parameters.

                                                               *crv-gloRvalue*
rvalue        A rvalue is the value of an expression.
              See also lvalue |crv-gloLvalue|.

                                                                *crv-gloScope*
Scope         Scope is the visibility of a C element (variable, function)
              within a program. The scope are the sections of a program where
              an element can be referenced by name. The scope of an element 
              may be limited to file, function or block.
              The scope of an element is determined from where it is defined.
              If it is defined outside of a block, it has file scope.
              If it is defined within a function prototype, it has function 
              scope.
              If it is defined within a block, it has block scope.
              
                                                            *crv-gloSemantics*
Semantics     The relationships between symbols and their meanings.

                                                           *crv-gloSideEffect*
Side-Effect   During evaluation of an expression the value of a variable is
              changed. Example:
>
                b = (a = 2) * (a *= 3)
<
              NOTE: To keep a program maintainable and readable don't use
                    side-effects.

                                                        *crv-gloSignExtension*
Sign-         Sign-extension is the filling of the left most bits with the
Extension     state of the sign-bit when shifting right or when promoting.

                                                            *crv-gloStatement*
Statement     A statement is an expression followed by a semicolon.
              see |crv-gloExpression|

                                                            *crv-gloStructure*
Structure     A set of elements that have possibly different data types. A
              structure groups them together.

                                                               *crv-gloSyntax*
Syntax        A syntax describes the structure and order of the elements
              of a language statement. In other words: it specifies how words 
              and symbols are put together to form a program.

              Example for Syntax versus Semantics:
              The syntax rules of a human language could be:
                - each word must be build with the characters a-z or A-Z
                - words are separated by at least one space (" ").
                - words must start either with an upper or lower character,
                  the following characters must be lower ones
                - a sentence consists of words
                - the first word of a sentence must start with an upper
                  character, the others with a lower one
                - a sentence ends with a point (.)

              Following these rules, this would be a valid sentence:
                "The weather is fine today."
                
              But this one would also be a syntactically correct 
              sentence:
                "Thkds sdfasd ksdf dsf dfklsflsd."

              The semantics of a language connects words with meanings.
              Thus the second sentence is a semantically incorrect sentence.

              So a language is defined by its semantics AND syntax.
              The syntax defines how to form words and the semantics gives
              words a meaning.

                                                                *crv-gloToken*
Token         Tokens are the minimal lexical elements of a programming 
              language. A token can be a keyword, an identifier, a constant,
              a string literal, an operator or a punctuator.

                                                            *crv-gloTrueFalse*
True / False  In standard C an expression is FALSE if its value is 0, else 
              it is TRUE. The value of a logical TRUE is implementation
              specific.
              So never do something like
                $if (IsWindowOpen() == TRUE)$
              instead of this do
                $if (IsWindowOpen())$
              or
                $if (IsWindowOpen() != FALSE)$

                                                                 *crv-gloType*
Type          The meaning of a value stored in an object or returned by a 
              function is determined by its type.
              
                                                       *crv-gloTypeIncomplete*
Type,         An incomplete type describes an object but lacks information to
incomplete    determine its size.
              E.g. an array type of unknown size is an incomplete type.

                                                             *crv-gloTypeCast*
Type Cast     A type cast is an operation in which an operand of one type is
              converted to another type. In C the cast operator 
              is$(type-name)$.
              Example:
>
              int main(void)
              {
                int   nVar = 42;
                float fVar;

                fVar = (float)nVar;
              }
<
                                                                *crv-gloUnary*
Unary        see Operator |crv-gloOperator|

                                                             *crv-gloVariable*
Variable     Is the symbolic representation of a memory area.

                                                           *crv-gloWhiteSpace*
White-Space  A space, tab, carriage return, new line, vertical tab, or
             formfeed character.



==============================================================================
Appendix B  BIBLIOGRAPHY                                    *crv-bibliography*

[1]  "Erfolgreich programmieren mit C", 1. Auflage, 1985
     J. Anton Illik
     SYBEX Verlag GmbH, Duesseldorf (Germany)
     
[2]  "Softwareentwicklung in C", 3. September 2001
     Klaus Schmaranz
     Springer Verlag

[3]  "The GNU C Library Reference Manual", for Version 2.2.x of the GNU C
     Library, Edition 0.10, last updated 2001-07-06
     Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002
     Free Software Foundation, Inc.

[4]  ISO/IEC 9899:1999(E)
     International Standard
     Programming languages - C
     Published by American National Standards Institute



==============================================================================
For Appendix C  COPYRIGHT & LICENSES  go to |crvdoc-copyright|


==============================================================================
For Appendix D  AUTHOR  go to |crvdoc-author|


==============================================================================
For Appendix E  CREDITS  go to |crvdoc-credits|


==============================================================================
For Appendix F  HISTORY  go to |crvdoc-history|



------------------------------------------------------------------------------
 vim:tw=78:ts=4:ft=help:norl: