*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 Diagnostics......|crv-libAssertH| II.3 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 Character.........|crv-libCtypeH| II.4.1 Character Handling........|crv-libCharHandling| II.4.2 Character Mapping.........|crv-libCharMapping| II.5 Error Codes.......|crv-libErrnoH| II.6 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 Floating Point....|crv-libFloatH| II.8 Absolute Value.|crv-libInttypesH| II.9 Alternatives.....|crv-libIso646H| II.10 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 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 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 Nonlocal Jumps...|crv-libSetjmpH| II.14 Signal Handling..|crv-libSignalH| II.14.1 Types.....................|crv-libSHTyp| II.14.2 Signals...................|crv-libSHSig| II.14.3 Functions.................|crv-libSHFunc| II.15 Arguments........|crv-libStdargH| II.16 Boolean Type....|crv-libStdboolH| II.17 Definitions......|crv-libStddefH| II.18 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 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 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...........|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 Type-Generic.....|crv-libTgmathH| II.23 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 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 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 | | \ | | 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 ------------+------------------------+--------------------------------------- $ < > $| | 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"}; 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'}; 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$$can be used to access arguments. Example: > #include #include 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 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 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 #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 --------------+----------------------------------------------------------- $ $| diagnostics.............................|crv-libAssertH| $ $| complex arithmetic......................|crv-libComplexH| $ $| character handling......................|crv-libCtypeH| $ $| error codes.............................|crv-libErrnoH| $ $| floating point environment..............|crv-libFenvH| $ $| characteristics of floating point types.|crv-libFloatH| $$| format conversion of integer types......|crv-libInttypesH| $ $| alternative spelling....................|crv-libIso646H| $ $| sizes of integer types..................|crv-libLimitsH| $ $| localization............................|crv-libLocalH| $ $| mathematics.............................|crv-libMathH| $ $| nonlocal jumps..........................|crv-libSetjmpH| $ $| signal handling.........................|crv-libSignalH| $ $| variable arguments......................|crv-libStdargH| $ $| boolean type and values.................|crv-libStdboolH| $ $| common definitions......................|crv-libStddefH| $ $| integer types...........................|crv-libStdintH| $ $| input / output..........................|crv-libStdioH| $ $| general utilities.......................|crv-libStdlibH| $ $| string handling.........................|crv-libStringH| $ $| type-generic math.......................|crv-libTgmathH| $ $| date and time...........................|crv-libTimeH| $ $| extended multibyte and wide.............|crv-libWcharH| | character utilities $ $| wide character classification and.......|crv-libWctypeH| | mapping utilities ============================================================================== II.2 Diagnostics *crv-libAssertH* Quicklink: $assert()$ Macro |crv-assert| $NDEBUG$ Macro |crv-NDEBUG| assert() Macro *crv-assert* *crv-NDEBUG* -------------- Synopsis~ $#include $ $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()$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 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 $ $#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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 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 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 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 $ $#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 $ $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 $ $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 $ $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 $ $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 $ $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|. $$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 $ $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 $ $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 $$. Its size and contents are implementation-defined. This variable should not be manipulated directly. fegetenv() Function *crv-fegetenv* ------------------- Synopsis~ $#include $ $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 $ $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 $ $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 $ $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 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 Absolute Value *crv-libInttypesH* This header extends the$$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 $$. For each type declared in$$, 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$.$ 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 #include 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 $ $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 $ $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 $ $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 $ $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 // for wchar_t$ $#include $ $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 // for wchar_t$ $#include $ $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 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 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 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 $ $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 $ $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 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$$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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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$$. 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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 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 $ $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 $ $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 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 $ $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 $ $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 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 $ $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 $ $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 $ $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 $ $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 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 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$$, see |crv-size_t2|. Also declared in$$, see |crv-size_t3|. Also declared in$$, see |crv-size_t4|. Also declared in$$, see |crv-size_t5|; Also declared in$$, 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$$, see |crv-libwchar_t2|. Also declared in$$, see |crv-libwchar_t3|. NULL Macro *crv-NULL* ---------- Expands to an implementation-defined null pointer constant. Also defined in$$, see |crv-NULL2|. Also defined in$$, see |crv-NULL3|. Also defined in$$, see |crv-NULL4|. Also defined in$$, see |crv-NULL5|. Also defined in$$, see |crv-NULL6|. offsetof() Macro *crv-offsetof* ---------------- Synopsis~ $#include $ $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 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$$. They are defined only if$__STDC_LIMIT_MACROS$is defined before including$$. 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$$, 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 $ $INTMAX_C(val);$ Description~ expands to an integer constant value$val$of type$intmax_t$ UINTMAX_C() Macro *crv-UINTMAX_C* ----------------- Synopsis~ $#include $ $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 $ $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 $ $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 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$$, see |crv-size_t|. Also declared in$$, see |crv-size_t2|. Also declared in$$, see |crv-size_t3|. Also declared in$$, see |crv-size_t4|. Also declared in$$, 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$$, see |crv-libNULL|. Also defined in$$, see |crv-libNULL2|. Also defined in$$, see |crv-libNULL3|. Also defined in$$, see |crv-libNULL4|. Also defined in$$, 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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $#include $ $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 $ $#include $ $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 $ $#include $ $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 $ $#include $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 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$$, see |crv-libsize_t|. Also declared in$$, see |crv-libsize_t3|. Also declared in$$, see |crv-libsize_t4|. Also declared in$$, see |crv-libsize_t5|. Also declared in$$, 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$$, see |crv-libwchar_t|. Also declared in$$, 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$$, see |crv-NULL|. Also defined in$$, see |crv-NULL3|. Also defined in$$, see |crv-NULL4|. Also defined in$$, see |crv-NULL5|. Also defined in$$, 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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $int abs(int number);$ Return~ absolute value Description~ Evaluates the absolute value of$number$. labs() Function *crv-labs* --------------- Synopsis~ $#include $ $long int labs(long int number);$ Return~ absolute value Description~ Evaluates the absolute value of$number$. llabs() Function *crv-llabs* ---------------- Synopsis~ $#include $ $long long int labs(long long int number);$ Return~ absolute value Description~ Evaluates the absolute value of$number$. div() Function *crv-div* -------------- Synopsis~ $#include $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 *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$$, see |crv-size_t|. Also declared in$$, see |crv-size_t2|. Also declared in$$, see |crv-size_t4|. Also declared in$$, see |crv-size_t5|. Also declared in$$, 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$$, see |crv-NULL|. Also defined in$$, see |crv-NULL2|. Also defined in$$, see |crv-NULL4|. Also defined in$$, see |crv-NULL5|. Also defined in$$, 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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 Type-Generic *crv-libTgmathH* This header file includes$$and$$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$$and$$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$$which has no suffix and for which there is a corresponding function in$$with prefix c, a type-generic macro is defined for both functions that has the name of the function declared in$$. 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 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$$, see |crv-size_t|. Also declared in$$, see |crv-size_t2|. Also declared in$$, see |crv-size_t3|. Also declared in$$, see |crv-size_t5|. Also declared in$$, 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$$, 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$$, see |crv-NULL|. Also defined in$$, see |crv-NULL2|. Also defined in$$, see |crv-NULL3|. Also defined in$$, see |crv-NULL5|. Also defined in$$, 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 $ $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 $ $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_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_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 $ $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 $ $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 $ $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 $ $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 $ $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 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$$, 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$$, see |crv-size_t|. Also declared in$$, see |crv-size_t2|. Also declared in$$, see |crv-size_t3|. Also declared in$$, see |crv-size_t4|. Also declared in$$, 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$$, see |crv-wchar_t|. Also declared in$$, 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$$, 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$$, see |crv-NULL|. Also defined in$$, see |crv-NULL2|. Also defined in$$, see |crv-NULL3|. Also defined in$$, see |crv-NULL4|. Also defined in$$, 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$$, 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$$, 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 $ $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 $ $#include $ $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 $ $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 $ $#include $ $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 $ $#include $ $#include $ $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 $ $#include $ $#include $ $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 $ $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 $ $#include $ $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 $ $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 $ $#include $ $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 $ $#include $ $#include $ $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 $ $#include $ $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 $ $#include $ $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 $ $#include $ $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 $ $#include $ $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 $ $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 $ $#include $ $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 $ $#include $ $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 $ $#include $ $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 $ $#include $ $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 $ $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 $ $#include $ $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 $ $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 $ $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_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_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_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_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_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_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 $ $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 $ $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 $ $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 $ $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 $ $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_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 $ $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_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_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 $ $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_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_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_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 $ $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_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 $ $#include $ $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 $ $#include $ $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 $ $#include $ $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 $ $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 $ $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 $ $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 $ $#include $ $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 $ $#include $ $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 $ $#include $ $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 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$$, 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$$, 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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $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 $ $int iswlower(wint_t wc);$ Description~ Returns true if$wc$is a lower-case letter. iswprint() Function *crv-iswprint* ------------------- Synopsis~ $#include $ $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 $ $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 $ $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 $ $int iswupper(wint_t wc);$ Description~ Returns true if$wc$is an upper-case letter. iswxdigit() Function *crv-iswxdigit* -------------------- Synopsis~ $#include $ $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 $ $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_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 $ $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 $ $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 $ $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 $ $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: