diff options
Diffstat (limited to '.vim/doc/crefvim.txt')
| -rwxr-xr-x | .vim/doc/crefvim.txt | 14112 |
1 files changed, 14112 insertions, 0 deletions
diff --git a/.vim/doc/crefvim.txt b/.vim/doc/crefvim.txt new file mode 100755 index 0000000..8fea502 --- /dev/null +++ b/.vim/doc/crefvim.txt @@ -0,0 +1,14112 @@ +*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 +∞. + + +FE_DOWNWARD Macro *crv-FE_DOWNWARD* +----------------- +Round toward -∞. + + +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/-∞. 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 ∞. +If x is zero,$logb()$returns ∞. 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 ∞ 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 ∞ 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 ∞, 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: |