14113 lines
469 KiB
Plaintext
14113 lines
469 KiB
Plaintext
*crefvim.txt* C-Reference Manual for Vim
|
|
Vim version 6.0
|
|
|
|
|
|
*crefvim* *C-Reference*
|
|
C-Reference for Vim
|
|
======================
|
|
Version 1.0.3
|
|
27. Nov. 2004
|
|
|
|
(c) 2002-2004 by Christian Habermann
|
|
christian (at) habermann-net (point) de
|
|
|
|
|
|
"The GNU C Library Reference Manual" is
|
|
copyright (c) 1993 - 2002 by the
|
|
Free Software Foundation, Inc.
|
|
|
|
|
|
See |crefvimdoc| for further information on the project CRefVim.
|
|
See |crvdoc-copyright| for copyright and licenses.
|
|
|
|
|
|
Table of C o n t e n t s:
|
|
|
|
Introduction..................|crv-intro|
|
|
|
|
Chapter I LANGUAGE......................|crv-language|
|
|
I.1 Characters..................|crv-lngChar|
|
|
I.1.1 Allowed Characters........|crv-lngAllowedChar|
|
|
I.1.2 Comment...................|crv-lngComment|
|
|
I.1.3 Escape-Sequences..........|crv-lngEscSeq|
|
|
|
|
I.2 Keywords....................|crv-keywords|
|
|
|
|
I.3 Operators...................|crv-operators|
|
|
I.3.1 Overview..................|crv-opOverview|
|
|
I.3.2 Arithmetic................|crv-opArithmetic|
|
|
I.3.3 Logical...................|crv-opLogical|
|
|
I.3.4 Relational................|crv-opRelational|
|
|
I.3.5 Bitwise...................|crv-opBitwise|
|
|
I.3.6 Assignments...............|crv-opAssigns|
|
|
I.3.7 Others....................|crv-opOthers|
|
|
I.3.7.1 Size of.................|crv-opSizeOf|
|
|
I.3.7.2 Address of..............|crv-opAddress|
|
|
I.3.7.3 Contents of.............|crv-opContents|
|
|
I.3.7.4 Conditional.............|crv-opConditional|
|
|
I.3.7.5 Series..................|crv-opSeries|
|
|
I.3.7.6 Type Cast...............|crv-opTypeCast|
|
|
I.3.7.7 Struct/Union Selectors..|crv-opStructUnionSel|
|
|
I.3.7.8 Array Selector..........|crv-opArraySel|
|
|
I.3.7.9 Parentheses.............|crv-opParenth|
|
|
I.3.8 Precedence................|crv-opPrecedence|
|
|
|
|
I.4 Punctuators.................|crv-punctuators|
|
|
|
|
I.5 Datatypes...................|crv-datatypes|
|
|
I.5.1 Overview..................|crv-dtOverview|
|
|
I.5.1.1 Type Specifiers.........|crv-dtTypeSpecifiers|
|
|
I.5.1.2 Type Grouping...........|crv-dtTypeGrouping|
|
|
I.5.2 Sizes and Ranges..........|crv-dtSizeRange|
|
|
I.5.2 Formats...................|crv-dtFormats|
|
|
I.5.2.1 Integer.................|crv-dtFormatsInt|
|
|
I.5.2.2 Floating-Point..........|crv-dtFormatsFloat|
|
|
I.5.2.2.1 Basics................|crv-dtFormatsFPBasics|
|
|
I.5.2.2.2 Types.................|crv-dtFormatsFPTypes|
|
|
I.5.3 void Type.................|crv-dtVoid|
|
|
I.5.4 Arrays....................|crv-dtArrays|
|
|
I.5.5 Structures................|crv-dtStructurs|
|
|
I.5.6 Unions....................|crv-dtUnions|
|
|
I.5.7 Bit-Fields................|crv-dtBitFields|
|
|
I.5.8 Enumerated Tags...........|crv-dtEnumerate|
|
|
I.5.9 Strings...................|crv-dtStrings|
|
|
I.5.10 Type Definitions..........|crv-dtTypeDef|
|
|
I.5.11 Storage Classes...........|crv-dtStorageClasses|
|
|
I.5.12 Qualifiers................|crv-dtQualifiers|
|
|
I.5.13 Pointers..................|crv-dtPointers|
|
|
I.5.13.1 Variables...............|crv-dtPtrVars|
|
|
I.5.13.2 Functions...............|crv-dtPtrFuncs|
|
|
I.5.13.3 Arithmetics.............|crv-dtPtrArithmetics|
|
|
I.5.14 Type Cast.................|crv-dtTypeCast|
|
|
I.5.14.1 Explicit................|crv-dtTypeCastExpl|
|
|
I.5.14.2 Implicit................|crv-dtTypeCastImpl|
|
|
I.5.15 Constants.................|crv-dtConstants|
|
|
I.5.15.1 Integer.................|crv-dtConstInt|
|
|
I.5.15.2 Floating-Point..........|crv-dtConstFloat|
|
|
I.5.15.3 Character...............|crv-dtConstChar|
|
|
|
|
I.6 Statements..................|crv-statements|
|
|
I.6.1 if-else...................|crv-stIfElse|
|
|
I.6.2 switch....................|crv-stSwitch|
|
|
I.6.3 while Loop................|crv-stWhile|
|
|
I.6.4 do-while Loop.............|crv-stDoWhile|
|
|
I.6.5 for Loop..................|crv-stFor|
|
|
I.6.6 break.....................|crv-stBreak|
|
|
I.6.7 continue..................|crv-stContinue|
|
|
I.6.8 goto......................|crv-stGoto|
|
|
I.6.9 return....................|crv-stReturn|
|
|
I.6.10 Null Statement............|crv-stNull|
|
|
|
|
I.7 Functions...................|crv-functions|
|
|
I.7.1 Definition................|crv-fuDefinition|
|
|
I.7.2 Protoype..................|crv-fuPrototype|
|
|
I.7.3 Conversion................|crv-fuConversion|
|
|
I.7.4 Storage Classes...........|crv-fuStorageClasses|
|
|
I.7.5 Specifier.................|crv-fuSpecifier|
|
|
I.7.6 main()....................|crv-fuMain|
|
|
|
|
I.8 Preprocessor................|crv-preprocessor|
|
|
I.8.1 Macros....................|crv-preMacros|
|
|
I.8.1.1 Definition #define......|crv-preMacDef|
|
|
I.8.1.2 Cancellation #undef.....|crv-preMacCancel|
|
|
I.8.1.3 # Operator..............|crv-preMac#Operator|
|
|
I.8.1.4 ## Operator.............|crv-preMac##Operator|
|
|
I.8.1.5 Predefined Macros.......|crv-preMacPredefined|
|
|
I.8.2 Conditional Compilation...|crv-preConditional|
|
|
I.8.2.1 defined Operator........|crv-preCondDefined|
|
|
I.8.2.2 #if Directive...........|crv-preCondIf|
|
|
I.8.2.3 #ifdef Directive........|crv-preCondIfdef|
|
|
I.8.2.4 #ifndef Directive.......|crv-preCondIfndef|
|
|
I.8.2.5 #else Directive.........|crv-preCondElse|
|
|
I.8.2.6 #elif Directive.........|crv-preCondElif|
|
|
I.8.2.7 #endif Directive........|crv-preCondEndif|
|
|
I.8.3 File Inclusion #include...|crv-preSourceInc|
|
|
I.8.4 Line Control #line........|crv-preLine|
|
|
I.8.5 Error Directive #error....|crv-preError|
|
|
I.8.6 Pragma Directive #pragma..|crv-prePragma|
|
|
I.8.7 Null Directive #..........|crv-preNull|
|
|
|
|
|
|
Chapter II STANDARD C LIBRARY............|crv-stdCLib|
|
|
II.1 Standard Headers............|crv-libHeaders|
|
|
|
|
II.2 <assert.h> Diagnostics......|crv-libAssertH|
|
|
|
|
II.3 <complex.h> Complex Math....|crv-libComplexH|
|
|
II.3.1 Macros....................|crv-libCHMac|
|
|
II.3.2 Pragmas...................|crv-libCHPrag|
|
|
II.3.3 Trigonometric.............|crv-libCHTrig|
|
|
II.3.4 Hyperbolic................|crv-libCHHyper|
|
|
II.3.5 Exponential & Logarithmic.|crv-libCHExpLog|
|
|
II.3.6 Power & Absolute..........|crv-libCHPower|
|
|
II.3.7 Manipulating..............|crv-libCHMani|
|
|
|
|
II.4 <ctype.h> Character.........|crv-libCtypeH|
|
|
II.4.1 Character Handling........|crv-libCharHandling|
|
|
II.4.2 Character Mapping.........|crv-libCharMapping|
|
|
|
|
II.5 <errno.h> Error Codes.......|crv-libErrnoH|
|
|
|
|
II.6 <fenv.h> FPU Status.........|crv-libFenvH|
|
|
II.6.1 Pragmas...................|crv-libFHPrag|
|
|
II.6.2 Exceptions................|crv-libFHExceptions|
|
|
II.6.3 Rounding..................|crv-libFHRounding|
|
|
II.6.4 Environment...............|crv-libFHEnv|
|
|
|
|
II.7 <float.h> Floating Point....|crv-libFloatH|
|
|
|
|
II.8 <inttypes.h> Absolute Value.|crv-libInttypesH|
|
|
|
|
II.9 <iso646.h> Alternatives.....|crv-libIso646H|
|
|
|
|
II.10 <limits.h> Limits of Int....|crv-libLimitsH|
|
|
II.10.1 Range of Integer Types....|crv-libLHRange|
|
|
II.10.2 Width of Type.............|crv-libLHWidth|
|
|
II.10.3 Conversion and Properties.|crv-libLHConv|
|
|
|
|
II.11 <local.h> Localization......|crv-libLocalH|
|
|
II.11.1 Categories................|crv-libLocHCat|
|
|
II.11.2 Standard Locales..........|crv-libLocHLoc|
|
|
II.11.3 Information Structure.....|crv-libLocHInfo|
|
|
II.11.4 Functions.................|crv-libLocHFunc|
|
|
|
|
II.12 <math.h> Mathematics........|crv-libMathH|
|
|
II.12.1 Error Conditions..........|crv-libMHErr|
|
|
II.12.2 Classification Macros.....|crv-libMHClass|
|
|
II.12.3 Comparison Macros.........|crv-libMHCmp|
|
|
II.12.4 Trigonometric.............|crv-libMHTrig|
|
|
II.12.5 Hyperbolic................|crv-libMHHyper|
|
|
II.12.6 Exponential & Logarithmic.|crv-libMHExpLog|
|
|
II.12.7 Power & Absolute..........|crv-libMHPower|
|
|
II.12.8 Error & Gamma.............|crv-libMHErrGam|
|
|
II.12.9 Nearest Integer...........|crv-libMHNear|
|
|
II.12.10 Remainder.................|crv-libMHRem|
|
|
II.12.11 Manipulating..............|crv-libMHMani|
|
|
II.12.12 Miscellaneous.............|crv-libMHMisc|
|
|
|
|
II.13 <setjmp.h> Nonlocal Jumps...|crv-libSetjmpH|
|
|
|
|
II.14 <signal.h> Signal Handling..|crv-libSignalH|
|
|
II.14.1 Types.....................|crv-libSHTyp|
|
|
II.14.2 Signals...................|crv-libSHSig|
|
|
II.14.3 Functions.................|crv-libSHFunc|
|
|
|
|
II.15 <stdarg.h> Arguments........|crv-libStdargH|
|
|
|
|
II.16 <stdbool.h> Boolean Type....|crv-libStdboolH|
|
|
|
|
II.17 <stddef.h> Definitions......|crv-libStddefH|
|
|
|
|
II.18 <stdint.h> Integer Type.....|crv-libStdintH|
|
|
II.18.1 Integer Types.............|crv-libSdHType|
|
|
II.18.1.1 Exact-Width.............|crv-libSdHTExact|
|
|
II.18.1.2 Minimum-Width...........|crv-libSdHTMin|
|
|
II.18.1.3 Fastest Minimum-Width...|crv-libSdHTFast|
|
|
II.18.1.4 Greatest-Width..........|crv-libSdHTGreat|
|
|
II.18.1.5 Hold Pointer............|crv-libSdHTPtr|
|
|
II.18.2 Limits....................|crv-libSdHTLim|
|
|
II.18.2.1 Exact-Width.............|crv-libSdHLExact|
|
|
II.18.2.2 Minimum-Width...........|crv-libSdHLMin|
|
|
II.18.2.3 Fastest Minimum-Width...|crv-libSdHLFast|
|
|
II.18.2.4 Greatest-Width..........|crv-libSdHLGreat|
|
|
II.18.2.5 Others..................|crv-libSdHLOther|
|
|
II.18.2.6 Hold Pointer............|crv-libSdHLPtr|
|
|
II.18.3 Macros....................|crv-libSdHMac|
|
|
|
|
II.19 <stdio.h> Input/Output......|crv-libStdioH|
|
|
II.19.1 Types.....................|crv-libSIOHType|
|
|
II.19.2 Macros....................|crv-libSIOHMac|
|
|
II.19.3 Streams and Files.........|crv-libSIOHStrmFile|
|
|
II.19.4 File Operations...........|crv-libSIOHFOp|
|
|
II.19.5 File Access...............|crv-libSIOHFAcc|
|
|
II.19.6 Formatted Input/Output....|crv-libSIOHIO|
|
|
II.19.6.1 Format Control..........|crv-libSIOHIOFormat|
|
|
II.19.6.1.1 Output, printf()......|crv-libSIOHIOFout|
|
|
II.19.6.1.2 Input, scanf()........|crv-libSIOHIOFin|
|
|
II.19.6.2 Functions...............|crv-libSIOHIOFunc|
|
|
II.19.7 Character Input/Output....|crv-libSIOHCIO|
|
|
II.19.8 Direct Input/Output.......|crv-libSIOHDIO|
|
|
II.19.9 File Positioning..........|crv-libSIOHFPos|
|
|
II.19.10 Error Handling............|crv-libSIOHErr|
|
|
|
|
II.20 <stdlib.h> Utilities........|crv-libStdlibH|
|
|
II.20.1 Types.....................|crv-libSLHType|
|
|
II.20.2 Macros....................|crv-libSLHMac|
|
|
II.20.3 Numeric Conversion........|crv-libSLHnum|
|
|
II.20.4 Pseudo-Random.............|crv-libSLHrand|
|
|
II.20.5 Memory Management.........|crv-libSLHmem|
|
|
II.20.6 Communication.............|crv-libSLHcom|
|
|
II.20.7 Searching and Sorting.....|crv-libSLHsearch|
|
|
II.20.8 Integer Arithmetic........|crv-libSLHintarith|
|
|
II.20.9 Multibyte/Wide Character..|crv-libSLHmulchar|
|
|
II.20.10 Multibyte/Wide String.....|crv-libSLHmulstrng|
|
|
|
|
II.21 <string.h> String...........|crv-libStringH|
|
|
II.21.1 Types.....................|crv-libSRHType|
|
|
II.21.2 Macros....................|crv-libSRHMac|
|
|
II.21.3 Copying...................|crv-libSRHCopy|
|
|
II.21.4 Concatenation.............|crv-libSRHConcat|
|
|
II.21.5 Comparison................|crv-libSRHCmp|
|
|
II.21.6 Search....................|crv-libSRHSearch|
|
|
II.21.7 Miscellaneous.............|crv-libSRHMisc|
|
|
|
|
II.22 <tgmath.h> Type-Generic.....|crv-libTgmathH|
|
|
|
|
II.23 <time.h> Date and Time......|crv-libTimeH|
|
|
II.23.1 Types.....................|crv-libTHType|
|
|
II.23.2 Macros....................|crv-libTHMac|
|
|
II.23.3 Time Manipulation.........|crv-libTHMani|
|
|
II.23.4 Time Conversion...........|crv-libTHConv|
|
|
|
|
II.24 <wchar.h> Wide Utilities....|crv-libWcharH|
|
|
II.24.1 Types.....................|crv-libWCHType|
|
|
II.24.2 Macros....................|crv-libWCHMac|
|
|
II.24.3 Formatted Input/Output....|crv-libWCHIO|
|
|
II.24.4 Character Input/Output....|crv-libWCHCIO|
|
|
II.24.5 String Utilities..........|crv-libWCHStrng|
|
|
II.24.5.1 Numeric Conversions.....|crv-libWCHNum|
|
|
II.24.5.2 Copying.................|crv-libWCHCopy|
|
|
II.24.5.3 Concatenation...........|crv-libWCHConcat|
|
|
II.24.5.4 Comparison..............|crv-libWCHCmp|
|
|
II.24.5.5 Search..................|crv-libWCHSearch|
|
|
II.24.5.6 Miscellaneous...........|crv-libWCHMisc|
|
|
II.24.6 Time Conversions..........|crv-libWCHTimeConv|
|
|
II.24.7 Character Conversions.....|crv-libWCHCharConv|
|
|
|
|
II.25 <wctype.h> Wide Character...|crv-libWctypeH|
|
|
II.25.1 Types.....................|crv-libWTHType|
|
|
II.25.2 Macros....................|crv-libWTHMac|
|
|
II.25.3 Classification............|crv-libWTHClass|
|
|
II.25.3.1 Wide Character..........|crv-libWTHCwide|
|
|
II.25.3.2 Extensible Wide Char....|crv-libWTHCextens|
|
|
II.25.4 Mapping...................|crv-libWTHMap|
|
|
II.25.4.1 Wide Character..........|crv-libWTHMwide|
|
|
II.25.4.2 Extensible Wide Char....|crv-libWTHMextens|
|
|
|
|
|
|
Appendix A GLOSSARY............................|crv-glossary|
|
|
B BIBLIOGRAPHY........................|crv-bibliography|
|
|
C COPYRIGHT & LICENSES................|crvdoc-copyright|
|
|
C.1 GNU General Public License........|crvdoc-licGPL|
|
|
C.2 GNU Free Documentation License....|crvdoc-licFDL|
|
|
C.3 GNU Lesser General Public License.|crvdoc-licLGPL|
|
|
C.4 Free Software Needs Free
|
|
Documentation.....................|crvdoc-licFreeDoc|
|
|
D AUTHOR..............................|crvdoc-author|
|
|
E CREDITS.............................|crvdoc-credits|
|
|
F HISTORY.............................|crvdoc-history|
|
|
|
|
|
|
Happy viming...
|
|
|
|
|
|
==============================================================================
|
|
Introduction *crv-intro*
|
|
==============================================================================
|
|
|
|
|
|
This document is a C-reference manual. It is NOT a tutorial on how to write
|
|
C programs. It is simply a quick reference to the standard C programming
|
|
language and its standard library functions.
|
|
The language description is based on the standard ISO/IEC 9899:1999(E), second
|
|
edition. But this reference does not contain all information from this
|
|
standard, it tries to reflect only the most important information.
|
|
|
|
DISCLAIMER: All efforts have been taken to make sure that all information
|
|
in this document is correct, but no guarantee is implied or
|
|
intended.
|
|
|
|
This C-reference manual is designed to be best viewed with Vim and syntax-
|
|
highlighting enabled. Furthermore when using Vim it's possible to navigate
|
|
through this document by tags. Vim is a very powerful text-editor available
|
|
for close to all platforms.
|
|
|
|
This C-reference is divided into two chapters and an appendix. The first
|
|
chapter deals mainly with the language. The second chapter shows the
|
|
functions of the standard C library. The appendix includes a glossary and
|
|
other items of interest.
|
|
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
Chapter I LANGUAGE *crv-language*
|
|
==============================================================================
|
|
|
|
|
|
|
|
==============================================================================
|
|
I.1 Characters *crv-lngChar*
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.1.1 Allowed Characters *crv-lngAllowedChar*
|
|
|
|
In a C source code the following characters are allowed:
|
|
|
|
Digits: 0...9
|
|
Letters: a-z A-Z
|
|
Others: ! " # & ' + - * / % , . : ; < = > ? \ ^ _ | ~
|
|
parentheses ( )
|
|
brackets [ ]
|
|
braces { }
|
|
space, tabulator, form feed
|
|
|
|
Trigraphs: ??= # ??) ] ??! | *crv-trigraph*
|
|
??( [ ??' ^ ??> }
|
|
??/ \ ??< { ??- ~
|
|
If a trigraph sequence is found in the source code it is
|
|
replaced with the corresponding single character. This allows
|
|
to enter some special symbols on platforms not providing these
|
|
symbols.
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.1.2 Comment *crv-lngComment*
|
|
|
|
There are two types of comments:
|
|
- block comment $/*...*/$
|
|
- line comment $//$
|
|
|
|
Block Comment: *crv-lngBlockComment*
|
|
A block comment starts with $/*$ and ends with $*/$. All characters between
|
|
start and end are treated as comment. Nesting is not allowed.
|
|
|
|
Line Comment: *crv-lngLineComment*
|
|
A line comment starts with $//$ and ends at the next new-line character
|
|
(new-line character is not included).
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.1.3 Escape-Sequences *crv-lngEscSeq*
|
|
|
|
|
|
Escape Sequence | Name | Meaning
|
|
----------------+-----------------+------------------------------------------
|
|
\' | | single quote '
|
|
\" | | double quote "
|
|
\? | | question mark ?
|
|
\\ | | backslash \
|
|
| |
|
|
\a | Alert | produces an audible or visible alert
|
|
\b | Backspace | moves cursor back one position
|
|
\f | Form Feed | moves cursor to start of next page
|
|
\n | New Line | moves cursor to start of next line
|
|
\r | Carriage Return | moves cursor to start of current line
|
|
\t | horiz. tabulator| moves cursor to next horiz. tab. position
|
|
\v | vert. tabulator | moves cursor to next vert. tab. position
|
|
| |
|
|
\0octal-digits | | octal character
|
|
\xhex-digits | | hexadecimal character
|
|
| |
|
|
\0 | null character | character with the value 0
|
|
| |
|
|
\<cr> | | concatenates actual line with next one
|
|
| | (backslash immediately followed by a
|
|
| | new-line)
|
|
|
|
|
|
|
|
==============================================================================
|
|
I.2 Keywords *crv-keywords*
|
|
|
|
Keywords are words with a special meaning in C. They must not be used for any
|
|
other purposes. Keywords are case sensitive.
|
|
|
|
|
|
Keyword | Description
|
|
---------------+----------------------------
|
|
$ auto $| storage-class specifier
|
|
$ break $| statement
|
|
$ case $| label
|
|
$ char $| type
|
|
$ const $| type qualifier
|
|
$ continue $| statement
|
|
$ default $| label
|
|
$ do $| statement
|
|
$ double $| type
|
|
$ else $| statement
|
|
$ enum $| type
|
|
$ extern $| storage-class specifier
|
|
$ float $| type
|
|
$ for $| statement
|
|
$ goto $| statement
|
|
$ if $| statement
|
|
$ inline $| function specifier
|
|
$ int $| type
|
|
$ long $| type
|
|
$ register $| storage-class specifier
|
|
$ restrict $| type qualifier
|
|
$ return $| statement
|
|
$ short $| type
|
|
$ signed $| type
|
|
$ sizeof $| operator
|
|
$ static $| storage-class specifier
|
|
$ struct $| specifier
|
|
$ switch $| statement
|
|
$ typedef $| declaration
|
|
$ union $| specifier
|
|
$ unsigned $| type
|
|
$ void $| type
|
|
$ volatile $| type qualifier
|
|
$ while $| statement
|
|
$ _Bool $| type
|
|
$ _Complex $| type
|
|
$ _Imaginary $| type
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
I.3 Operators *crv-operators*
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.3.1 Overview *crv-opOverview*
|
|
|
|
|
|
Operator | Usage | Description
|
|
--------------+-----------------+-------------------------------------------
|
|
| |
|
|
|crv-opArithmetic|
|
|
Arithmetic~
|
|
$ +$[unary] |$+operand $| positive sign, same like$operand$
|
|
$ -$[unary] |$-operand $| negation of$operand$
|
|
| |
|
|
$ +$[binary] |$expr1 + expr2 $| addition
|
|
$ -$[binary] |$expr1 - expr2 $| substraction
|
|
$ / $ |$expr1 / expr2 $| division
|
|
$ * $ |$expr1 * expr2 $| multiplication
|
|
$ % $ |$expr1 % expr2 $| modulo
|
|
$ --$[postfix] |$operand-- $|$operand$before decrementing by 1
|
|
$ --$[prefix] |$--operand $|$operand$after decrementing by 1
|
|
$ ++$[postfix] |$operand++ $|$operand$before incrementing by 1
|
|
$ ++$[prefix] |$++operand $|$operand$after incrementing by 1
|
|
| |
|
|
|crv-opLogical|
|
|
Logical~
|
|
$ && $ |$expr1 && expr2 $| logical AND
|
|
$ || $ |$expr1 || expr2 $| logical OR
|
|
$ ! $ |$!expr1 $| logical NOT
|
|
| |
|
|
|crv-opRelational|
|
|
Relational~
|
|
$ ==$ |$expr1 == expr2 $| compare for equal
|
|
$ !=$ |$expr1 != expr2 $| compare for not equal
|
|
$ > $ |$expr1 > expr2 $| compare for "greater than"
|
|
$ < $ |$expr1 < expr2 $| compare for "less than"
|
|
$ >=$ |$expr1 >= expr2 $| compare for "greater than or equal"
|
|
$ <=$ |$expr1 <= expr2 $| compare for "less than or equal"
|
|
| |
|
|
|crv-opBitwise|
|
|
Bitwise~
|
|
$ & $ |$expr1 & expr2 $| bitwise AND
|
|
$ | $ |$expr1 | expr2 $| bitwise OR
|
|
$ ^ $ |$expr1 ^ expr2 $| bitwise XOR
|
|
$ << $ |$expr1 << expr2 $| shift bits to left
|
|
$ >> $ |$expr1 >> expr2 $| shift bits to right
|
|
$ ~ $ |$~expr1 $| one's complement
|
|
| |
|
|
|crv-opAssigns|
|
|
Assignment~
|
|
$ = $ |$expr1 = expr2 $| assignment
|
|
$ *= $ |$expr1 *= expr2 $|$expr1 = expr1 * expr2 $
|
|
$ /= $ |$expr1 /= expr2 $|$expr1 = expr1 / expr2 $
|
|
$ %= $ |$expr1 %= expr2 $|$expr1 = expr1 % expr2 $
|
|
$ += $ |$expr1 += expr2 $|$expr1 = expr1 + expr2 $
|
|
$ -= $ |$expr1 -= expr2 $|$expr1 = expr1 - expr2 $
|
|
$ <<=$ |$expr1 <<= expr2$|$expr1 = expr1 << expr2 $
|
|
$ >>=$ |$expr1 >>= expr2$|$expr1 = expr1 >> expr2 $
|
|
$ &= $ |$expr1 &= expr2 $|$expr1 = expr1 & expr2 $
|
|
$ ^= $ |$expr1 ^= expr2 $|$expr1 = expr1 ^ expr2 $
|
|
$ |= $ |$expr1 |= expr2 $|$expr1 = expr1 | expr2 $
|
|
| |
|
|
|crv-opOthers|
|
|
Others~
|
|
$ sizeof $ |$sizeof a $| size of element$a$in bytes
|
|
$ & $ |$&expr1 $| address of$expr1$
|
|
$ * $ |$*expr1 $| contents of$expr1$, $expr1$is a pointer
|
|
$ ?: $ |$a?expr1:expr2 $| conditional operator$a!=0:expr1 else expr2$
|
|
$ , $ |$expr1,expr2 $| comma operator
|
|
$(type-name)$ |$(float)expr1 $| explicit type cast
|
|
$ . $ |$a.b $| struct/union selector,$a$is struct/union
|
|
$ -> $ |$a->b $| struct/union selector,$a$is pointer to
|
|
| | struct/union
|
|
$ [] $ |$a[0] $| array selector
|
|
$ () $ |$(a + b) * c $| group operators or
|
|
|$func() $| declare functions
|
|
| |
|
|
--------------+-----------------+-------------------------------------------
|
|
|
|
|
|
The sections below give further information on operators.
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.3.2 Arithmetic *crv-opArithmetic*
|
|
|
|
$+operand$ *crv-opPosSign*
|
|
----------
|
|
positive sign
|
|
|
|
Examples: >
|
|
a = +15;
|
|
a = +b;
|
|
func(3.12E+3);
|
|
|
|
|
|
$-operand$ *crv-opNegSign*
|
|
----------
|
|
negative sign, negation
|
|
|
|
Examples: >
|
|
a = -15;
|
|
a = -a;
|
|
|
|
|
|
$expr1 + expr2$ *crv-opAdd*
|
|
---------------
|
|
This adds the two expressions.
|
|
|
|
Examples: >
|
|
a = b + c;
|
|
a = b + 42;
|
|
a = func(b + c);
|
|
|
|
|
|
$expr1 - expr2$ *crv-opSub*
|
|
---------------
|
|
Substract$expr2$from$expr1$.
|
|
|
|
Examples: >
|
|
a = b - c;
|
|
a = b - 42;
|
|
a = func(b - c);
|
|
|
|
|
|
$expr1 / expr2$ *crv-opDivide*
|
|
---------------
|
|
Divide$expr1$by$expr2$.
|
|
If$expr2$is 0, behavior is undefined.
|
|
|
|
Examples: >
|
|
a = b / c;
|
|
a = b / 42;
|
|
a = func(c / 3);
|
|
|
|
|
|
$expr1 * expr2$ *crv-opMultiply*
|
|
---------------
|
|
Multiply$expr1$by$expr2$.
|
|
|
|
Examples: >
|
|
a = b * c;
|
|
a = b * 42;
|
|
a = func(c * 3);
|
|
|
|
|
|
$expr1 % expr2$ *crv-opModulo*
|
|
---------------
|
|
Modulo operator. The result is the value of the remainder after
|
|
dividing$expr1$by$expr2$.
|
|
Both expressions must be integer types (char, short, int, long...,
|
|
signed or unsigned).
|
|
If$expr2$is 0, behavior is undefined.
|
|
|
|
Examples: >
|
|
a = 0 % 3; // result = 0
|
|
a = 1 % 3; // result = 1
|
|
a = 2 % 3; // result = 2
|
|
a = 3 % 3; // result = 0
|
|
a = 4 % 3; // result = 1
|
|
a = 5 % 3; // result = 2
|
|
a = 6 % 3; // result = 0
|
|
a = 7 % 3; // result = 1
|
|
a = 7 % (-3); // result = 1
|
|
a = (-7) % 3; // result = -1
|
|
a = (-7) % (-3); // result = -1
|
|
|
|
a = b % c;
|
|
func(a % c);
|
|
|
|
|
|
$operand--$ *crv-opPostDec*
|
|
-----------
|
|
This is a postfix operation (unary operator after operand).
|
|
$operand$will be decremented by 1 AFTER the expression is
|
|
evaluated.
|
|
The value 1 of the appropriate type is subtracted.
|
|
So e.g. integer and float can be used as$operand$.
|
|
|
|
Example: >
|
|
int nA;
|
|
float fA;
|
|
|
|
nA = 3;
|
|
printf("%d", nA--); // output 3
|
|
printf("%d", nA); // output 2
|
|
|
|
fA = 3.2f;
|
|
fA--;
|
|
printf("%f", fA); // output 2.2
|
|
|
|
|
|
$--operand$ *crv-opPreDec*
|
|
-----------
|
|
This is a prefix operation (unary operator before operand).
|
|
$operand$will be decremented by 1 BEFORE the expression is
|
|
evaluated.
|
|
The value 1 of the appropriate type is subtracted.
|
|
So e.g. integer and float can be used as$operand$.
|
|
|
|
Example: >
|
|
int nA;
|
|
float fA;
|
|
|
|
nA = 3;
|
|
printf("%d", --nA); // output 2
|
|
printf("%d", nA); // output 2
|
|
|
|
fA = 3.2f;
|
|
--fA;
|
|
printf("%f", fA); // output 2.2
|
|
|
|
|
|
$operand++$ *crv-opPostInc*
|
|
-----------
|
|
This is a postfix operation (unary operator after operand).
|
|
$operand$will be incremented by 1 AFTER the expression is
|
|
evaluated.
|
|
The value 1 of the appropriate type is added. So e.g.
|
|
integer and float can be used as$operand$.
|
|
|
|
Example: >
|
|
int nA;
|
|
float fA;
|
|
|
|
nA = 3;
|
|
printf("%d", nA++); // output 3
|
|
printf("%d", nA); // output 4
|
|
|
|
fA = 3.2f;
|
|
fA++;
|
|
printf("%f", fA); // output 4.2
|
|
|
|
|
|
$++operand$ *crv-PreInc*
|
|
-----------
|
|
This is a prefix operation (unary operator before operand).
|
|
$operand$will be incremented by 1 BEFORE the expression is
|
|
evaluated.
|
|
The value 1 of the appropriate type is added. So e.g.
|
|
integer and float can be used as$operand$.
|
|
|
|
Example: >
|
|
int nA;
|
|
float fA;
|
|
|
|
nA = 3;
|
|
printf("%d", ++nA); // output 4
|
|
printf("%d", nA); // output 4
|
|
|
|
fA = 3.2f;
|
|
++fA;
|
|
printf("%f", fA); // output 4.2
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.3.3 Logical *crv-opLogical*
|
|
|
|
An expression is FALSE if its value is 0, else it is TRUE.
|
|
|
|
ATTENTION: This means TRUE is defined as unequal to 0. So never assume any
|
|
value for TRUE, TRUE's value depends on implementation.
|
|
|
|
|
|
$expr1 && expr2$ *crv-opLogAnd*
|
|
----------------
|
|
This is the logical AND.
|
|
The expression is TRUE if both$expr1$AND$expr2$are TRUE - else it is FALSE.
|
|
If$expr1$is equal 0,$expr2$is not evaluated.
|
|
The result has type$int$.
|
|
|
|
$expr1$|$expr2$ || result
|
|
--------+--------++--------
|
|
0 | 0 || 0
|
|
0 | >=1 || 0
|
|
>=1 | 0 || 0
|
|
>=1 | >=1 || >=1
|
|
|
|
|
|
$expr1 || expr2$ *crv-opLogOr*
|
|
----------------
|
|
This is the logical OR.
|
|
The expression is TRUE if either$expr1$OR$expr2$is TRUE - else it is FALSE.
|
|
If$expr1$is unequal 0,$expr2$is not evaluated.
|
|
The result has type$int$.
|
|
|
|
$expr1$|$expr2$ || result
|
|
--------+--------++--------
|
|
0 | 0 || 0
|
|
0 | >=1 || >=1
|
|
>=1 | 0 || >=1
|
|
>=1 | >=1 || >=1
|
|
|
|
|
|
$!expr1$ *crv-opLogNot*
|
|
--------
|
|
This is the logical NOT.
|
|
The expression is TRUE if$expr1$is FALSE. The expression is FALSE if$expr1$is
|
|
TRUE.
|
|
The result has type$int$.
|
|
|
|
$expr1$|| result
|
|
------++--------
|
|
0 || >=1
|
|
>=1 || 0
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.3.4 Relational *crv-opRelational*
|
|
|
|
$expr1 == expr2$ *crv-opRelEqual*
|
|
----------------
|
|
Equality operator. The result is 1 if operands are equal. The result is
|
|
0 if operands are unequal.
|
|
The result has type$int$.
|
|
|
|
Example: >
|
|
int x, a, b;
|
|
|
|
a = 1;
|
|
b = 2;
|
|
|
|
if (a == 1)
|
|
{
|
|
printf("a is equal to 1");
|
|
}
|
|
|
|
x = a == b;
|
|
printf("%d", x); // output is 0, since a != b
|
|
|
|
|
|
$expr1 != expr2$ *crv-opRelUnequal*
|
|
----------------
|
|
Unequality operator. The result is 1 if operands are unequal. The result is
|
|
0 if operands are equal.
|
|
The result has type$int$.
|
|
|
|
Example: >
|
|
int x, a, b;
|
|
|
|
a = 1;
|
|
b = 2;
|
|
|
|
if (a != b)
|
|
{
|
|
printf("a is unequal to b");
|
|
}
|
|
|
|
x = a != b;
|
|
printf("%d", x); // output is 1, since a != b
|
|
|
|
|
|
$expr1 > expr2$ *crv-opRelGT*
|
|
---------------
|
|
"greater than" operator. The result is 1 if value of$expr1$is greater than
|
|
value of $expr2$, else result is 0.
|
|
The result has type$int$.
|
|
|
|
Example: >
|
|
int x, a, b;
|
|
|
|
a = 5;
|
|
b = 2;
|
|
|
|
if (a > b)
|
|
{
|
|
printf("a is greater than b");
|
|
}
|
|
|
|
x = a > b;
|
|
printf("%d", x); // output is 1, since a > b
|
|
|
|
|
|
$expr1 < expr2$ *crv-opRelLT*
|
|
---------------
|
|
"less than" operator. The result is 1 if value of$expr1$is less than
|
|
value of$expr2$, else result is 0.
|
|
The result has type$int$.
|
|
|
|
Example: >
|
|
int x, a, b;
|
|
|
|
a = 1;
|
|
b = 2;
|
|
|
|
if (a < b)
|
|
{
|
|
printf("a is less than b");
|
|
}
|
|
|
|
x = a < b;
|
|
printf("%d", x); // output is 1, since a < b
|
|
|
|
|
|
$expr1 >= expr2$ *crv-opRelGTE*
|
|
----------------
|
|
"greater than or equal to" operator. The result is 1 if value of$expr1$is
|
|
greater than or equal to value of$expr2$, else result is 0.
|
|
The result has type$int$.
|
|
|
|
Example: >
|
|
int x, a, b;
|
|
|
|
a = 1;
|
|
b = 1;
|
|
|
|
if (a >= b)
|
|
{
|
|
printf("a is greater than or equal to b");
|
|
}
|
|
|
|
a = 1; b = 2;
|
|
x = a >= b;
|
|
printf("%d", x); // output is 0, since a < b
|
|
|
|
|
|
$expr1 <= expr2$ *crv-opRelLTE*
|
|
----------------
|
|
"less than or equal to" operator. The result is 1 if value of$expr1$is
|
|
less than or equal to value of$expr2$, else result is 0.
|
|
The result has type$int$.
|
|
|
|
Example: >
|
|
int x, a, b;
|
|
|
|
a = 1;
|
|
b = 2;
|
|
|
|
if (a <= b)
|
|
{
|
|
printf("a is less than or equal to b");
|
|
}
|
|
|
|
x = a <= b;
|
|
printf("%d", x); // output is 1, since a <= b
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.3.5 Bitwise *crv-opBitwise*
|
|
|
|
$expr1 & expr2$ *crv-opBitAnd*
|
|
---------------
|
|
Bitwise AND operator. This operator does a bitwise AND on the values
|
|
of$expr1$and$expr2$.
|
|
The result is a value the same size as the expressions.
|
|
|
|
$expr1$ | $expr2$ || result
|
|
n-th Bit | n-th Bit || n-th Bit
|
|
----------+-----------++----------
|
|
0 | 0 || 0
|
|
0 | 1 || 0
|
|
1 | 0 || 0
|
|
1 | 1 || 1
|
|
|
|
Example: >
|
|
int a, b;
|
|
|
|
b = 0x81;
|
|
a = b & 0xF0;
|
|
// value of a is: 0x80
|
|
|
|
|
|
$expr1 | expr2$ *crv-opBitOr*
|
|
---------------
|
|
Bitwise OR operator. This operator does a bitwise OR on the values
|
|
of$expr1$and$expr2$.
|
|
The result is a value the same size as the expressions.
|
|
|
|
$expr1$ | $expr2$ || result
|
|
n-th Bit | n-th Bit || n-th Bit
|
|
----------+-----------++----------
|
|
0 | 0 || 0
|
|
0 | 1 || 1
|
|
1 | 0 || 1
|
|
1 | 1 || 1
|
|
|
|
Example: >
|
|
int a, b;
|
|
|
|
b = 0x81;
|
|
a = b | 0xF0;
|
|
// value of a is: 0xF1
|
|
|
|
|
|
$expr1 ^ expr2$ *crv-opBitXor*
|
|
---------------
|
|
Bitwise XOR operator. This operator does a bitwise XOR on the values
|
|
of$expr1$and$expr2$.
|
|
The result is a value the same size as the expressions.
|
|
|
|
$expr1$ | $expr2$ || result
|
|
n-th Bit | n-th Bit || n-th Bit
|
|
----------+-----------++----------
|
|
0 | 0 || 0
|
|
0 | 1 || 1
|
|
1 | 0 || 1
|
|
1 | 1 || 0
|
|
|
|
Example: >
|
|
int a, b;
|
|
|
|
b = 0x81;
|
|
a = b ^ 0xF0;
|
|
// value of a is: 0x71
|
|
|
|
|
|
$expr1 << expr2$ *crv-opBitLeftShift*
|
|
----------------
|
|
Bitwise left-shift operator. The result is$expr1$left-shifted$expr2$bit
|
|
positions, vacated bits are filled with 0.
|
|
|
|
IF$expr1$is an unsigned type the value of the result is:
|
|
$expr1$* 2^($expr2$) modulo (1 + maximum value representable in resulting
|
|
type)
|
|
ELSE
|
|
IF$expr1$is a signed type and has a nonnegative value and
|
|
$expr1$* 2^($expr2$) is representable in the result type then the
|
|
result is:
|
|
$expr1$* 2^($expr2$)
|
|
ELSE
|
|
behavior is undefined
|
|
|
|
Both expressions must be integer types (char, short, int, long...,
|
|
signed or unsigned).
|
|
The result has the type of$expr1$.
|
|
If the value of$expr2$is negative or is greater than or equal to the
|
|
width of$expr1$, the behavior is implementation specific.
|
|
|
|
Example: >
|
|
int a, b, c;
|
|
|
|
a = 3;
|
|
b = 2;
|
|
c = a << b;
|
|
// value of c is 12
|
|
|
|
|
|
$expr1 >> expr2$ *crv-opBitRightShift*
|
|
----------------
|
|
Bitwise right-shift operator. The result is$expr1$right-shifted$expr2$
|
|
bit positions.
|
|
|
|
If$expr1$has an unsigned type or if$expr1$has a signed type and a nonnegative
|
|
value, the result is:
|
|
$expr1$/ 2^($expr2$)
|
|
|
|
If$expr1$has a signed type and a negative value, the result is implementation
|
|
specific. Many compilers set vacated bits to 1.
|
|
|
|
Example: >
|
|
int a, b, c;
|
|
|
|
a = 17;
|
|
b = 2;
|
|
c = a >> b;
|
|
// value of c is 4
|
|
|
|
|
|
$~expr1$ *crv-opBitCompl*
|
|
--------
|
|
Bitwise one's complement. A bit in the result is set if the corresponding bit
|
|
in$expr1$is not set. A bit in the result is cleared if the corresponding bit
|
|
in$expr1$is set.
|
|
|
|
The expression must has an integer type (char, short, int, long...,
|
|
signed or unsigned). The result has the type of$expr1$.
|
|
|
|
Example: >
|
|
int a, b;
|
|
|
|
a = 0xF0;
|
|
b = ~a;
|
|
// value of b is 0x0F
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.3.6 Assignments *crv-opAssigns*
|
|
|
|
|
|
$expr1 = expr2$ *crv-opAsAssign*
|
|
---------------
|
|
The value of$expr2$is assigned to$expr1$.
|
|
|
|
Example: >
|
|
int a, b;
|
|
|
|
a = 2;
|
|
b = 3;
|
|
b = a * b;
|
|
|
|
|
|
$expr1 *= expr2$ *crv-opAsMul*
|
|
----------------
|
|
Assign$expr1$the value of$expr1$multiplied by$expr2$.
|
|
|
|
Same as: $expr1 = expr1 * expr2$
|
|
|
|
see |crv-opMultiply|
|
|
|
|
Example: >
|
|
int a, b;
|
|
|
|
a = 2;
|
|
b = 3;
|
|
a *= b;
|
|
// a has value 6
|
|
|
|
|
|
$expr1 /= expr2$ *crv-opAsDiv*
|
|
----------------
|
|
Assign$expr1$the value of$expr1$divided by$expr2$.
|
|
|
|
Same as: $expr1 = expr1 / expr2$
|
|
|
|
see |crv-opDivide|
|
|
|
|
Example: >
|
|
int a, b;
|
|
|
|
a = 6;
|
|
b = 3;
|
|
a /= b;
|
|
// a has value 2
|
|
|
|
|
|
$expr1 %= expr2$ *crv-opAsModulo*
|
|
----------------
|
|
Assign$expr1$the remainder after dividing$expr1$by$expr2$.
|
|
|
|
Same as: $expr1 = expr1 % expr2$
|
|
|
|
see |crv-opModulo|
|
|
|
|
Example: >
|
|
int a, b;
|
|
|
|
a = 6;
|
|
b = 3;
|
|
a %= b;
|
|
// a has value 0
|
|
|
|
|
|
$expr1 += expr2$ *crv-opAsAdd*
|
|
----------------
|
|
Assign$expr1$the value of the sum of$expr1$and$expr2$.
|
|
|
|
Same as: $expr1 = expr1 + expr2$
|
|
|
|
see |crv-opAdd|
|
|
|
|
Example: >
|
|
int a, b;
|
|
|
|
a = 6;
|
|
b = 3;
|
|
a += b;
|
|
// a has value 9
|
|
|
|
|
|
|
|
$expr1 -= expr2$ *crv-opAsSub*
|
|
----------------
|
|
Assign$expr1$the value of$expr2$substracted by$expr1$.
|
|
|
|
Same as: $expr1 = expr1 - expr2$
|
|
|
|
see |crv-opSub|
|
|
|
|
Example: >
|
|
int a, b;
|
|
|
|
a = 6;
|
|
b = 4;
|
|
a -= b;
|
|
// a has value 2
|
|
|
|
|
|
$expr1 <<= expr2$ *crv-opAsLeftShift*
|
|
-----------------
|
|
Assign$expr1$the value of$expr1$left-shifted by$expr2$bit positions.
|
|
|
|
Same as: $expr1 = expr1 << expr2$
|
|
|
|
see |crv-opBitLeftShift|
|
|
|
|
Example: >
|
|
int a, b;
|
|
|
|
a = 6;
|
|
b = 2;
|
|
a <<= b;
|
|
// a has value 24
|
|
|
|
|
|
$expr1 >>= expr2$ *op-opAsRightShift*
|
|
-----------------
|
|
Assign$expr1$the value of$expr1$right-shifted by$expr2$bit positions.
|
|
|
|
Same as: $expr1 = expr1 >> expr2$
|
|
|
|
see |crv-opBitRightShift|
|
|
|
|
Example: >
|
|
int a, b;
|
|
|
|
a = 6;
|
|
b = 1;
|
|
a >>= b;
|
|
// a has value 3
|
|
|
|
|
|
$expr1 &= expr2$ *opAsBitAnd*
|
|
----------------
|
|
Assign$expr1$the value of the bitwise AND of$expr1$and$expr2$.
|
|
|
|
Same as: $expr1 = expr1 & expr2$
|
|
|
|
see |crv-opBitAnd|
|
|
|
|
Example: >
|
|
int a, b;
|
|
|
|
a = 0x81;
|
|
b = 0x0F;
|
|
a &= b;
|
|
// a has value 0x01
|
|
|
|
|
|
$expr1 ^= expr2$ *opAsBitXor*
|
|
----------------
|
|
Assign$expr1$the value of the bitwise XOR of$expr1$and$expr2$.
|
|
|
|
Same as: $expr1 = expr1 ^ expr2$
|
|
|
|
see |crv-opBitXor|
|
|
|
|
Example: >
|
|
int a, b;
|
|
|
|
a = 0x81;
|
|
b = 0x0F;
|
|
a &= b;
|
|
// a has value 0x01
|
|
|
|
|
|
$expr1 |= expr2$ *opAsBitOr*
|
|
----------------
|
|
Assign$expr1$the value of the bitwise OR of$expr1$and$expr2$.
|
|
|
|
Same as: $expr1 = expr1 | expr2$
|
|
|
|
see |crv-opBitOr|
|
|
|
|
Example: >
|
|
int a, b;
|
|
|
|
a = 0x81;
|
|
b = 0x0F;
|
|
a |= b;
|
|
// a has value 0x8F
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.3.7 Others *crv-opOthers*
|
|
|
|
I.3.7.1 Size of *crv-opSizeOf*
|
|
----------------
|
|
Operator: $sizeof$ *crv-sizeof*
|
|
Declaration:
|
|
$size_t sizeof expression$
|
|
or
|
|
$size_t sizeof (type-name)$
|
|
|
|
The$sizeof$operator yields the size of its operand (number of bytes).
|
|
The operand is either an expression or a name of a type. The name of type
|
|
must be in parenthesis.
|
|
The result has type$size_t$which is an unsigned integer type (unsigned int,
|
|
unsigned long,.... implementation specific).
|
|
|
|
The result for$char$,$unsigned char$,$signed char$or a typedef of them is 1.
|
|
For arrays the result is the total number of bytes used by the object.
|
|
For structures or unions the result is the total number of bytes in the
|
|
object including pad-bytes added by the compiler for alignment.
|
|
|
|
Examples: >
|
|
char a[7];
|
|
printf("%d", sizeof a ); // prints 7
|
|
printf("%d", sizeof a[0] ); // prints 1
|
|
|
|
printf("%d", sizeof(float) ); // prints 4
|
|
|
|
--------
|
|
|
|
struct Test {
|
|
char ch;
|
|
float f;
|
|
} tst;
|
|
|
|
printf("%d", sizeof(tst) ); // print 8 (impl. specific)
|
|
printf("%d", sizeof(struct Test) ); // print 8 (impl. specific)
|
|
|
|
|
|
|
|
I.3.7.2 Address of *crv-opAddress*
|
|
-------------------
|
|
Syntax: $&operand$
|
|
|
|
The$&$operator returns the address of its operand. If the operand has type
|
|
"type" the result has type "pointer to type".
|
|
|
|
Operand can be:
|
|
- a data type that is not register nor bit-fields
|
|
- function designator
|
|
- the result of$[]$operator
|
|
- the result of$*$operator
|
|
|
|
|
|
Example: >
|
|
int a, *ptr;
|
|
|
|
a = 3;
|
|
ptr = &a; // assign address of a to prt
|
|
|
|
printf("a: value = %d, address = %p", a, ptr);
|
|
|
|
|
|
I.3.7.3 Contents of *crv-opContents*
|
|
--------------------
|
|
Syntax: $*operand$
|
|
|
|
The$*$operator refers to the value of the object a pointer points to.
|
|
The operand must be a pointer type.
|
|
If the operand has type "pointer to type" the result has type "type".
|
|
|
|
Example: >
|
|
int a, b, *ptr;
|
|
|
|
ptr = &a; // assign address of a to prt
|
|
*ptr = 5 // set value of object ptr points to to 5 (object is a)
|
|
b = *ptr; // assign value of object pointer ptr points to to b
|
|
|
|
|
|
I.3.7.4 Conditional *crv-opConditional*
|
|
--------------------
|
|
Syntax: $expr1 ? expr2 : expr3$
|
|
|
|
At first$expr1$is evaluated. If$expr1$is unequal 0,$expr2$is evaluated.
|
|
If$expr1$is equal 0,$expr3$is evaluated.
|
|
|
|
The result of the conditional operator is either the value of$expr2$or$expr3$,
|
|
whichever is evaluated. The type of the result is:
|
|
- If$expr2$and$expr3$have the same type, the result has that type.
|
|
- If$expr2$and$expr3$have different types, the result has the type
|
|
that would be determined by the usual arithmetic conversions, were they
|
|
applied to$expr2$and$expr3$.
|
|
|
|
Example: >
|
|
int a, b, max;
|
|
|
|
a = 2;
|
|
b = 5;
|
|
|
|
max = a > b ? a : b; // get maximum of a and b
|
|
|
|
a == 2 ? FuncA() : FuncB(); // call FuncA() if a == 2, else call FuncB()
|
|
|
|
|
|
I.3.7.5 Series *crv-opSeries*
|
|
---------------
|
|
Syntax: $expr1, expr2$
|
|
|
|
The comma operator$,$ allows to put two separate expressions where one is
|
|
required.
|
|
At first$expr1$is evaluated. Then$expr2$is evaluated. The result of the
|
|
comma operator has the value and type of$expr2$.
|
|
|
|
It is allowed to nest expressions.
|
|
|
|
Example: >
|
|
int i, j, k;
|
|
|
|
for (i=0, j=15, k=2; i < 5; i++, j--)
|
|
{
|
|
....
|
|
}
|
|
|
|
func(3, (i=3, i+6), k); // second parameter has value 9 and type int
|
|
|
|
|
|
|
|
I.3.7.6 Type Cast *crv-opTypeCast*
|
|
------------------
|
|
Syntax: $(type-name)expr1$
|
|
|
|
The type cast operator converts the value of$expr1$to$type-name$.
|
|
|
|
Examples: >
|
|
int a, b;
|
|
float f;
|
|
|
|
a = 5;
|
|
b = 10;
|
|
|
|
f = a / b;
|
|
// f has value 0, integer division
|
|
|
|
f = (float)a / (float)b;
|
|
// f has value 0.5
|
|
|
|
|
|
I.3.7.7 Struct/Union Selectors *crv-opStructUnionSel*
|
|
-------------------------------
|
|
- Struct/Union: $expr1.identifier$
|
|
The$.$operator selects a member of a structure or union.
|
|
$expr1$has the type of a structure or union.
|
|
|
|
|
|
- Pointer to Struct/Union: $expr1->identifier$
|
|
The$->$operator selects a member of a structure or union.
|
|
$expr1$has the type of "pointer to structure" or
|
|
"pointer to union".
|
|
|
|
Examples: >
|
|
struct Example {
|
|
int element1;
|
|
float element2;
|
|
} expl;
|
|
|
|
struct Example *ptr;
|
|
|
|
ptr = &expl;
|
|
|
|
expl.element1 = 2;
|
|
ptr->element2 = 42.0f;
|
|
|
|
|
|
I.3.7.8 Array Selector *crv-opArraySel*
|
|
-----------------------
|
|
Syntax: $expr1[expr2]...[exprN]$
|
|
|
|
Selects an element of an array. First element has index 0.
|
|
|
|
Examples: >
|
|
int a[3] = {1,2,3};
|
|
int b[2][3] = { {1,2,3}, {4,5,6}};
|
|
|
|
printf("%d\n", b[1][0]); // output 4
|
|
|
|
a[2] = 0; // array a contains {1,2,0}
|
|
|
|
|
|
I.3.7.9 Parentheses *crv-opParenth*
|
|
--------------------
|
|
Operator:$()$
|
|
|
|
The parentheses-operator is used for:
|
|
|
|
- group expressions
|
|
$a = (b + 2) * c$
|
|
|
|
- declare functions
|
|
$a = func(b, c + 1)$
|
|
|
|
- explicit type-cast (see |crv-opTypeCast|)
|
|
|
|
- statements like
|
|
$if (...)$
|
|
$for (...)$
|
|
$while(...)$
|
|
....
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.3.8 Precedence *crv-opPrecedence*
|
|
|
|
The precedence defines which operator is done before other ones
|
|
(e.g.$a + b * c$: at first the multiplication is done then the addition).
|
|
The following table shows the order of precedence, operators at the top have
|
|
highest precedence.
|
|
|
|
|
|
Operator | Associativity
|
|
---------------------------------------+----------------
|
|
$ () [] -> . $| left to right
|
|
$ ! ~ ++ -- + - (type-name) * & sizeof $| right to left (unary operators)
|
|
$ * / % $| left to right
|
|
$ + - $| left to right
|
|
$ << >> $| left to right
|
|
$ < <= > >= $| left to right
|
|
$ == != $| left to right
|
|
$ & $| left to right
|
|
$ ^ $| left to right
|
|
$ | $| left to right
|
|
$ && $| left to right
|
|
$ || $| left to right
|
|
$ ?: $| right to left
|
|
$ = += -= /= *= %= >>= <<= &= |= ^= $| right to left
|
|
$ , $| left to right
|
|
|
|
|
|
If operators have the same order of precedence, the associativity defines
|
|
the order in which operators are done:
|
|
E.g.
|
|
$ a - b - c$
|
|
is done as
|
|
$(a - b) - c$
|
|
(from left to right)
|
|
|
|
|
|
NOTE: Precedence and associativity define which operator is done before
|
|
other ones. But the order of evaluation of subexpressions is unspecified,
|
|
except from function-call$()$,$&&$,$||$,$?:$and$,$. The order in which side
|
|
effects take place is unspecified too.
|
|
|
|
Example:
|
|
$a = b + c * d;$
|
|
|
|
Because of the precedence a compiler has to calculate$c*d$and has
|
|
to add$b$and has to assign the result of that whole expression to$a$.
|
|
This is defined in the C standard. But a compiler is free to take e.g.
|
|
$b$and save it, then take$c$and then$d$and do$c*d$, add the saved value
|
|
of$b$and assign result to$a$. Or do any other order of evaluating the
|
|
subexpressions.
|
|
There are just a few operators that force compilers to a specified
|
|
sequence of evaluating subexpressions (see paragraph above).
|
|
|
|
But of course the order of evaluating subexpressions can be relevant:
|
|
Example: >
|
|
int a = 4;
|
|
int b;
|
|
|
|
b = ((a=2) * (a*=3)); // b either 12 or 24?
|
|
// a either 2 or 6? compiler specific
|
|
<
|
|
If the compiler takes first the expression$(a=2)$and then$(a*=3)$the
|
|
result will be 12. But if the compiler takes first$(a*=3)$and then
|
|
$(a=2)$the result will be 24.
|
|
|
|
NOTE: Never ever write code that depends on the order of evaluating
|
|
expressions.
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
I.4 Punctuators *crv-punctuators*
|
|
|
|
Punctuators are special characters, they are not operands or identifiers.
|
|
They have their own semantic and syntactic.
|
|
|
|
Punctuator | Example | Description
|
|
------------+------------------------+---------------------------------------
|
|
$ < > $| <stdio.h> | header name
|
|
$ [ ] $| n = a[3]; | array delimiter
|
|
$ ( ) $| func(a, b); | function parameter list or
|
|
| | expression grouping
|
|
$ { } $| char ch[2]={'a', 'b'}; | function body, initializer list,
|
|
| | compound statement
|
|
$ * $| int *ptr; | pointer declaration
|
|
$ # $| #include | preprocessor directive
|
|
$ , $| char ch[2]={'a', 'b'}; | argument list separator
|
|
$ : $| label: | label
|
|
$ ; $| a = b + c; | end of statement
|
|
$ ... $| func(int a, ...) | variable length of argument list
|
|
$ = $| int n = 2; | declaration initializer
|
|
$ ' ' $| char ch = 'a'; | character constant
|
|
$ " " $| char ch[] = "abc"; | string constant or header file name
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
I.5 Datatypes *crv-datatypes*
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.5.1 Overview *crv-dtOverview*
|
|
|
|
I.5.1.1 Type Specifiers *crv-dtTypeSpecifiers*
|
|
------------------------
|
|
To specify a datatype in standard C the following type-specifiers are
|
|
allowed:
|
|
|
|
$void $
|
|
$char $ *crv-char*
|
|
$short $ *crv-short*
|
|
$int $ *crv-int*
|
|
$long $ *crv-long*
|
|
$float $ *crv-float*
|
|
$double $ *crv-double*
|
|
$signed $ *crv-signed*
|
|
$unsigned $ *crv-unsigned*
|
|
$_Bool $ *crv-_Bool*
|
|
$_Complex $ *crv-_Complex*
|
|
$_Imaginary$ *crv-_Imaginary*
|
|
$struct $
|
|
$union $
|
|
$enum $
|
|
$typedef-name$
|
|
|
|
|
|
Type specifiers can be combined, the whole set of possible type specifiers is
|
|
viewed in the table below. Specifiers given in the same row have the same
|
|
meaning.
|
|
|
|
|
|
Type Specifier | Description
|
|
=========================+==================================================
|
|
$void $| empty or NULL value
|
|
-------------------------+--------------------------------------------------
|
|
$char $| store member of basic character set
|
|
$signed char $|
|
|
-------------------------+--------------------------------------------------
|
|
$unsigned char $| same as char, but unsigned values only
|
|
-------------------------+--------------------------------------------------
|
|
$short $| defines a short signed integer
|
|
$short int $|
|
|
$signed short $|
|
|
$signed short int $|
|
|
-------------------------+--------------------------------------------------
|
|
$unsigned short $| same as short, but unsigned values only
|
|
$unsigned short int $|
|
|
-------------------------+--------------------------------------------------
|
|
$int $| defines a signed integer
|
|
$signed $|
|
|
$signed int $|
|
|
-------------------------+--------------------------------------------------
|
|
$unsigned $| same as int, but unsigned values only
|
|
$unsigned int $|
|
|
-------------------------+--------------------------------------------------
|
|
$long $| defines a long signed integer
|
|
$long int $|
|
|
$signed long $|
|
|
$signed long int $|
|
|
-------------------------+--------------------------------------------------
|
|
$unsigned long $| same as long, but unsigned values only
|
|
$unsigned long int $|
|
|
-------------------------+--------------------------------------------------
|
|
$long long $| defines a long long signed integer
|
|
$long long int $|
|
|
$signed long long $|
|
|
$signed long long int $|
|
|
-------------------------+--------------------------------------------------
|
|
$unsigned long long $| same as long long, but unsigned values only
|
|
$unsigned long long int $|
|
|
-------------------------+--------------------------------------------------
|
|
$float $| defines a floating-point number
|
|
-------------------------+--------------------------------------------------
|
|
$double $| defines a more accurate floating-point number
|
|
| than float
|
|
-------------------------+--------------------------------------------------
|
|
$long double $| defines a more accurate floating-point number
|
|
| than double
|
|
-------------------------+--------------------------------------------------
|
|
$_Bool $| defines a Bool-integer (0 or 1 only)
|
|
-------------------------+--------------------------------------------------
|
|
$float _Complex $| defines a complex number with floating
|
|
-------------------------+--------------------------------------------------
|
|
$double _Complex $| defines a complex number more accurate
|
|
| than the float type
|
|
-------------------------+--------------------------------------------------
|
|
$long double _Complex $| defines a complex number more accurate than
|
|
| the double type
|
|
-------------------------+--------------------------------------------------
|
|
$float _Imaginary $| defines an imaginary number with floating
|
|
-------------------------+--------------------------------------------------
|
|
$double _Imaginary $| defines an imaginary number more accurate
|
|
| than the float type
|
|
-------------------------+--------------------------------------------------
|
|
$long double _Imaginary $| defines an imaginary number more accurate than
|
|
| the double type
|
|
-------------------------+--------------------------------------------------
|
|
$struct $| defines a set of elements that have possibly
|
|
| different datatypes (unlike an array)
|
|
-------------------------+--------------------------------------------------
|
|
$union $| defines a set of elements that have possibly
|
|
| different datatypes and use the same overlapping
|
|
| memory (total size is size of biggest element)
|
|
-------------------------+--------------------------------------------------
|
|
$enum $| defines a set of named integer constant values
|
|
-------------------------+--------------------------------------------------
|
|
$typedef-name $| a new named type defined with the$typedef$
|
|
| keyword, the new type is a synonym for one of the
|
|
| types listed above
|
|
=========================+==================================================
|
|
|
|
|
|
|
|
I.5.1.2 Type Grouping *crv-dtTypeGrouping*
|
|
----------------------
|
|
|
|
The types can be grouped in this way:
|
|
|
|
|
|
TYPE
|
|
|
|
|
-------------------+-----------+-------------
|
|
| | |
|
|
| | |
|
|
------- SCALAR ----- AGGREGATE $void$
|
|
| | |
|
|
| | +-------------
|
|
| | | |
|
|
- ARITHMETIC --- $pointers$ ARRAY STRUCTURE
|
|
| | | |
|
|
| | | |
|
|
INTEGER - FLOATING -+----------- $array$ -$struct$-
|
|
| | | | | |
|
|
| | | | | |
|
|
| REAL COMPLEX IMAGINARY $union bit-field$
|
|
| | | |
|
|
| | | $_Imaginary$(1)
|
|
| | | |
|
|
| | | +-------+---------
|
|
| | | | | |
|
|
| | | $float double long double$
|
|
| | |
|
|
| | |
|
|
| | $_Complex$(1)
|
|
| | |
|
|
| | +-------+---------
|
|
| | | | |
|
|
| | $float double long double$
|
|
| |
|
|
| |
|
|
| +-------+---------
|
|
| | | |
|
|
| $float double long double$
|
|
|
|
|
|
|
|
+-----------------+---------------+---------
|
|
| | | |
|
|
$char short enum _Bool$
|
|
$signed/unsigned int $
|
|
$ long $
|
|
$ long long $
|
|
$ signed/unsigned $
|
|
|
|
|
|
(1): implementation of these datatypes is not required
|
|
|
|
|
|
The basic types are type char, signed/unsigned integer types and floating
|
|
types.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.5.2 Sizes and Ranges *crv-dtSizeRange*
|
|
|
|
|
|
The C standard defines the basic types as having a "at least" size.
|
|
|
|
Type | Size/Range
|
|
============+===================================================
|
|
$char $| large enough to store any member of the basic
|
|
| character set
|
|
------------+---------------------------------------------------
|
|
$short $| same as int or smaller range
|
|
------------+---------------------------------------------------
|
|
$int $| has the natural size suggested by the architecture
|
|
| of the execution environment
|
|
------------+---------------------------------------------------
|
|
$long $| same as int or greater range
|
|
------------+---------------------------------------------------
|
|
$long long $| same as long or greater range
|
|
------------+---------------------------------------------------
|
|
$float $| IEEE-754 floating-point standard, single format
|
|
------------+--------------------------------------------------
|
|
$double $| IEEE-754 floating-point standard, double format
|
|
------------+---------------------------------------------------
|
|
$long double$| shall have more precision than double and at
|
|
| least the range of double
|
|
------------+---------------------------------------------------
|
|
$_Bool $| large enough to store values 0 and 1
|
|
============+===================================================
|
|
|
|
|
|
|
|
Common - but not guaranteed - values are:
|
|
|
|
|
|
Type | Size/Range
|
|
| 16-bit Architecture 32-bit Architecture
|
|
============+================================================================
|
|
$char $| 8 bit
|
|
| 0...255
|
|
| -128...127
|
|
------------+----------------------------------------------------------------
|
|
$short $| 16 bit
|
|
| 0...65535
|
|
| -32768...32767
|
|
------------+----------------------------------------------------------------
|
|
$int $| 16 bit | 32 bit
|
|
| 0...65535 | 0...4,294,967,295
|
|
| -32768...32767 | -2,147,483,648...2,147,483,647
|
|
------------+----------------------------------------------------------------
|
|
$long $| 32 bit
|
|
| 0...4,294,967,295
|
|
| -2,147,483,648...2,147,483,647
|
|
------------+----------------------------------------------------------------
|
|
$long long $| 64 bit
|
|
| 0...18,446,744,073,709,551,615
|
|
| -9,223,372,036,854,775,808...9,223,372,036,854,775,807
|
|
------------+----------------------------------------------------------------
|
|
$float $| 32 bit
|
|
| magnitudes: 1.175494351e-38...3.402823466e+38
|
|
| significant digits: >= 6
|
|
| given x, next is: x * (1 + 1.192092896e-7)
|
|
------------+----------------------------------------------------------------
|
|
$double $| 64 bits
|
|
| magnitudes: 2.2250738585072014e-308...1.7976931348623158e+308
|
|
| significant digits: >= 15
|
|
| given x, next is: x * (1 + 2.2204460492503131e-16)
|
|
------------+----------------------------------------------------------------
|
|
$long double$| 96 bits, 80 bits used
|
|
| magnitudes: 3.36210314311209351e-4932 1.18973149535723177e+4932
|
|
| significant digits: >= 18
|
|
| given x, next is: x * (1 + 1.08420217248550443e-19)
|
|
------------+----------------------------------------------------------------
|
|
$_Bool $| 16 bit | 32 bit
|
|
| 0, 1 | 0, 1
|
|
============+================================================================
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.5.2 Formats *crv-dtFormats*
|
|
|
|
I.5.2.1 Integer *crv-dtFormatsInt*
|
|
----------------
|
|
|
|
Integer values are represented as binary numbers (base 2).
|
|
|
|
The range of unsinged integer types is 0...2^(N-1), whereas N is the size
|
|
of the integer type (8, 16, 32, 64 bit...).
|
|
|
|
Value = bitN*2^(N-1) + ... + bit3*2^3 + bit2*2^2 + bit1*2^1 + bit0*2^0
|
|
|
|
N is the most significant bit, 0 the least significant.
|
|
|
|
For signed integer values one bit is used as sign, commonly the most
|
|
significant bit.
|
|
If sign bit is 0, the representation is the same as for unsigned integer.
|
|
If sign bit is 1, a negative value is represented. There are three
|
|
possibilities to represent a negative value:
|
|
|
|
- Sign-Magnitude *crv-signMagnitude*
|
|
--------------
|
|
Sign bit 0: the rest is a positive number
|
|
Sign bit 1: the rest is a negative number
|
|
E.g.:
|
|
0000 1001 = +9
|
|
1000 1001 = -9
|
|
|
|
Attributs:
|
|
+0 and -0 exists
|
|
Range: -2^(N-1) - 1 ... 2^(N-1) - 1 (e.g. 8bit: -127 ... +127)
|
|
adding, subtracting, dividing, multiplying needs extra logic
|
|
conversion from positive to negative values and vice versa is simple
|
|
|
|
- One's Complement *crv-onesComplement*
|
|
----------------
|
|
The negative value is obtained by inverting all bits of the corresponding
|
|
positive value.
|
|
The most significant bit is the sign bit. Positive values have sign bit 0,
|
|
negative values have sign bit 1.
|
|
|
|
Attributs:
|
|
+0 and -0 exists
|
|
Range: -2^(N-1) - 1 ... 2^(N-1) - 1 (e.g. 8bit: -127 ... +127)
|
|
conversion from positive to negative values and vice versa is simple
|
|
adding can be done directly, subtracting can be converted to adding
|
|
multiplication needs extra logic for sign
|
|
|
|
- Two's Complement *crv-twosComplement*
|
|
----------------
|
|
The negative value is obtained by inverting all bits of the corresponding
|
|
positive value and adding 1.
|
|
The most significant bit is the sign bit. Positive values have sign bit 0,
|
|
negative values have sign bit 1.
|
|
|
|
Attributs:
|
|
only one 0 exists
|
|
Range: -2^(N-1) ... 2^(N-1) - 1, asymetric (e.g. 8bit: -128 ... +127)
|
|
adding and multiplying is straight forward
|
|
sign extension when promoting is simple (repeat sign bit on the left)
|
|
|
|
Which method is used to represent negative values is implementation specific,
|
|
commonly the two's complement is used.
|
|
|
|
|
|
Beneath decimal numbers (base 10), octal (base 8) and hexadecimal (base 16)
|
|
numbers can be used in standard C.
|
|
|
|
Octal numbers start with a 0 (zero), hexadecimal start with a 0x (zero x).
|
|
Opposed to decimal numbers, conversions from and to binary is easier with
|
|
octal and hexadecimal numbers.
|
|
Octal groups 3 bits, one digit has range 0...7.
|
|
Hexadecimal groups 4 bits, one digit has range 0...9, A...F.
|
|
|
|
Examples:
|
|
Bit
|
|
15 14 13 12 11 10 9 8 | 7 6 5 4 3 2 1 0
|
|
--------------------------------------------------
|
|
1 1 1 0 1 0 0 1 0 1 0 1 1 0 0 1
|
|
| | | | |
|
|
octal: 1 | 6 | 4 | 5 | 3 | 1 = 0164531
|
|
|
|
|
|
Bit
|
|
15 14 13 12 11 10 9 8 | 7 6 5 4 3 2 1 0
|
|
--------------------------------------------------
|
|
1 1 1 0 1 0 0 1 0 1 0 1 1 0 0 1
|
|
| | |
|
|
hex: E | 9 | 5 | 9 = 0xE959
|
|
|
|
|
|
|
|
|
|
I.5.2.2 Floating-Point *crv-dtFormatsFloat*
|
|
-----------------------
|
|
|
|
I.5.2.2.1 Basics *crv-dtFormatsFPBasics*
|
|
-----------------
|
|
In standard C floating values are represented as described in the floating-
|
|
point standard IEC 60559 (previously IEEE-754).
|
|
NOTE: The standard does not define bit-positions!
|
|
|
|
Generally a floating pointer number consists of four parts:
|
|
- sign
|
|
- mantissa
|
|
- radix
|
|
- exponent
|
|
|
|
---------------------------------------------- ~
|
|
| value = sign * mantissa * radix^(exponent) |~
|
|
---------------------------------------------- ~
|
|
|
|
The sign is +1 or -1. The mantissa holds the significant digits of a
|
|
floating-point number and is always positive.
|
|
The exponent indicates the positive or negative power of the radix. To
|
|
be able to get positive and negative exponents a bias is added to the
|
|
actual exponent.
|
|
|
|
A number can be expressed in many different ways, e.g.:
|
|
3.0: 3.0 * 10^0
|
|
0.03 * 10^2
|
|
300 * 10^(-2)
|
|
.....
|
|
|
|
To maximize the quantity of representable numbers, floating-point numbers
|
|
are typically stored in a normalized form.
|
|
A normalized floating-point number has a mantissa that's leftmost digit
|
|
is non-zero. To normalize the mantissa is shifted left until the leftmost
|
|
digit is non-zero, the exponent is reduced by the number of shifts.
|
|
The normalized form of the number 3.0 would be:
|
|
3.0 * 10^0
|
|
A mantissa of a floating-point number fulfils the following equation:
|
|
|
|
1/radix <= mantissa < 1~
|
|
|
|
If this equation is not fulfilled, the floating-point number is called
|
|
denormalized.
|
|
|
|
For bias 2 an optimization is available and exploited: for normalized
|
|
floating-point numbers the leftmost bit of the mantissa is always 1.
|
|
This bit don't need to be stored explicitly. We can assume it to be 1 so that
|
|
we get an extra bit to increase resolution (e.g. for float we have a 23 bit
|
|
mantissa, but a 24 bit resolution).
|
|
|
|
|
|
Special Values: *crv-dtFormatsFPValues*
|
|
---------------
|
|
There are some special values explained below.
|
|
|
|
Zero: *crv-dtFormatsFPZero*
|
|
-----
|
|
All exponent and mantissa bits are set to 0. The sign bit can be set or
|
|
cleared, so that +0 and -0 is possible. Both are treated as 0.0.
|
|
|
|
Note: There is no way to represent the value 0.0 in the format described
|
|
above. Because of normalization the leading digit must be unequal 0.
|
|
|
|
Infinity: *crv-dtFormatsFPInfinity*
|
|
---------
|
|
Infinity is signaled by all bits of exponent set and all bits of mantissa
|
|
cleared. The sign bit denotes +infinity and -infinity.
|
|
Infinity allows to handle overflows.
|
|
|
|
NaN (Not a Number): *crv-dtFormatsFPNaN*
|
|
-------------------
|
|
NaN is used to signal that the value is not a real number. NaN is denoted
|
|
by all exponent bits set and the mantissa != 0.
|
|
There are two types of NaN: Signalling NaN and Quiet NaN
|
|
Both indicates that something went wrong.
|
|
|
|
Signalling NaN:
|
|
The most significant mantissa bit cleared denotes a signalling NaN.
|
|
A signalling NaN denotes an invalid operation (e.g. division by zero).
|
|
|
|
Quiet NaN:
|
|
The most significant mantissa bit set denotes a quiet NaN.
|
|
A quiet NaN is set, if the result of an operation is not mathematically
|
|
defined.
|
|
|
|
Denormalized: *crv-dtFormatsFPSDenorm*
|
|
-------------
|
|
If the exponent is 0 and the mantissa is unequal 0, then the value is a
|
|
denormalized number. A denormalized number has no assumed 1 in the
|
|
mantissa.
|
|
|
|
|
|
|
|
Special Operations: *crv-dtFormatsFPOp*
|
|
-------------------
|
|
|
|
Operation | Result
|
|
-------------------------+------------
|
|
n / +-infinity | 0
|
|
+-nonzero / 0 | +-infinity
|
|
+-infinity * +-infinity | +-infinity
|
|
infinity + infinity | infinity
|
|
infinity - infinity | NaN
|
|
+-infinity / +-infinity | NaN
|
|
+-infinity * 0 | NaN
|
|
+-0 / +-0 | NaN
|
|
|
|
|
|
|
|
I.5.2.2.2 Types *crv-dtFormatsFPTypes*
|
|
----------------
|
|
Below commonly used floating-point formats are described. The bit positions
|
|
are not defined in standards, neither in standard C nor in IEEE-754.
|
|
|
|
The radix is 2, so that the formula to get the value of a floating-point
|
|
number is:
|
|
|
|
------------------------------------------ ~
|
|
| value = sign * mantissa * 2^(exponent) |~
|
|
------------------------------------------ ~
|
|
|
|
Float: *crv-dtFormatsFPFloat*
|
|
------
|
|
Radix: 2
|
|
Sign: 1 bit, = 0 positive, = 1 negative
|
|
Exponent: 8 bit, bias 127
|
|
Mantissa: 23 bit, 24 bit resolution
|
|
Total Size: 32 bit
|
|
Range: 1.175494351e-38...3.402823466e+38
|
|
Precision: >= 6 (number of digital digits of precision)
|
|
(see also |crv-dtSizeRange|)
|
|
|
|
Bit: 31 30 23 22 0
|
|
s eeeeeeee mmmmmmmmmmmmmmmmmmmmmmm
|
|
|
|
s: signe
|
|
e: exponent
|
|
m: mantissa
|
|
|
|
Examples:
|
|
s eeeeeeee mmmmmmmmmmmmmmmmmmmmmmm
|
|
0.75 = 0 01111110 10000000000000000000000
|
|
|___________
|
|
|
|
|
e = 126 - 127 = -1 |
|
|
m = 1 (assume MSB 1) + 1/(2^1)
|
|
= 1.5
|
|
value = 1.5 * 2^(-1) = 0.75
|
|
|
|
s eeeeeeee mmmmmmmmmmmmmmmmmmmmmmm
|
|
12.75 = 0 10000010 10011000000000000000000
|
|
| ||____________________________
|
|
| |____________________ |
|
|
|___________ | |
|
|
| | |
|
|
e = 130 - 127 = 3 | | |
|
|
m = 1 (assume MSB 1) + 1/(2^1) + 1/(2^4) + 1/(2^5)
|
|
= 1.59375
|
|
value = 1.59375 * 2^3 = 12.75
|
|
|
|
denormalized:
|
|
s eeeeeeee mmmmmmmmmmmmmmmmmmmmmmm
|
|
1.46936...e-39 = 0 0000000 01000000000000000000000
|
|
|________
|
|
|
|
|
e = 0 - 127 = -127 |
|
|
m = 0 (no assumed MSB 1) + 1/(2^2)
|
|
= 0.25
|
|
value = 0.25 * 2^(-127) = 1.4693679385278594e-39
|
|
|
|
Double: *crv-dtFormatsFPDouble*
|
|
-------
|
|
Radix: 2
|
|
Sign: 1 bit, = 0 positive, = 1 negative
|
|
Exponent: 11 bit, bias 1023
|
|
Mantissa: 52 bit, 53 bit resolution
|
|
Total Size: 64 bit
|
|
Range: 2.2250738585072014e-308...1.7976931348623158e+308
|
|
Precision: >= 15 (number of digital digits of precision)
|
|
(see also |crv-dtSizeRange|)
|
|
|
|
Bit: 63 62 52 51 0
|
|
s eeeeeeeeeee mmmmmmmm...mmmmmmmmmmmm
|
|
|
|
s: signe
|
|
e: exponent
|
|
m: mantissa
|
|
|
|
|
|
Long Double: *crv-dtFormatsFPLDouble*
|
|
------------
|
|
Radix: 2
|
|
Sign: 1 bit, = 0 positive, = 1 negative
|
|
Exponent: 15 bit, bias 16383
|
|
Mantissa: 64 bit, 64 bit resolution(!), no assumed 1 in MSB
|
|
Total Size: 92 bit, 80 bit used
|
|
Range: 3.36210314311209351e-4932...1.18973149535723177e+4932
|
|
Precision: >= 18 (number of digital digits of precision)
|
|
(see also |crv-dtSizeRange|)
|
|
|
|
Bit: 79 78 64 63 0
|
|
s eeeeeeeeeeeeeee mmmmmmmm...mmmmmmmmmmmm
|
|
|
|
s: signe
|
|
e: exponent
|
|
m: mantissa
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.5.3 void Type *crv-dtVoid*
|
|
*crv-void*
|
|
The$void$type specifies an empty or NULL type. This is used to:
|
|
- signify that a function does not return a value
|
|
- specify a function prototype with no arguments
|
|
- indicate a generic pointer
|
|
A generic pointer can point to any object type. No type cast is
|
|
necessary.
|
|
|
|
Examples:
|
|
- function with no return value >
|
|
void Func(int n)
|
|
{
|
|
...
|
|
}
|
|
<
|
|
- function with no arguments >
|
|
int Func (void)
|
|
{
|
|
...
|
|
}
|
|
<
|
|
- generic pointer >
|
|
int i;
|
|
long l;
|
|
void *ptr;
|
|
|
|
ptr = &i;
|
|
ptr = &l;
|
|
<
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.5.4 Arrays *crv-dtArrays*
|
|
|
|
Syntax:
|
|
$storage-class-specifier type-specifier declarator[constant-expression$or$*];$
|
|
|
|
$storage-class-specifier$,$constant-expression$and$*$are optional
|
|
|
|
Arrays are used to group data types of the same type. An array can be of any
|
|
data type, except$void$.
|
|
|
|
When addressing an index within this array, indexing starts at 0 and ends
|
|
at array-size(in elements) - 1.
|
|
|
|
An array has only one dimension. To get a multidemsional array an array of
|
|
array(s) can be declared.
|
|
The elements of arrays are stored in increasing addresses so that the
|
|
rightmost subscript varies most rapidly.
|
|
Example: $int n[2][3];$
|
|
the elements are stored in this sequence:
|
|
n[0][0], n[0][1], n[0][2], n[1][0], n[1][1], n[1][2]
|
|
|
|
It can be initialized with:
|
|
$int n[2][3] = { {0, 1, 2}, {3, 4, 5} };$
|
|
|
|
|
|
Complete Array Type Declaration *crv-dtCompleteArrayDecl*
|
|
-------------------------------
|
|
|
|
A complete array type declaration is a declaration of an array with known
|
|
size. The number of elements an array stores is specified at declaration.
|
|
|
|
E.g.: $int array[2];$
|
|
|
|
The number of elements must be a constant value of >= 1 or a$*$.
|
|
|
|
If a$*$is specified then the array type is a variable-length array type of
|
|
unspecified size, which can be used only in declarations with function
|
|
prototype scope.
|
|
|
|
|
|
Incomplete Array Type Declaration *drv-dtIncompleteArrayDecl*
|
|
---------------------------------
|
|
|
|
It is possible to declare an array of unknown size by omitting the size-
|
|
information at declaration. This sort of array declaration is called
|
|
incomplete array declaration. The size of an incomplete array declaration must
|
|
be specified elsewhere, so that the array type itself is complete.
|
|
|
|
Incomplete array type declaration is useful for:
|
|
- When initializing at declaration. E.g.: >
|
|
char name1[] = "bert"; // end of string (0x00) is added automatically
|
|
char name2[] = {'b', 'e', 'r', 't', '\0'};
|
|
<
|
|
The size of both arrays is 5 bytes. The initialization does complete the
|
|
array type.
|
|
|
|
- To reference to an external defined array with known size: >
|
|
extern array[];
|
|
|
|
int main(void)
|
|
{
|
|
array[0] = 42;
|
|
....
|
|
}
|
|
<
|
|
To work with this array, its size must be known of course.
|
|
|
|
- For function parameter incomplete array type declaration can be used in the
|
|
function's declaration. E.g. >
|
|
void func(int array[])
|
|
{
|
|
array[0] = 2;
|
|
}
|
|
<
|
|
A pointer must be passed to this function!
|
|
|
|
|
|
Initialization of Arrays *drv-dtArrayInit*
|
|
------------------------
|
|
|
|
Arrays can be initialized at definition time. It is allowed to initialized
|
|
less or all elements of a array. If less are initialized the remaining
|
|
elements are set to 0 automatically.
|
|
|
|
Initialize all elements of the array, e.g.:
|
|
$int a[2] = {1, 2};$
|
|
|
|
Initialize the first elements, the rest is set to 0:
|
|
$int a[5] = {1, 2, 3};$
|
|
Not allowed is to initialize more elements as the array can store:
|
|
$int a[5] = {1, 2, 3, 4, 5, 6}; // ERROR at compilation time$
|
|
|
|
Initialize multidimensional arrays:
|
|
$int b[2][3] = { {0, 1, 2}, {3, 4, 5} };$
|
|
|
|
Initialize incomplete arrays:
|
|
$char name1[] = "bert"; // end-of-string (0x00) is added$
|
|
$char name2[] = {'b', 'e', 'r', 't', '\0'};$
|
|
|
|
Attention when assigning strings to arrays:
|
|
The end-of-string (0x00) is added only if the string fits into array:
|
|
$char ch[3] = "abc" // no end-of-string (0x00) is added here!$
|
|
$char ch[4] = "abc" // end-of-string is added$
|
|
$char ch[] = "abc" // end-of-string is added, array gets dimension of 4$
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.5.5 Structures *crv-dtStructurs*
|
|
*crv-struct*
|
|
Syntax:
|
|
$struct$structur-name${$
|
|
$variables,...$
|
|
$}$structur-variable,...$;$
|
|
|
|
|
|
Structures are used to group heterogenous data. The elements (members) of a
|
|
structure can be of different data types (opposed to arrays). All data types
|
|
are allowed, except$void$type.
|
|
The member names must be unique within a structure, but the same names can be
|
|
used in nested structures.
|
|
A structure cannot contain instances of themselves, but can have pointers
|
|
to instances of themselves as members.
|
|
|
|
The members are stored sequentially in increasing addresses. The first member
|
|
is at the starting address of a structure. But a compiler is free to add
|
|
pad-bytes for alignment. So the total size of a structure may differ from the
|
|
sum of member-sizes.
|
|
A pointer to a structure points to the starting address of the structure,
|
|
there the first member is stored.
|
|
|
|
To access a member of a structure, the structure selector$.$is used. To access
|
|
a member of a structure a pointer points to$->$is used.
|
|
|
|
A structure can be passed by value to functions and returned by value by
|
|
functions. Allowed operators with structures are$=$and$sizeof$.
|
|
|
|
|
|
Declaration *crv-dtStructDef*
|
|
-----------
|
|
To declare a structure the 'structur-variable' is omitted, e.g.: >
|
|
struct myStruct {
|
|
int n;
|
|
char *name;
|
|
long counter;
|
|
};
|
|
No variable is generated here, it's the declaration of a structure with
|
|
name myStruct. To get an object do:
|
|
$ struct myStruct ms;$
|
|
|
|
|
|
Definition *crv-dtStructDecl*
|
|
----------
|
|
A definition can be done in several ways:
|
|
|
|
- If a structure is declared already, a definition is done this way:
|
|
$struct Person pers;$
|
|
perss is the object generated
|
|
|
|
- Declaration and definition can be done both, e.g.: >
|
|
struct Person {
|
|
int age;
|
|
char *name;
|
|
} pers1;
|
|
< An object pers1 is generated. 'structur-variable' can be a comma-
|
|
separated list of variables, e.g.: >
|
|
struct Person {
|
|
int age;
|
|
char *name;
|
|
} pers1, pers2, pers3;
|
|
< The objects pers1, pers2 and pers3 are generated.
|
|
|
|
Further definitions can be done via:
|
|
$struct Person pers4;$
|
|
because a 'structure-name' was specified above.
|
|
|
|
- Only definition, no 'struct-name' specified, e.g.: >
|
|
struct {
|
|
int age;
|
|
char *name;
|
|
} pers1;
|
|
< An object pers1 is generated.
|
|
|
|
|
|
Initialization *crv-dtStructInit*
|
|
--------------
|
|
Structures can be initialized at definition time. It is allowed to initialized
|
|
less or all members of a structure. If less are initialized the remaining
|
|
elements are set to 0 automatically.
|
|
|
|
Examples: >
|
|
struct Person {
|
|
int age;
|
|
char *name;
|
|
} pers1 = {42, "Sting"};
|
|
<or >
|
|
struct Person pers2 = {42, "Sting"};
|
|
|
|
|
|
Accessing *crv-dtStructAccess*
|
|
---------
|
|
A member of a structure can be accessed via$.$,e.g.: >
|
|
myStruct.age = 42;
|
|
myStruct.anotherStruct.n = 3;
|
|
|
|
A member of a structure a pointer points to can be accessed via$->$, e.g.: >
|
|
myStructPtr->age = 42;
|
|
myStructPtr->anotherStruct.n = 3;
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.5.6 Unions *crv-dtUnions*
|
|
*crv-union*
|
|
Syntax:
|
|
$union$union-name${$
|
|
$variables,...$
|
|
$}$union-variable,...$;$
|
|
|
|
|
|
A union is used to store objects of different data types at the same location
|
|
in memory. All members of a union have offset 0 to the start address of the
|
|
union. Enough space is allocated only for the largest member in the union.
|
|
|
|
For members all data types are allowed, except$void$type. The member names
|
|
must be unique within a union, but the same names can be used in nested
|
|
unions. A union cannot contain instances of themselves, but can have pointers
|
|
to instances of themselves as members.
|
|
|
|
A pointer to a union points to the starting address of the union.
|
|
|
|
To access a member of a union, the union selector$.$is used. To access a
|
|
member of a union a pointer points to$->$is used.
|
|
|
|
A union can be passed by value to functions and returned by value by
|
|
functions. Allowed operators with unions are$=$and$sizeof$.
|
|
|
|
|
|
Declaration *crv-dtUnionDef*
|
|
-----------
|
|
To declare a union the 'union-variable' is omitted, e.g.: >
|
|
union Integers {
|
|
char c;
|
|
short s;
|
|
int n;
|
|
long l;
|
|
};
|
|
No variable is generated here, it's the declaration of a union with name
|
|
Integers. To get an object do:
|
|
$ union Integers ints;$
|
|
|
|
|
|
Definition *crv-dtUnionDecl*
|
|
----------
|
|
A definition can be done in several ways:
|
|
|
|
- If a union is declared already, a definition is done this way:
|
|
$union Integers ints;$
|
|
ints is the object generated
|
|
|
|
- Declaration and definition can be done both, e.g.: >
|
|
union Integers {
|
|
char c;
|
|
short s;
|
|
int n;
|
|
long l;
|
|
} ints1;
|
|
< An object ints1 is generated. 'union-variable' can be a comma-
|
|
separated list of variables, e.g.: >
|
|
union Integers {
|
|
char c;
|
|
short s;
|
|
int n;
|
|
long l;
|
|
} ints1, ints2, ints3;
|
|
< The objects ints1, ints2 and ints3 are generated.
|
|
|
|
Forther definitions can be done via:
|
|
$union Integers ints;$
|
|
because a 'union-name' was specified above.
|
|
|
|
- Only definition, no 'union-name' specified, e.g.: >
|
|
union {
|
|
char c;
|
|
short s;
|
|
int n;
|
|
long l;
|
|
} ints1;
|
|
< An object ints1 is generated.
|
|
|
|
|
|
Initialization *crv-dtUnionInit*
|
|
--------------
|
|
Unions can be initialized at definition time, but only the first member can
|
|
be given an initializer.
|
|
|
|
Examples: >
|
|
union Integers {
|
|
char c;
|
|
short s;
|
|
int n;
|
|
long l;
|
|
} ints1 = {'a'};
|
|
<or >
|
|
union Integers ints2 = {'a'};
|
|
|
|
|
|
Accessing *crv-dtUnionAccess*
|
|
---------
|
|
A member of a union can be accessed via$.$,e.g.: >
|
|
myUnion.age = 42;
|
|
myUnion.anotherUnion.n = 3;
|
|
|
|
A member of a union a pointer points to can be accessed via$->$, e.g.: >
|
|
myUnionPtr->age = 42;
|
|
myUnionPtr->anotherUnion.n = 3;
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.5.7 Bit-Fields *crv-dtBitFields*
|
|
|
|
Syntax:
|
|
$type-specifier identifier:constant-expression$
|
|
|
|
A member of a structure or union can be declared to consist of a specified
|
|
number of bits. Such a member is called a bit-field.
|
|
A bit-field can be of type$_Bool$,$signed int$,$unsigned int$or of some other
|
|
implementation specific type. The specified number of bits for a bit-field
|
|
must be small enough to be stored in its type.
|
|
|
|
Sequences of bit-fields are packed as tightly as possible, they are assigned
|
|
from low-order to high-order bit.
|
|
If in a sequence of bit-fields a further bit-field is specified, and this
|
|
bit-field does not fit into the remaining bits, it's implementation-specific
|
|
whether this bit-field is put into the next unit or overlaps adjacent units.
|
|
|
|
A bit-field can be closed in two ways:
|
|
- specify a data-type !=$bit-field$, a following bit-field will be started
|
|
in a new unit at low-order bit
|
|
- specify a bit-field with size 0, a following bit-field will be started
|
|
in a new unit at low-order bit
|
|
|
|
For padding it is possible to declare a bit-field without identifier
|
|
(e.g. :10).
|
|
|
|
Pointers to bit-field are not possible.
|
|
|
|
Examples: >
|
|
struct BitField {
|
|
unsigned int a:2;
|
|
unsigned int :3; // leave 3 bits free
|
|
unsigned int b:4;
|
|
unsigned int :0; // force to start new unit
|
|
|
|
unsigned int c:4:
|
|
unsigned int c:1;
|
|
|
|
long lng;
|
|
|
|
unsigned int d:2; // start a new unit since the previous type is
|
|
// not a bit-field
|
|
};
|
|
<
|
|
also possible would be >
|
|
struct BitField {
|
|
unsigend int a:2,
|
|
:3, // leave 3 bits free
|
|
b:4,
|
|
:0, // force to start new unit
|
|
|
|
c:4,
|
|
c:1;
|
|
|
|
long lng;
|
|
|
|
int d:2; // start a new unit since the previous type is
|
|
// not a bit-field
|
|
};
|
|
|
|
|
|
Accessing a bit-field is done this way: >
|
|
struct BitField {
|
|
unsigend int a:2,
|
|
b:3;
|
|
} bf;
|
|
|
|
bf.a = 3;
|
|
bf.b = 0;
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.5.8 Enumerated Tags *crv-dtEnumerate*
|
|
*crv-enum*
|
|
Syntax:
|
|
$enum identifier{enumerator-list} declarator;$
|
|
|
|
|
|
An enumeration type is a user-defined integer type. The possible values of
|
|
this type are defined in the$enumerator-list$. The elements of this list are
|
|
symbolic representations of constant integers.
|
|
Each element of the$enumerator-list$gets the value of the previous plus 1.
|
|
The first element gets the value 0. Alternatively values can be assigned to
|
|
the elements.
|
|
|
|
All this could be achieved by using$#define$too. The advantage of enumeration
|
|
types is that debuggers can view values of enumeration type objects
|
|
symbolically.
|
|
|
|
|
|
Examples:
|
|
$enum color {red, yellow, green};$
|
|
|
|
$color$is a new integer type that can have the values$red$(=0),$yellow$(=1)
|
|
and$green$(=2).
|
|
|
|
Assignment can be done this way: >
|
|
color col;
|
|
col = red;
|
|
|
|
To assign values to the constants do:
|
|
$enum color {red=10, yellow, green=20, white};$
|
|
|
|
$color$is a new integer type that can have the values$red$(=10),$yellow$
|
|
(=11),$green$(=20) and$white$(=21).
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.5.9 Strings *crv-dtStrings*
|
|
|
|
In C a string is an array of characters encapsulated in double quotes. At
|
|
the end of the string an end-of-string (0x00} is appended.
|
|
|
|
Example: >
|
|
char strng[] = "this is a string";
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.5.10 Type Definitions *crv-dtTypeDef*
|
|
|
|
A type definition is used to define a type synonym for a data type.
|
|
Type definitions are just aliases. The compiler replaces a type definition
|
|
by its assigned type.
|
|
|
|
Type definitions can apply to variables or functions.
|
|
|
|
Type definitions provide:
|
|
- It is possible to replace a lengthy and/or confusing type definition
|
|
by an expressive one.
|
|
- Type definitions can simplify the process of changing the type of
|
|
variables. Example:
|
|
$typedef short coordinate;$
|
|
If you notice that$short$is too small for your needs, simply change it:
|
|
$typedef long coordinate;$
|
|
and all variables of the type$coordinate$will have the new type$long$.
|
|
|
|
Example for data type: >
|
|
typedef int * pointerToInt;
|
|
|
|
pointerToInt iPtr; // is identical to: int *iPtr;
|
|
|
|
Example for function: >
|
|
typedef int calculate(int a, int b); // function returns int, and gets
|
|
// two ints
|
|
calculate sum; // declarate functions
|
|
calculate dif;
|
|
|
|
int sum(int a, int b) // definition: parameters and return type
|
|
{ // must be according to the typedef
|
|
return a + b;
|
|
}
|
|
|
|
int dif(int a, int b)
|
|
{
|
|
return a - b;
|
|
}
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.5.11 Storage Classes *crv-dtStorageClasses*
|
|
|
|
A storage class defines the scope and lifetime of a variable or function.
|
|
see |crv-gloScope|, |crv-gloLifetime|
|
|
|
|
Storage Class |
|
|
Specifier | Description
|
|
---------------+------------------------------------------------------------
|
|
$ auto $| default, local variable has local lifetime
|
|
$ static $| local variable, but maintained during program execution
|
|
$ extern $| indicates that a variable is defined outside of the current
|
|
| file, no variable is created by this
|
|
$ register $| request to access variable as fast as possible (normally
|
|
| this means to store an object in a CPU register)
|
|
$ typedef $| creates an alias name for a basic or derived data type
|
|
none, in | a global variable is defined
|
|
file scope |
|
|
|
|
|
|
|
|
$auto$ *crv-auto*
|
|
------
|
|
The$auto$class specifies a local variable with local lifetime. The storage of
|
|
a variable is created upon entry to the block defining the variable, and is
|
|
destroyed when exiting the block.
|
|
|
|
The contents of a new defined$auto$object is undefined.
|
|
|
|
This class can only be declared at the beginning of a block { ... }.
|
|
If no storage class if given, this is the default.
|
|
|
|
Example: >
|
|
int main(void)
|
|
{
|
|
int a; // auto can be omitted, it's the default
|
|
auto int b;
|
|
auto long c = 10L; // initializer can be used
|
|
|
|
....
|
|
}
|
|
|
|
|
|
$static$ *crv-static*
|
|
--------
|
|
The$static$class specifies that an object is maintained during the whole
|
|
program execution, but it's accessable only within its scope (block or file).
|
|
Several objects with the same identifier can co-exist, as long as they have
|
|
different scopes.
|
|
|
|
A$static$object can be declared anywhere a declaration is allowed.
|
|
|
|
The contents of a new$static$object is initialized, arithmetic members are
|
|
set to 0, pointer members are set to NULL. If an initializer is given, the
|
|
object is initialized only once at program start. Its contents is preserved
|
|
after leaving object's scope.
|
|
|
|
Example: >
|
|
int TestFunction ()
|
|
{
|
|
static int b; // initialized with 0 automatically
|
|
static long c = 10L; // initializer can be used
|
|
|
|
if (c == 10L)
|
|
{
|
|
b++;
|
|
c++;
|
|
}
|
|
.... // next time calling b will be 1 and c will be 11
|
|
}
|
|
|
|
|
|
$register$ *crv-register*
|
|
----------
|
|
The$register$class suggests the compiler to minimize access time for
|
|
a variable. Normally this means to assign the value to a register.
|
|
The compiler is free to do so or not.
|
|
The lifetime is the same as for$auto$.
|
|
|
|
The$register$class is the only storage class specifier that can
|
|
be used for function parameters too.
|
|
|
|
Example: >
|
|
int TestFunction (register int a)
|
|
{
|
|
register int b;
|
|
...
|
|
}
|
|
|
|
|
|
$extern$ *crv-extern*
|
|
--------
|
|
Using$extern$in a declaration brings the named object into the current scope,
|
|
the object must be a global one. This is used to access objects that are
|
|
defined out of the current file (linkage ->|crv-gloLinkage|).
|
|
|
|
No new variable is generated, it is just a link to an existing one.
|
|
|
|
Example: >
|
|
File 1: File 2:
|
|
------- -------
|
|
int globVar2 = 42; extern int globVar2;
|
|
|
|
int main(void) void TestFunc(void)
|
|
{ {
|
|
.... globVar2 = 3;
|
|
} ...
|
|
}
|
|
|
|
|
|
$typedef$ *crv-typedef*
|
|
---------
|
|
The$typedef$is used to create an alias for a basic or derived (array, struct,
|
|
union) data type.
|
|
Actually$typedef$isn't a real storage class, but in standard C it is defined
|
|
to be one.
|
|
No new variable is generated.
|
|
For further information see |crv-dtTypeDef|.
|
|
|
|
|
|
Global Variable
|
|
---------------
|
|
A global variable is defined when the definition is within file scope and
|
|
no storage class specifier is given.
|
|
|
|
A global object is initialized, arithmetic members are set to 0, pointer
|
|
members are set to null pointer, in unions the first named member is
|
|
initialized according to this rules. An initializer can be given.
|
|
|
|
To access a global variable from outside of its scope, declare this
|
|
variable with$extern$class in the new scope.
|
|
|
|
Example: >
|
|
File 1: File 2:
|
|
------- -------
|
|
int globVar; extern int globVar2;
|
|
|
|
int globVar2 = 42;
|
|
|
|
int main(void) void TestFunc(void)
|
|
{ {
|
|
.... globVar2 = 3;
|
|
} ...
|
|
}
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.5.12 Qualifiers *crv-dtQualifiers*
|
|
|
|
The type qualifiers allow to set further attributes of data types.
|
|
|
|
Type Qualifier | Description
|
|
----------------+------------------------------------------------------------
|
|
$ const $| no write access to a variable
|
|
$ restrict $| only for pointers: gives compiler better possibilities for
|
|
| optimizations
|
|
$ volatile $| disable compiler optimization for a variable
|
|
|
|
|
|
|
|
$const$ *crv-const*
|
|
-------
|
|
The$const$type qualifier is used to qualify an object as not modifiable. This
|
|
means no write access is allowed to this object after initialization.
|
|
The$const$qualifier can be used for any data type and together with$volatile$.
|
|
|
|
When$const$is used to qualify an aggregate type (array, struct, union) all
|
|
members are$const$. When$const$is used to qualify a member of an aggregate
|
|
only that member is$const$.
|
|
|
|
NOTE: Attempting to change a$const$object using a pointer to a non-$const$
|
|
object causes unpredictable behavior.
|
|
|
|
Example: >
|
|
const a = 5; // a = 5 and a is not modifiable
|
|
|
|
const struct Test {
|
|
int b;
|
|
char *title;
|
|
} test; // all members of test are const
|
|
|
|
const int *ptr; // pointer to a constant integer type
|
|
// pointer is allowed to change, contents not
|
|
|
|
int *const ptr; // constant pointer; pointer is not allowed to change
|
|
// contents is allowed to change
|
|
|
|
const int *const ptr; // both pointer and contents are not allowed
|
|
// to change
|
|
|
|
|
|
$restrict$ *crv-restrict*
|
|
----------
|
|
The$restrict$qualifier can only be used for pointers. It indicates that the
|
|
compiler is allowed to make optimizations when dealing with this pointer.
|
|
|
|
Normally compilers can do very less optimizations to pointers because the
|
|
compiler cannot determine whether or not two pointers point to the same
|
|
object. So the compiler must suppress various optimizations.
|
|
|
|
The user guarantees that none of the$restrict$qualified pointers do
|
|
point to the same object. So the compiler can do further optimizations
|
|
for these pointers.
|
|
|
|
|
|
$volatile$ *crv-volatile*
|
|
----------
|
|
The$volatile$qualifier indicates that the value of an object can possibly be
|
|
changed outside of compiler's control (e.g. changes done by other processes,
|
|
hardware registers of mikrocontrollers,...). The$volatile$qualifier forces
|
|
the compiler to take this into account. The compiler must access the object
|
|
always from memory and most optimizations can't be done.
|
|
|
|
The$volatile$qualifier can be used for any data type and together with$const$
|
|
qualifier.
|
|
When$volatile$is used to qualify an aggregate type (array, struct, union) all
|
|
members are$volatile$. When$volatile$is used to qualify a member of an
|
|
aggregate only that member is$volatile$.
|
|
|
|
Example: >
|
|
volatile int a;
|
|
|
|
int main(void)
|
|
{
|
|
....
|
|
}
|
|
|
|
|
|
Hint: When type casting a volatile variable, the volatile qualifier will be
|
|
lost if it is omitted in the type cast operator.
|
|
|
|
Example: >
|
|
volatile int ptrA;
|
|
long ptrB;
|
|
|
|
...
|
|
|
|
ptrA = (int *)ptrB; // ATTENTION: after this, ptrA is no
|
|
// longer volatile!
|
|
|
|
ptrA = (volatile int *)ptrB; // ptrA is still volatile
|
|
|
|
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.5.13 Pointers *crv-dtPointers*
|
|
|
|
A pointer contains the address of a variable of stated type, function or
|
|
memory area.
|
|
|
|
A pointer can have a special value indicating that the pointer points to
|
|
nowhere. Such a pointer is called null pointer, its value is NULL.
|
|
A pointer of type$void$can be used to point to an object of any type.
|
|
A pointer can point to pointers.
|
|
|
|
A pointer is declared using the$*$punctuator. The operator$*$is used to
|
|
dereference a pointer in order to have access to the contents of the object
|
|
the pointer points to.
|
|
|
|
|
|
I.5.13.1 Variables *crv-dtPtrVars*
|
|
-------------------
|
|
To assign the address of a variable to a pointer the address operator$&$is
|
|
used. To dereference the$*$operator is used.
|
|
|
|
Example simple pointer: >
|
|
int n = 3;
|
|
int *ptr; // define pointer of type int
|
|
|
|
ptr = &n; // pointer points to n
|
|
*ptr = 4; // assign object pointer points to value 4 (=> n=4)
|
|
|
|
Example pointer to pointer: >
|
|
int n = 3;
|
|
int *ptr1; // pointer to int
|
|
int **ptr2; // pointer to pointer to int
|
|
|
|
ptr1 = &n; // pointer ptr1 points to int n
|
|
ptr2 = &ptr1; // pointer ptr2 points to pointer to int n
|
|
**ptr2 = 4; // dereference pointer to pointer and assign 4 (n = 4)
|
|
|
|
A pointer can be set to a fix address this way (not standard C): >
|
|
int *ptr;
|
|
|
|
ptr = (int *)42000;
|
|
|
|
|
|
Pointer and Arrays
|
|
------------------
|
|
Example pointer to array: >
|
|
int n[2];
|
|
int *ptr;
|
|
|
|
ptr = &n[0];
|
|
ptr = n; // is equivalent to ptr = &n[0]
|
|
|
|
Example array of pointers: >
|
|
int *ptrs[3]; // array of pointers to int
|
|
int n1 = 1, n2 = 2, n3 = 3;
|
|
|
|
ptrs[0] = &n1;
|
|
ptrs[1] = &n2;
|
|
ptrs[2] = ptrs[0];
|
|
|
|
|
|
Pointer to String
|
|
-----------------
|
|
A sequence of characters encapsulated with double quotes is a pointer to
|
|
const character.
|
|
Example: >
|
|
char *ptr;
|
|
|
|
ptr = "string";
|
|
|
|
|
|
|
|
I.5.13.2 Functions *crv-dtPtrFuncs*
|
|
-------------------
|
|
A pointer can point to a function and the function can be called via pointer.
|
|
|
|
A function pointer is defined in a similar way as a function prototype, the
|
|
function name is replaced with$(*pointer-name)$.
|
|
|
|
Example: >
|
|
int (*funcPtr)(int a, int b); // define a function pointer "funcPtr"
|
|
|
|
funcPtr = anyFunction; // assign function to pointer
|
|
|
|
c = funcPtr(2, 3); // call via function pointer
|
|
|
|
|
|
Example: >
|
|
int sum(int a, int b)
|
|
{
|
|
return a + b;
|
|
}
|
|
|
|
|
|
int (*funcPtr)(int a, int b); // define a function pointer
|
|
|
|
int main(void)
|
|
{
|
|
int a;
|
|
|
|
funcPtr = sum; // assign function to pointer
|
|
|
|
a = funcPtr(2, 3); // same as a = sum(2, 3);
|
|
|
|
printf("%d\n", a); // 5 is printed
|
|
}
|
|
|
|
|
|
Example, call function at absolut address: >
|
|
|
|
// call a function of type int Func(int nNumOf)
|
|
// located at address 0x42000
|
|
|
|
// typedefs make usage of function pointers a little bit clearer
|
|
|
|
typedef int (*FuncPtr)( int nNumOf );
|
|
|
|
|
|
int main(void)
|
|
{
|
|
FuncPtr func1;
|
|
|
|
...
|
|
|
|
func1 = (FuncPtr)0x42000; // assign address to function pointer
|
|
|
|
result = func1( n ); // call function func1 points to
|
|
}
|
|
|
|
|
|
|
|
|
|
I.5.13.3 Arithmetics *crv-dtPtrArithmetics*
|
|
---------------------
|
|
|
|
Some operators are allowed to be used on pointers.
|
|
|
|
|
|
Relational Operators
|
|
--------------------
|
|
The relational operators$==$,$!=$,$>$,$<$,$>=$,$<=$are allowed if both
|
|
operands are pointers of the same type and both pointers point to an element
|
|
of the same array or to the first element after that array.
|
|
|
|
The operators$==$and$!=$are allowed in any case if one of the operands is a
|
|
null pointer (NULL).
|
|
|
|
|
|
Negation
|
|
--------
|
|
The logic negation$!$is allowed.
|
|
The negation of a null pointer (value NULL) is an integer value 1. The
|
|
negation of a pointer not equal NULL is an integer value 0.
|
|
|
|
|
|
Increasing and Decreasing
|
|
-------------------------
|
|
Increasing or decreasing of pointers of type$void$is not allowed, because the
|
|
size of the object a$void$pointer points to is unknown.
|
|
|
|
For other pointer types it is allowed to add / subtract an integer value.
|
|
If an integer value N is added to a pointer the pointer points to the Nth
|
|
element located after the element the pointer pointed to before adding.
|
|
If an integer value N is subtracted from a pointer the pointer points to the
|
|
Nth element located before the element the pointer pointed to before
|
|
subtracting.
|
|
|
|
Allowed operations: >
|
|
pointer + integer-value
|
|
pointer - integer-value
|
|
pointer++
|
|
pointer--
|
|
++pointer
|
|
--pointer
|
|
|
|
|
|
Subtraction
|
|
-----------
|
|
Pointers can be subtracted. Both pointers must not be of type$void$.
|
|
Both pointers must be of the same type and must point to an element of the
|
|
same array or to the first element after that array.
|
|
|
|
The operation$pointer1 - pointer2$returns the number of elements separating
|
|
them (negative value if pointer1 < pointer2).
|
|
|
|
|
|
Assignments
|
|
-----------
|
|
Assignments of pointers are of course allowed. The pointers must be of the
|
|
same type (if needed a type cast is to be done).
|
|
|
|
Compound assignments are allowed as long as the requirements for increasing,
|
|
decreasing and subtracting are fulfilled.
|
|
|
|
Allowed assignments: >
|
|
pointer1 = pointer2
|
|
pointer += integer-value
|
|
pointer -= integer-value
|
|
pointer1 -= pointer2
|
|
|
|
------------------------------------------------------------------------------
|
|
I.5.14 Type Cast *crv-dtTypeCast*
|
|
|
|
Type cast is an operation that converts the type of an operand into another
|
|
type. There are two types of casts, explicit and implicit.
|
|
|
|
|
|
I.5.14.1 Explicit *crv-dtTypeCastExpl*
|
|
------------------
|
|
The explicit type cast is done with the type cast operator$(type-name)$.
|
|
Example: >
|
|
int main(void)
|
|
{
|
|
int nVar = 42;
|
|
float fVar;
|
|
|
|
fVar = (float)nVar;
|
|
}
|
|
|
|
|
|
I.5.14.2 Implicit *crv-dtTypeCastImpl*
|
|
------------------
|
|
Implicit type casts are done by the compiler according to well defined rules.
|
|
|
|
A compiler does an implicit type cast:
|
|
- When two or more operands of different types appear in an expression.
|
|
- When arguments are passed to a function that do not conform to the
|
|
parameters declared in a function prototype.
|
|
|
|
|
|
When a floating-type operand is converted to an integer, the fractional part
|
|
is discarded.
|
|
|
|
|
|
- If either operand is not of arithmetic type, no conversion is performed.
|
|
|
|
- If either operand has type$long double$, the other operand is converted
|
|
to$long double$.
|
|
|
|
- Otherwise, if either operand has type$double$, the other operand is
|
|
converted to$double$.
|
|
|
|
- Otherwise, if either operand has type$float$, the other operand is
|
|
converted to$float$.
|
|
|
|
- Otherwise the following rules apply:
|
|
|
|
- If both operands have signed integer types or both operands have
|
|
unsigned integer types the operand with the type of lesser rank
|
|
is converted to the type of the operand with greater rank.
|
|
|
|
- Otherwise, if the operand that has unsigned integer type has rank
|
|
greater or equal to the rank of the other operand, then the operand with
|
|
signed integer type is converted to the type of the operand with
|
|
unsigned integer type.
|
|
|
|
- Otherwise, if the type of the operand with signed integer type can
|
|
represent all of the values of the type of the operand with unsigned
|
|
integer type, then the operand with unsigned integer type is converted
|
|
to the type of the operand with signed integer type.
|
|
|
|
- Otherwise, both operands are converted to the unsigned integer type
|
|
corresponding to the type of the operand with signed integer type.
|
|
|
|
|
|
Ranking is $long long$>$long$>$int$>$short$>$char$>$bit-field$
|
|
no matter whether singed or unsigned
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.5.15 Constants *crv-dtConstants*
|
|
|
|
Beneath$enum$there are three categories of constants in C, they are described
|
|
below.
|
|
|
|
|
|
I.5.15.1 Integer *crv-dtConstInt*
|
|
-----------------
|
|
|
|
An integer constant can be specified in decimal, hexadecimal or octal. A
|
|
suffix can be added to specify a constant's type.
|
|
|
|
Decimal~
|
|
To specify a decimal constant, the first digit must be a 1...9. For the
|
|
following digits the characters 0...9 are allowed.
|
|
|
|
Hexadecimal~
|
|
To specify a hexadecimal constant, a prefix 0x or 0X must be in front of the
|
|
hexadecimal number. For hex-numbers the characters 0...9, a-f and A-F are
|
|
allowed.
|
|
|
|
Octal~
|
|
To specify an octal constant the first digit must be a 0 (zero). For the
|
|
following digits the characters 0...7 are allowed.
|
|
|
|
|
|
Type~
|
|
The type of an integer constant is the first of the corresponding list
|
|
in which its value can be represented:
|
|
|
|
| | octal or hexadecimal
|
|
Suffix | decimal constant | constant
|
|
==============+========================+========================
|
|
none |$int $|$int$
|
|
|$long int $|$unsigned int$
|
|
|$long long int $|$long int$
|
|
|$ $|$unsigned long int$
|
|
| |$long long int$
|
|
| |$unsigned long long int$
|
|
-------------+------------------------+------------------------
|
|
$u$or$U$ |$unsigned int$ |$unsigned int$
|
|
|$unsigned long int$ |$unsigned long int$
|
|
|$unsigned long long int$|$unsigned long long int$
|
|
-------------+------------------------+------------------------
|
|
$l$or$L$ |$long int$ |$long int$
|
|
|$long long int$ |$unsigned long int$
|
|
| |$long long int$
|
|
| |$unsigned long long int$
|
|
-------------+------------------------+------------------------
|
|
both$u$or$U$|$unsigned long int$ |$unsigned long int$
|
|
and$l$or$L$ |$unsigned long long int$|$unsigned long long int$
|
|
-------------+------------------------+------------------------
|
|
$ll$or$LL$ |$long long int$ |$long long int$
|
|
| |$unsigned long long int$
|
|
-------------+------------------------+------------------------
|
|
both$u$or$U$ | |
|
|
and$ll$or$LL$|$unsigned long long int$|$unsigned long long int$
|
|
-------------+------------------------+------------------------
|
|
|
|
|
|
I.5.15.2 Floating-Point *crv-dtConstFloat*
|
|
------------------------
|
|
A floating constant has a significant part that may be followed by an exponent
|
|
part and a suffix that specifies its type.
|
|
|
|
If a floating constant has no suffix, its type is$double$. If suffix is$f$or
|
|
$F$it has type$float$. If suffix is$l$or$L$its type is$long double$.
|
|
|
|
Example | Value | Type
|
|
-----------+---------+-------------
|
|
.0 | 0.00000 | double
|
|
1. | 1.00000 | double
|
|
2.23 | 2.23000 | double
|
|
2e2 | 200.000 | double
|
|
2.e2 | 200.000 | double
|
|
2.0e2 | 200.000 | double
|
|
2.0e+2 | 200.000 | double
|
|
2.0e-2 | 0.02000 | double
|
|
3.4f | 3.40000 | float
|
|
3.4l | 3.40000 | long double
|
|
|
|
|
|
|
|
I.5.15.3 Character *crv-dtConstChar*
|
|
-------------------
|
|
A character constant is any character from the source character set enclosed
|
|
in apostrophes.
|
|
See escape sequences (-> |crv-lngEscSeq|) for special characters.
|
|
|
|
Examples: >
|
|
char a;
|
|
|
|
a = 'd';
|
|
a = '\x2F';
|
|
|
|
|
|
|
|
==============================================================================
|
|
I.6 Statements *crv-statements*
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.6.1 if-else *crv-stIfElse*
|
|
*crv-if* *crv-else*
|
|
Syntax: $if (expr1)$
|
|
$ statement1$
|
|
$else$
|
|
$ statement2$
|
|
|
|
|
|
If$expr1$is not equal to 0,$statement1$is done. If$expr1$is equal to 0,
|
|
$statement2$is done. The$else$-part is optional.
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.6.2 switch *crv-stSwitch*
|
|
*crv-switch* *crv-case* *crv-default*
|
|
Syntax: $switch (expr1) {$
|
|
$ case constant-expression1:$
|
|
$ statement1$
|
|
$ ...$
|
|
$ default:$
|
|
$ statementN$
|
|
$}$
|
|
|
|
|
|
Both$case$and$default$-part are optional.
|
|
|
|
If$expr1$is equal to one of the$constant-expressions$in the$case$labels,
|
|
the according $statement$is executed. The$default$-part is entered,
|
|
if$expr1$is not equal to one of the$constant-expressions$of the$case$labels.
|
|
|
|
If a$statement$is done, the following$statements$are done until the end of
|
|
the$switch$statement is reached or a$break$is done.
|
|
|
|
There can be several$case$labels, but only one$default$label. The order is
|
|
arbitrary.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.6.3 while Loop *crv-stWhile*
|
|
*crv-while*
|
|
Syntax: $while (expr1)$
|
|
$ statement$
|
|
|
|
|
|
The$while$statement provides an iterative loop.
|
|
The loop body ($statement$) is executed as long as$expr1$is true (!=0). If
|
|
$expr1$is false (=0) the loop is finished.
|
|
The expression$expr1$is evaluated before$statement$is executed.
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.6.4 do-while Loop *crv-stDoWhile*
|
|
*crv-do*
|
|
Syntax: $do$
|
|
$ statement$
|
|
$while (expr1);$
|
|
|
|
|
|
The$do-while$statement provides an iterative loop.
|
|
The loop body ($statement$) is executed as long as$expr1$is true (!=0). If
|
|
$expr1$is false (=0) the loop is finished.
|
|
The expression$expr1$is evaluated after$statement$is executed (opposed to
|
|
$while$-loop).
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.6.5 for Loop *crv-stFor*
|
|
*crv-for*
|
|
Syntax: $for (expr1; expr2; expr3)$
|
|
$ statement$
|
|
|
|
The expressions$expr1$,$expr2$and$expr3$are optional.
|
|
|
|
|
|
The$for$statement provides an iterative loop.
|
|
|
|
$expr1$: This expression is evaluated once before the first execution of the
|
|
loop body. Usually this is used to initialize variables used in the
|
|
loop body (e.g. loop counter).
|
|
|
|
$expr2$: The loop body ($statement$) is executed as long as$expr2$is true
|
|
(!=0). If$expr2$is false (=0) the loop is finished.
|
|
If$expr2$is omitted, the expression is always true (infinite loop).
|
|
|
|
$expr3$: This expression is evaluated after each iteration.
|
|
|
|
The expression$expr2$is evaluated before$statement$is executed.
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.6.6 break *crv-stBreak*
|
|
*crv-break*
|
|
Syntax: $break;$
|
|
|
|
|
|
The$break$statement is used to immediately terminate the execution of the
|
|
enclosing$switch$,$for$,$while$or$do-while$statement.
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.6.7 continue *crv-stContinue*
|
|
*crv-continue*
|
|
Syntax: $continue;$
|
|
|
|
|
|
The$continue$statement is used to immediately jump to the end of the
|
|
enclosing$for$,$while$or$do-while$statement.
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.6.8 goto *crv-stGoto*
|
|
*crv-goto*
|
|
Syntax: $goto identifier;$
|
|
|
|
|
|
The$goto$statement causes an unconditional jump to a labeled statement
|
|
that is specified by$identifier$. The labeled statement must be in the scope
|
|
of the function containing the$goto$statement.
|
|
|
|
A$goto$statement is not allowed to jump past any declaration of objects.
|
|
Apart from this jumping into other blocks is allowed.
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.6.9 return *crv-stReturn*
|
|
*crv-return*
|
|
Syntax: $return expr1;$
|
|
|
|
$expr1$is optional
|
|
|
|
|
|
The$return$statement terminates execution of the current function and returns
|
|
control to its caller. If present,$expr1$is evaluated and its value is
|
|
returned to the calling function. If the type of$expr1$is not the same as
|
|
the type of the function, implicit type cast is done.
|
|
|
|
A$return$statement can appear anywhere in a function, several$return$
|
|
statements are allowed.
|
|
|
|
For functions of type$void$either a return without$expr1$must be given or
|
|
no$return$statement ($return;$and the enclosing$}$of the function are treated
|
|
as the same).
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.6.10 Null Statement *crv-stNull*
|
|
|
|
Syntax: $;$
|
|
|
|
|
|
A null statement performs no operation. A null statement is used in situations
|
|
where the grammar of C requires a statement, but the program needs no
|
|
operation.
|
|
|
|
Usage:
|
|
- supply an empty loop body
|
|
Example: >
|
|
char *strngPtr;
|
|
|
|
while (*stngPtr++ != 'a') // search first 'a' in string
|
|
;
|
|
<
|
|
- set a label just before the closing$}$
|
|
Example: >
|
|
....
|
|
}
|
|
end_loop: ;
|
|
}
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
I.7 Functions *crv-functions*
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.7.1 Definition *crv-fuDefinition*
|
|
|
|
$return-type function-name(parameter-list, ...) {$
|
|
$ statement...$
|
|
$}$
|
|
|
|
$return-type$ type of value returned by function
|
|
$function-name$ name of function
|
|
$parameter-list$ list of parameters passed to function
|
|
|
|
|
|
The$return-type$is the type the function returns. It can be any type except
|
|
array types or function types. If no value is returned,$void$must be used.
|
|
If$return-type$is omitted,$int$is assumed.
|
|
|
|
The$function-name$is the identifier under that a function can be called
|
|
(see |crv-gloIdentifier| for valid names).
|
|
|
|
The$parameter-list$specifies the parameters a function expects when called.
|
|
A function can have no parameter, a specific number of parameters or
|
|
a variable number of parameters.
|
|
|
|
- No Parameter
|
|
--------------
|
|
$parameter-list$must be$void$
|
|
Example: >
|
|
int Func(void)
|
|
{
|
|
...
|
|
return 0;
|
|
}
|
|
<
|
|
- One or More Parameters
|
|
------------------------
|
|
$parameter-list$is a comma separated list of parameter specifications.
|
|
Each parameter must be specified this way: $type-name identifier$
|
|
$type-name$ : type of the parameter, if omitted$int$is used
|
|
$identifier$: identifier under which this parameter can be referenced
|
|
within the function
|
|
Example: >
|
|
int Func(char ch, int cntr)
|
|
{
|
|
if ( (ch == 'q') || (cntr == 42) )
|
|
exit(0);
|
|
|
|
return 0;
|
|
}
|
|
<
|
|
- Variable Number of Parameters *crv-fuDefVarPara*
|
|
-------------------------------
|
|
$parameter-list$is a comma separated list of parameter specifications
|
|
ending with an ellipsis ($,...$).
|
|
Functions declared in$<stdarg.h>$can be used to access arguments.
|
|
|
|
Example: >
|
|
#include <stdarg.h>
|
|
#include <stdio.h>
|
|
|
|
|
|
void Func(int numOfArgs, ...)
|
|
{
|
|
int n;
|
|
va_list ap;
|
|
|
|
va_start(ap, numOfArgs); // initialize
|
|
|
|
for (n = 0; n < numOfArgs; n++)
|
|
printf("%d ", va_arg(ap, int)); // get next argument, type is int
|
|
|
|
printf("\n");
|
|
|
|
va_end(ap); // finish
|
|
}
|
|
|
|
|
|
int main(void)
|
|
{
|
|
Func(1, 100); // output is 100
|
|
Func(2, 100, 101); // output is 100 101
|
|
Func(3, 100, 101, 102); // output is 100 101 102
|
|
}
|
|
<
|
|
|
|
A parameter can be of any type. But parameters of array type or function type
|
|
are converted automatically to pointers.
|
|
Example: >
|
|
#include <stdio.h>
|
|
|
|
|
|
int Func2()
|
|
{
|
|
return 3;
|
|
}
|
|
|
|
|
|
void Func1(int n[3], int (*func)(void))
|
|
{
|
|
n[0] = 1;
|
|
n[1] = 2;
|
|
n[2] = func();
|
|
}
|
|
|
|
int main(void)
|
|
{
|
|
int n[3] = {5, 5, 5};
|
|
|
|
Func1(n, Func2);
|
|
|
|
printf("%d %d %d\n", n[0], n[1], n[2]); // output is 1 2 3
|
|
|
|
}
|
|
<
|
|
|
|
The only allowed storage class for a parameter is$register$.
|
|
All kinds of type qualifiers are allowed for parameters.
|
|
|
|
Arguments are passed by value, that means that a function receives a copy
|
|
of the argument's value.
|
|
The order of evaluation of arguments is not specified.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.7.2 Prototype *crv-fuPrototype*
|
|
|
|
$return-type function-name(parameter-list, ...);$
|
|
|
|
|
|
If a function is used before it's defined then it must be prototyped, so
|
|
that the compiler knows about return type and parameter types of the function,
|
|
else$int$is assumed for return type and parameter types.
|
|
|
|
A prototype is identical to the function header with the addition of an
|
|
ending$;$. Function prototypes need not use parameter identifiers. Only the
|
|
types are required.
|
|
|
|
Normally prototyping occurs at the beginning of a source code file or in a
|
|
header file.
|
|
|
|
|
|
Example: >
|
|
int Func(char ch);
|
|
|
|
|
|
int main(void)
|
|
{
|
|
if (Func1('q') == 2)
|
|
{
|
|
....
|
|
}
|
|
}
|
|
|
|
|
|
int Func(char ch)
|
|
{
|
|
...
|
|
}
|
|
<
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.7.3 Conversion *crv-fuConversion*
|
|
|
|
|
|
If a function is called the arguments must be of the same types as specified
|
|
in prototype. If not, conversions are done.
|
|
|
|
Example: >
|
|
void Func(int n, char c, long l);
|
|
|
|
int main(void)
|
|
{
|
|
char chr;
|
|
long a;
|
|
int b;
|
|
|
|
...
|
|
|
|
Func(chr, a, b); // chr is converted to type int
|
|
// a is converted to type char
|
|
// b is converted to type long
|
|
}
|
|
<
|
|
|
|
If no prototype is in scope when calling a function the following conversions
|
|
are done on the arguments:
|
|
- An argument of type$float$is converted to type$double$.
|
|
- If an$int$can represent all values of the original type, the value is
|
|
converted to an$int$. Otherwise it is converted to an$unsigned int$.
|
|
For most compilers this means: an argument of type$char$,$unsigned char$,
|
|
$short$,$unsigned short$is converted to type$int$.
|
|
|
|
This is called "argument promotion".
|
|
|
|
No other conversions are performed on arguments.
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.7.4 Storage Classes *crv-fuStorageClasses*
|
|
|
|
Implicitly functions do have the storage class$extern$. To limit the scope of
|
|
a function to a file$static$can be used.
|
|
|
|
Example$extern$: >
|
|
File 1 File 2
|
|
------ ------
|
|
|
|
int GetSolution(void) extern int GetSolution(void);
|
|
{
|
|
return 42;
|
|
} void Func(void)
|
|
{
|
|
if (GetSolution() == 42)
|
|
int main(void) {
|
|
{ ...
|
|
if (GetSolution() != 42) }
|
|
{ }
|
|
...
|
|
}
|
|
}
|
|
<
|
|
|
|
Example$static$: >
|
|
File
|
|
----
|
|
|
|
static int GetSolution(void) // can only be referenced within same file
|
|
{
|
|
return 42;
|
|
}
|
|
|
|
|
|
int main(void)
|
|
{
|
|
if (GetSolution() == 42)
|
|
{
|
|
...
|
|
}
|
|
}
|
|
<
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.7.5 Specifier *crv-fuSpecifier*
|
|
*crv-inline*
|
|
|
|
A function declared with an$inline$specifier is an inline function. This
|
|
suggests that calls to the function be as fast as possible. The extend to
|
|
which this suggestion is taken into account is implementation specific.
|
|
|
|
Normally$inline$means that the call to the function is replaced by the
|
|
function body. As a result of this there is no overhead for calling, but at
|
|
the expense of code size, since each call of the inline function is replaced
|
|
by it's function body.
|
|
|
|
For$main()$the$inline$specifier is not allowed.
|
|
|
|
Example: >
|
|
|
|
inline int Func(void)
|
|
{
|
|
...
|
|
return 42;
|
|
}
|
|
|
|
|
|
int main(void)
|
|
{
|
|
int a;
|
|
|
|
a = Func();
|
|
...
|
|
}
|
|
<
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.7.6 main() *crv-fuMain*
|
|
|
|
A program begins by calling the$main()$function and ends by exiting
|
|
the$main()$function. There is no prototype required for$main()$.
|
|
|
|
$main()$can be defined in two ways, either with no parameter
|
|
|
|
$ int main(void)$
|
|
$ {$
|
|
$ statements$
|
|
$ }$
|
|
|
|
or with two parameters
|
|
|
|
$ int main(int argc, char *argv[])$
|
|
$ {$
|
|
$ statements$
|
|
$ }$
|
|
|
|
The return type is type$int$.
|
|
|
|
The parameters do not have to be named$argc$and$argv$, but it is a common way
|
|
to do so.
|
|
|
|
Parameter$argc$is a nonnegative integer. If the value of$argc$is greater than
|
|
zero, the string pointed to by$argv[0]$is the program name. If the value
|
|
of$argc$is greater than one, the strings pointed to by$argv[1]$through
|
|
$argv[argc - 1]$represent the program parameters.
|
|
|
|
|
|
|
|
==============================================================================
|
|
I.8 Preprocessor *crv-preprocessor*
|
|
|
|
A preprocessor is the first pass of a compiler. It does perform macro
|
|
substitution, inclusion of files, conditional compilation and provides the
|
|
ability to pass control directives to the compiler.
|
|
|
|
A C-preprocessor directive is invoked by a$#$. Opposed to a C-statement a
|
|
C-preprocessor directive is NOT terminated by a semicolon ($;$), instead of
|
|
it is terminated by the new-line. To span a directive over several lines
|
|
the "line-escape"$\$can be used (see |crv-lngEscSeq|).
|
|
Example: >
|
|
#define MEAS_CYCLES (3 \
|
|
+ \
|
|
1)
|
|
<
|
|
is synonymical to: >
|
|
#define MEAS_CYCLES (3 + 1)
|
|
|
|
|
|
A C-preprocessor directive can be placed anywhere in a source file. The
|
|
directive is active from the line of invocation up to the end of source file.
|
|
|
|
|
|
In the following sections possible preprocessor directives and preprocessor
|
|
operators are described.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.8.1 Macros *crv-preMacros*
|
|
|
|
A macro is an identifier that is equated to a text or symbolic expression
|
|
to which it is to be expanded by the preprocessor.
|
|
|
|
*crv-preMacObj* *crv-preMacFunc*
|
|
There are two types of macros: macros without parameters, they are called
|
|
object-like macros and macros with parameters, they are called function-like
|
|
macros.
|
|
|
|
When using a macro each subsequent occurrence of the macro$identifier$within
|
|
source-file is replaced by its$replacement-list$, unless the macro occurs
|
|
inside of a comment, a literal string or a character constant.
|
|
|
|
A macro definition lasts until end of the source-file or until a corresponding
|
|
$#undef$is encountered.
|
|
|
|
Macros can be nested.
|
|
|
|
|
|
NOTE: It is not a good programming style to specify macro arguments that
|
|
use side effects. Macro parameters can be used several times within a macro,
|
|
that can cause unexpected behaviour.
|
|
Example: >
|
|
#define MIN(a, b) ( (a < b) ? a : b )
|
|
|
|
MIN(val1++, val2)
|
|
<
|
|
would be replaced: >
|
|
( (val1++ < val2) ? val1++ : val2 )
|
|
|
|
|
|
|
|
I.8.1.1 Definition #define *crv-preMacDef*
|
|
---------------------------
|
|
*crv-#define*
|
|
Syntax Object-Like Macro:
|
|
$#define identifier replacement-list newline$
|
|
|
|
Syntax Function-Like Macro:
|
|
$#define identifier(identifier-list) replacement-list newline$
|
|
|
|
|
|
Example of an object-like macro: >
|
|
#define CONST_ADD 42
|
|
#define FOREVER for(;;)
|
|
|
|
int main(void)
|
|
{
|
|
int a = 0;
|
|
|
|
FOREVER
|
|
{
|
|
a += CONST_ADD;
|
|
...
|
|
}
|
|
}
|
|
<
|
|
Example of a function-like macro: >
|
|
#define MIN(a, b) ( (a < b) ? a : b )
|
|
|
|
int main(void)
|
|
{
|
|
int x1, x2, x;
|
|
|
|
x1 = 2;
|
|
x2 = 5;
|
|
|
|
x = MIN(x1, x2);
|
|
}
|
|
<
|
|
Example of a nested macro: >
|
|
#define CONST1 ( 35 + CONST2 )
|
|
#define COSNT2 7
|
|
<
|
|
|
|
|
|
I.8.1.2 Cancellation #undef *crv-preMacCancel*
|
|
----------------------------
|
|
Syntax: $#undef identifier newline$ *crv-#undef*
|
|
|
|
A macro specified by$identifier$is no longer a macro name. If$identifier$is
|
|
currently no macro, this directive is ignored.
|
|
|
|
Example: >
|
|
#define CONST 5
|
|
|
|
int main(void)
|
|
{
|
|
...
|
|
a = CONST;
|
|
...
|
|
|
|
#undef CONST
|
|
|
|
a = CONST; // will cause an error at compilation time
|
|
}
|
|
<
|
|
|
|
|
|
I.8.1.3 # Operator *crv-preMac#Operator*
|
|
-------------------
|
|
*crv-#*
|
|
The preprocessor operator$#$converts an argument of a function-like macro to a
|
|
string literal.
|
|
|
|
Example: >
|
|
#define PRINT1(var) printf("Value of "#var" is: %d\n", var)
|
|
#define PRINT2(var) printf("Value of %s is: %d\n", #var, var)
|
|
|
|
int main(void)
|
|
{
|
|
int a = 2;
|
|
int b = 3;
|
|
|
|
PRINT1(a); // prints: Value of a is: 2
|
|
PRINT2(b); // prints: Value of b is: 3
|
|
}
|
|
|
|
|
|
|
|
I.8.1.4 ## Operator *crv-preMac##Operator*
|
|
--------------------
|
|
*crv-##*
|
|
The preprocessor operator$##$concatenates two tokens.
|
|
|
|
Example: >
|
|
#define PRINT(prefix, postfix) printf("Value is: %d\n", prefix ## postfix)
|
|
|
|
int main(void)
|
|
{
|
|
int varCar = 2;
|
|
int varHouse = 3;
|
|
|
|
PRINT(var, Car); // prints: Value is: 2
|
|
PRINT(var, House); // prints: Value is: 3
|
|
}
|
|
|
|
|
|
|
|
I.8.1.5 Predefined Macros *crv-preMacPredefined*
|
|
--------------------------
|
|
|
|
There is a set of predefined macro names. They are not allowed to be changed.
|
|
*crv-__DATA__*
|
|
$__DATA__$ This macro is evaluated to a string literal representing the
|
|
date when compilation of the current source-file began. Its
|
|
form is "Mmm dd yyyy". The names of the months are the same as
|
|
those generated by the$asctime()$function.
|
|
*crv-__FILE__*
|
|
$__FILE__$ This macro is evaluated to a string literal representing the
|
|
name of the current source-file.
|
|
*crv-__LINE__*
|
|
$__LINE__$ This macro is evaluated to a decimal constant representing the
|
|
current line number.
|
|
*crv-__STDC__*
|
|
$__STDC__$ The integer constant 1. Used to indicate if this is a standard
|
|
C compiler.
|
|
|
|
$__STDC_HOSTED__$ *crv-__STDC_HOSTED__*
|
|
This macro is evaluated to an integer constant value. If 1
|
|
the compiler is hosted, if 0 it is not.
|
|
|
|
$__STDC_VERSION__$ *crv-__STDC_VERSION__*
|
|
This macro is evaluated to a$long int$value that belongs to the
|
|
revision of the International C Standard.
|
|
*crv-__TIME__*
|
|
$__TIME__$ This macro is evaluated to a string literal representing the
|
|
time when compilation of the current source-file began. Its
|
|
form is "hh:mm:ss", the same as what is generated the$asctime()$
|
|
function.
|
|
|
|
|
|
Furthermore the compiler conditionally provides the following macros:
|
|
|
|
$__STDC_IEC_559__$ *crv-__STDC_IEC_559__*
|
|
The integer constant 1. Used to indicate if this C compiler is
|
|
conform to the floating-point standard IEC 60559.
|
|
|
|
$__STDC_IEC_559_COMPLEX__$ *crv-__STDC_IEC_559_COMPLEX__*
|
|
The integer constant 1. Used to indicate if this C compiler's
|
|
complex arithmetic is conform to the floating-point standard
|
|
IEC 60559.
|
|
|
|
$__STDC_ISO_10646__$ *crv-__STDC_ISO10646__*
|
|
This macro is evaluated to a$long int$constant value of the
|
|
form yyyymm. Its intention is to indicate that values of
|
|
$wchar_t$are the coded representations of the characters defined
|
|
by ISO/IEC 10646. The year/month refers to the ISO/IEC 10646
|
|
including amendments and corrections this implementation is
|
|
conform to.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.8.2 Conditional Compilation *crv-preConditional*
|
|
|
|
There are preprocessor directives that allow to control which part of a
|
|
source-code is to be or is not to be translated (conditional compilation).
|
|
|
|
|
|
I.8.2.1 defined Operator *crv-preCondDefined*
|
|
-------------------------
|
|
*crv-defined*
|
|
Syntax: $defined identifier$
|
|
or$defined (identifier)$
|
|
|
|
|
|
The$defined$operator evaluates to 1 if$identifier$is defined, else it
|
|
evaluates to 0.$identifier$is a macro name.
|
|
|
|
$defined$operators can be combined in any logical expression using logical
|
|
operators (see |crv-opLogical|).
|
|
$defined$is allowed to be used in the expression of an$#if$or$#elif$directive.
|
|
|
|
|
|
Example: >
|
|
#if defined(MACRO1) || (defined(MACRO2) && !defined(MACRO3))
|
|
...
|
|
#endif
|
|
|
|
|
|
I.8.2.2 #if Directive *crv-preCondIf*
|
|
----------------------
|
|
*crv-#if*
|
|
Syntax: $#if constant-expression newline$
|
|
|
|
|
|
This preprocessor directive checks whether the constant expression evaluates
|
|
to nonzero. If so, the source-code between$#if$and the corresponding$#endif$,
|
|
$#else$or$#elif$is passed to compiler, else it's skipped.
|
|
|
|
The constant expression may be a$defined$operator, a macro name or any
|
|
constant integer expression. Not allowed are type-casts, keywords or
|
|
expressions that need memory ($++$,$--$...).
|
|
If a macro name used in the constant expression does not exist, it's treated
|
|
as zero.
|
|
|
|
Example: >
|
|
#if defined(MACRO1) || (defined(MACRO2) && !defined(MACRO3))
|
|
...
|
|
#endif
|
|
|
|
#if (CONST_VALUE + 5 == 8)
|
|
... // its value is 8
|
|
#else
|
|
... // its value is not 8
|
|
#endif
|
|
|
|
|
|
|
|
I.8.2.3 #ifdef Directive *crv-preCondIfdef*
|
|
-------------------------
|
|
*crv-#ifdef*
|
|
Syntax: $#ifdef identifier newline$
|
|
|
|
|
|
This preprocessor directive checks whether the identifier is currently
|
|
defined. If so, the source-code between$#ifdef$and the corresponding$#endif$,
|
|
$#else$or$#elif$is passed to compiler, else it's skipped.
|
|
|
|
Example: >
|
|
#define DEBUG 1
|
|
|
|
#ifdef DEBUG
|
|
... // that is passed to the compiler
|
|
#endif
|
|
|
|
|
|
|
|
I.8.2.4 #ifndef Directive *crv-preCondIfndef*
|
|
--------------------------
|
|
*crv-#ifndef*
|
|
Syntax: $#ifndef identifier newline$
|
|
|
|
|
|
This preprocessor directive checks whether the identifier is currently not
|
|
defined. If so, the source-code between$#ifndef$and the corresponding$#endif$,
|
|
$#else$or$#elif$is passed to compiler, else it's skipped.
|
|
|
|
Example: >
|
|
#define DEBUG 1
|
|
|
|
#ifndef DEBUG
|
|
... // that is not passed to the compiler
|
|
#endif
|
|
|
|
|
|
|
|
I.8.2.5 #else Directive *crv-preCondElse*
|
|
------------------------
|
|
*crv-#else*
|
|
Syntax: $#else newline$
|
|
|
|
|
|
This directive is used together with$#if$,$#ifdef$or$#ifndef$. If the "if"
|
|
does not evaluate to nonzero, the source code between the matching$else$and
|
|
the$endif$is passed to compiler.
|
|
|
|
Example: >
|
|
#define DEBUG 1
|
|
|
|
#ifndef DEBUG
|
|
... // that is not passed to the compiler
|
|
#else
|
|
... // that is passed to the compiler
|
|
#endif
|
|
|
|
|
|
|
|
I.8.2.6 #elif Directive *crv-preCondElif*
|
|
------------------------
|
|
*crv-#elif*
|
|
Syntax: $#elif constant-expression newline$
|
|
|
|
|
|
This directive provides an else-if statement. It can be used together
|
|
with$#if$,$#ifdef$,$#ifndef$or another$#elif$. If the corresponding "if" does
|
|
not evaluate to nonzero the$#elif$'s constant expression is tested to be
|
|
nonzero. If so, the source-code between$#elif$and the matching$#else$,$#elif$
|
|
or$#endif$is passed to the compiler, else not.
|
|
|
|
See |crv-preCondIf| for further information on the constant expression.
|
|
|
|
Example: >
|
|
#if (CONST_VALUE + 5 == 8)
|
|
... // its value is 8
|
|
#elif (CONST_VALUE + 5 == 9)
|
|
... // its value is 9
|
|
#endif
|
|
|
|
|
|
|
|
I.8.2.7 #endif Directive *crv-preCondEndif*
|
|
-------------------------
|
|
*crv-#endif*
|
|
Syntax: $#endif newline$
|
|
|
|
|
|
This directive is used to finish one of this directives:$#if$,$#ifdef$,
|
|
$#ifndef$,$elif$or$else$.
|
|
|
|
|
|
Example: >
|
|
#ifdef DEBUG
|
|
...
|
|
#endif
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.8.3 File Inclusion #include *crv-preSourceInc*
|
|
*crv-#include*
|
|
Syntax: $#include "filename" newline$ (1)
|
|
$#include <filename> newline$ (2)
|
|
$#include macro-name newline$ (3)
|
|
|
|
|
|
This preprocessor directive causes the replacement of that directive by the
|
|
entire contents of the file specified by$filename$.
|
|
|
|
Files enclosed in <...> are searched in an implementation-defined manner.
|
|
Files enclosed in quotes "..." are searched in an implementation-defined
|
|
manner too, if a file is not found it is searched in the same way like
|
|
files enclosed in <...>.
|
|
|
|
In general, form (1) is used to include user files whereas form (2) is used
|
|
to include standard library files.
|
|
|
|
This directive does support macro replacement (form (3)).
|
|
|
|
Nesting is allowed, an included file may itself contain$#include$directives.
|
|
But nesting easy leads to the situation that files are included several times,
|
|
which would waste time and may cause compilation errors. There is a standard
|
|
way to prevent that a file is included twice due to nesting. It is called
|
|
"wrapper #ifndef". Do the following in included files to avoid processing
|
|
them twice: >
|
|
// file foo.h
|
|
|
|
#ifndef _FOO_H_
|
|
#define _FOO_H_
|
|
|
|
... the entire file
|
|
|
|
#endif // #endif of _FOO_H_
|
|
|
|
|
|
Example: >
|
|
#include <stdio.h>
|
|
|
|
#include "galer.h"
|
|
|
|
|
|
#define HEADER_FILE "datatype.h"
|
|
|
|
#include HEADER_FILE
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.8.4 Line Control #line *crv-preLine*
|
|
*crv-#line*
|
|
Syntax: $#line digit-sequence newline$ (1)
|
|
$#line digit-sequence "filename" newline$ (2)
|
|
$#line macro-names newline$ (3)
|
|
|
|
|
|
This preprocessor directive allows to change the current line number and/or
|
|
the name of the current source-code file.
|
|
|
|
The$#line$directive gives the next line in source-code a new line-number.
|
|
The line numbers of the subsequent lines are derived from this number by
|
|
incrementing for each new line.
|
|
The new line-number is specified by$digit-sequence$. Line numbers must be
|
|
in the range of 1 to 2147483647.
|
|
|
|
Furthermore for the current source-code file a new filename can be specified
|
|
($filename$).
|
|
|
|
Form (1) can be used to set a new line number. Form (2) can be used to set
|
|
both, a new line number and a new filename.
|
|
In form (3) the macro-names are expanded, the result must match either
|
|
form (1) or (2). Its then processed appropriate.
|
|
|
|
The$#line$directive effects the predefined macros$#__LINE__$and$#__FILE__$.
|
|
|
|
Example: >
|
|
#line 1000 "GALer.c"
|
|
or >
|
|
#define NEW_LINE_NUMBER 1000
|
|
#define SOURCE "GALer.c"
|
|
|
|
#line NEW_LINE_NUMBER SOURCE
|
|
printf("%d %s\n", __LINE__, __FILE__); // result is: 1000 GALer.c
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.8.5 Error Directive #error *crv-preError*
|
|
*crv-#error*
|
|
Syntax: $#error message newline$
|
|
|
|
$message$is optional
|
|
|
|
|
|
This preprocessor directive causes the compiler to print a diagnostic message
|
|
that includes$message$and cancel compilation.
|
|
|
|
Example: >
|
|
#if defined UNIX
|
|
...
|
|
#elif defined LINUX
|
|
...
|
|
#elif
|
|
#error Error: no system specified
|
|
#endif
|
|
<
|
|
If neither UNIX nor LINUX is defined, the compiler prints an error message:
|
|
"Error: no system specified" and cancels compilation.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.8.6 Pragma Directive #pragma *crv-prePragma*
|
|
*crv-#pragma*
|
|
Syntax: $#pragma directive newline$
|
|
|
|
|
|
This preprocessor directive provides further control over the compiler. Which
|
|
$#pragma$directives an implementation provides is implementation specific.
|
|
If a$#pragma$directive is not known by the implementation, it is ignored.
|
|
|
|
|
|
Example: >
|
|
#pragma Int16 // use 16 bit integer for this file
|
|
|
|
#pragma DISABLE_WARNING_32 // disable warning 32 for this file
|
|
... do stuff that would cause a warning 32
|
|
#pragma ENABLE_WARNING_32
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
I.8.7 Null Directive # *crv-preNull*
|
|
|
|
Syntax: $# newline$
|
|
|
|
The preprocessor directive of the form$# newline$has no effect.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
Chapter II STANDARD C LIBRARY *crv-stdCLib*
|
|
==============================================================================
|
|
|
|
The C language provides no built-in facilities for performing such common
|
|
operations as input/output, memory management, string manipulation, and the
|
|
like. Instead, these facilities are defined in a standard C library which can
|
|
be linked to program.
|
|
Subject of this chapter is the standard C library as specified by the ISO C
|
|
standard.
|
|
|
|
|
|
==============================================================================
|
|
II.1 Standard Headers *crv-libHeaders*
|
|
|
|
Below is an alphabetically sorted list of all header files of the standard C
|
|
library.
|
|
|
|
Header | Short Description
|
|
--------------+-----------------------------------------------------------
|
|
$<assert.h> $| diagnostics.............................|crv-libAssertH|
|
|
$<complex.h> $| complex arithmetic......................|crv-libComplexH|
|
|
$<ctype.h> $| character handling......................|crv-libCtypeH|
|
|
$<errno.h> $| error codes.............................|crv-libErrnoH|
|
|
$<fenv.h> $| floating point environment..............|crv-libFenvH|
|
|
$<float.h> $| characteristics of floating point types.|crv-libFloatH|
|
|
$<inttypes.h>$| format conversion of integer types......|crv-libInttypesH|
|
|
$<iso646.h> $| alternative spelling....................|crv-libIso646H|
|
|
$<limits.h> $| sizes of integer types..................|crv-libLimitsH|
|
|
$<local.h> $| localization............................|crv-libLocalH|
|
|
$<math.h> $| mathematics.............................|crv-libMathH|
|
|
$<setjmp.h> $| nonlocal jumps..........................|crv-libSetjmpH|
|
|
$<signal.h> $| signal handling.........................|crv-libSignalH|
|
|
$<stdarg.h> $| variable arguments......................|crv-libStdargH|
|
|
$<stdbool.h> $| boolean type and values.................|crv-libStdboolH|
|
|
$<stddef.h> $| common definitions......................|crv-libStddefH|
|
|
$<stdint.h> $| integer types...........................|crv-libStdintH|
|
|
$<stdio.h> $| input / output..........................|crv-libStdioH|
|
|
$<stdlib.h> $| general utilities.......................|crv-libStdlibH|
|
|
$<string.h> $| string handling.........................|crv-libStringH|
|
|
$<tgmath.h> $| type-generic math.......................|crv-libTgmathH|
|
|
$<time.h> $| date and time...........................|crv-libTimeH|
|
|
$<wchar.h> $| extended multibyte and wide.............|crv-libWcharH|
|
|
| character utilities
|
|
$<wctype.h> $| wide character classification and.......|crv-libWctypeH|
|
|
| mapping utilities
|
|
|
|
|
|
|
|
==============================================================================
|
|
II.2 <assert.h> Diagnostics *crv-libAssertH*
|
|
|
|
Quicklink:
|
|
$assert()$ Macro |crv-assert|
|
|
$NDEBUG$ Macro |crv-NDEBUG|
|
|
|
|
|
|
assert() Macro *crv-assert* *crv-NDEBUG*
|
|
--------------
|
|
Synopsis~
|
|
$#include <assert.h>$
|
|
$void assert (int expression);$
|
|
|
|
Return~
|
|
none
|
|
|
|
Description~
|
|
The macro$assert()$tests the value of$expression$. If it is false (zero),
|
|
the$assert()$macro writes the following information on the standard error
|
|
stream:
|
|
- text of argument
|
|
- name of source file
|
|
- line number
|
|
- name of the enclosing function
|
|
The format of output is implementation-defined. After writing this information
|
|
the program is terminated by calling the$abort()$function.
|
|
|
|
If the macro$NDEBUG$is defined before including$<assert.h>$,$assert()$is
|
|
defined as follows:
|
|
$#define assert(ignore) ((void)0)$
|
|
This means that the macro has no effect,$expression$is even not evaluated.
|
|
|
|
Note: The assert facility is designed for detecting internal inconsistency;
|
|
it is not suitable for reporting invalid input or improper usage by the user
|
|
of the program.
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
II.3 <complex.h> Complex Math *crv-libComplexH*
|
|
|
|
This header file defines macros and declares functions that allow to do
|
|
complex arithmetic.
|
|
|
|
Quicklink:
|
|
$_Complex_I$ Macro |crv-_Complex_I|
|
|
$_Imaginary_I$ Macro |crv-_Imaginary_I|
|
|
$cabs()$ Func |crv-cabs|
|
|
$cabsf()$ Func |crv-cabsf|
|
|
$cabsl()$ Func |crv-cabsl|
|
|
$cacos()$ Func |crv-cacos|
|
|
$cacosf()$ Func |crv-cacosf|
|
|
$cacosl()$ Func |crv-cacosl|
|
|
$casin()$ Func |crv-casin|
|
|
$casinf()$ Func |crv-casinf|
|
|
$casinl()$ Func |crv-casinl|
|
|
$catan()$ Func |crv-catan|
|
|
$catanf()$ Func |crv-catanf|
|
|
$catanl()$ Func |crv-catanl|
|
|
$cacosh()$ Func |crv-cacosh|
|
|
$cacoshf()$ Func |crv-cacoshf|
|
|
$cacoshl()$ Func |crv-cacoshl|
|
|
$carg()$ Func |crv-carg|
|
|
$cargf()$ Func |crv-cargf|
|
|
$cargl()$ Func |crv-cargl|
|
|
$casinh()$ Func |crv-casinh|
|
|
$casinhf()$ Func |crv-casinhf|
|
|
$casinhl()$ Func |crv-casinhl|
|
|
$catanh()$ Func |crv-catanh|
|
|
$catanhf()$ Func |crv-catanhf|
|
|
$catanhl()$ Func |crv-catanhl|
|
|
$ccos()$ Func |crv-ccos|
|
|
$ccosf()$ Func |crv-ccosf|
|
|
$ccosl()$ Func |crv-ccosl|
|
|
$ccosh()$ Func |crv-ccosh|
|
|
$ccoshf()$ Func |crv-ccoshf|
|
|
$ccoshl()$ Func |crv-ccoshl|
|
|
$cexp()$ Func |crv-cexp|
|
|
$cexpf()$ Func |crv-cexpf|
|
|
$cexpl()$ Func |crv-cexpl|
|
|
$cimag()$ Func |crv-cimag|
|
|
$cimagf()$ Func |crv-cimagf|
|
|
$cimagl()$ Func |crv-cimagl|
|
|
$clog()$ Func |crv-clog|
|
|
$clogf()$ Func |crv-clogf|
|
|
$clogl()$ Func |crv-clogl|
|
|
$conj()$ Func |crv-conj|
|
|
$conjf()$ Func |crv-conjf|
|
|
$conjl()$ Func |crv-conjl|
|
|
$cpow()$ Func |crv-cpow|
|
|
$cpowf()$ Func |crv-cpowf|
|
|
$cpowl()$ Func |crv-cpowl|
|
|
$cproj()$ Func |crv-cproj|
|
|
$cprojf()$ Func |crv-cprojf|
|
|
$cprojl()$ Func |crv-cprojl|
|
|
$creal()$ Func |crv-creal|
|
|
$crealf()$ Func |crv-crealf|
|
|
$creall()$ Func |crv-creall|
|
|
$csinh()$ Func |crv-csinh|
|
|
$csin()$ Func |crv-csin|
|
|
$csinf()$ Func |crv-csinf|
|
|
$csinl()$ Func |crv-csinl|
|
|
$csinh()$ Func |crv-csinh|
|
|
$csinhf()$ Func |crv-csinhf|
|
|
$csinhl()$ Func |crv-csinhl|
|
|
$csqrt()$ Func |crv-csqrt|
|
|
$csqrtf()$ Func |crv-csqrtf|
|
|
$csqrtl()$ Func |crv-csqrtl|
|
|
$ctan()$ Func |crv-ctan|
|
|
$ctanf()$ Func |crv-ctanf|
|
|
$ctanl()$ Func |crv-ctanl|
|
|
$ctanh()$ Func |crv-ctanh|
|
|
$ctanhf()$ Func |crv-ctanhf|
|
|
$ctanhl()$ Func |crv-ctanhl|
|
|
$complex$ Macro |crv-complex|
|
|
$CX_LIMITED_RANGE$ Pragma |crv-CX_LIMITED_RANGE|
|
|
$I$ Macro |crv-I|
|
|
$imaginary$ Macro |crv-imaginary|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.3.1 Macros *crv-libCHMac*
|
|
|
|
|
|
_Complex_I Macro *crv-_Complex_I*
|
|
----------------
|
|
This macro expands to$const float _Complex$with the complex number "0+1i".
|
|
|
|
|
|
_Imaginary_I Macro *crv-_Imaginary_I*
|
|
------------------
|
|
This macro is defined only if the compiler supports imaginary types.
|
|
If defined, it expands to$_Imaginary$and a constant expression of the type
|
|
$const float _Imaginary$with the value "0+1i".
|
|
|
|
|
|
complex Macro *crv-complex*
|
|
-------------
|
|
This macro expands to$_Complex$.
|
|
|
|
|
|
I Macro *crv-I*
|
|
-------
|
|
This macro either expands to$_Imaginary_I$or$_Complex_I$. If$_Imaginary_I$is
|
|
not defined$I$expands to$_Complex_I$.
|
|
|
|
|
|
imaginary Macro *crv-imaginary*
|
|
---------------
|
|
This macro is defined only if the compiler supports imaginary types.
|
|
If defined, it expands to$_Imaginary$and a constant expression of the type
|
|
$const float _Imaginary$with the value "0+1i".
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.3.2 Pragmas *crv-libCHPrag*
|
|
|
|
|
|
CX_LIMITED_RANGE Pragma *crv-CX_LIMITED_RANGE*
|
|
-----------------------
|
|
Synopsis~
|
|
$#include <complex.h>$
|
|
$#pragma STDC CX_LIMITED_RANGE on/off-switch$
|
|
|
|
$on/off-switch$is$ON$,$OFF$or$DEFAULT$
|
|
|
|
Description~
|
|
Complex arithmetic is problematic because of their treatment of infinities
|
|
and because of undue overflow and underflow.
|
|
If this pragma is on the compiler is informed that the usual mathematical
|
|
formulas can be used. If on, the compiler can use this formulas:
|
|
(x + iy)x(u + iv) = (xu - yv) + i(yu + xv)
|
|
|
|
(x + iy) / ( u + iv) = [(xu + yv) + i(yu - xv)] / (u^2 + v^2)
|
|
|
|
-----------
|
|
| x + iy | = \| x^2 + y^2
|
|
|
|
When inside a compound statement, the pragma takes effect from its occurrence
|
|
until end of compound statement or until the next$CX_LIMITED_RANGE$is
|
|
encountered; at the end of a compound statement the state of the pragma is
|
|
restored to its state just before entering that compound statement.
|
|
When outside a compound statement, the pragma takes effect from its occurrence
|
|
until end of source-file or until the next$CX_LIMITED_RANGE$is encountered.
|
|
The default state of this pragma is off.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.3.3 Trigonometric *crv-libCHTrig*
|
|
|
|
|
|
cacos() Functions *crv-cacos* *crv-cacosf* *crv-cacosl*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <complex.h>$
|
|
$double complex cacos(double complex z);$
|
|
$float complex cacosf(float complex z);$
|
|
$long double complex cacosl(long double complex z);$
|
|
|
|
Return~
|
|
return complex arc cosine of z in radians
|
|
Values: imaginary is unbounded, real is in the interval [0, PI]
|
|
|
|
Description~
|
|
These functions compute the complex arc cosine of z, with branch cuts outside
|
|
the interval [-1, +1] along real axis.
|
|
|
|
|
|
|
|
casin() Functions *crv-casin* *crv-casinf* *crv-casinl*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <complex.h>$
|
|
$double complex casin(double complex z);$
|
|
$float complex casinf(float complex z);$
|
|
$long double complex casinl(long double complex z);$
|
|
|
|
Return~
|
|
return complex arc sine of z in radians
|
|
Range: imaginary is unbounded, real is in the interval [-PI/2, +PI/2]
|
|
|
|
Description~
|
|
These functions compute the complex arc sine of z, with branch cuts outside
|
|
the interval [-1, +1] along real axis
|
|
|
|
|
|
|
|
catan() Functions *crv-catan* *crv-catanf* *crv-catanl*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <complex.h>$
|
|
$double complex catan(double complex z);$
|
|
$float complex catanf(float complex z);$
|
|
$long double complex catanl(long double complex z);$
|
|
|
|
Return~
|
|
return complex arc tangent of z in radians
|
|
Range: imaginary is unbounded, real is in the interval [-PI/2, +PI/2]
|
|
|
|
Description~
|
|
These functions compute the complex arc tangent of z, with branch cuts outside
|
|
the interval [-i, +i] along imaginary axis.
|
|
|
|
|
|
|
|
ccos() Functions *crv-ccos* *crv-ccosf* *crv-ccosl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <complex.h>$
|
|
$double complex ccos(double complex z);$
|
|
$float complex ccosf(float complex z);$
|
|
$long double complex ccosl(long double complex z);$
|
|
|
|
Return~
|
|
return complex cosine of z
|
|
|
|
Description~
|
|
These functions compute the complex cosine of z.
|
|
The mathematical definition of the complex cosine is:
|
|
cos(z) = 1/2 * (exp(z*i) + exp(-z*i))
|
|
|
|
|
|
|
|
csin() Functions *crv-csin* *crv-csinf* *crv-csinl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <complex.h>$
|
|
$double complex csin(double complex z);$
|
|
$float complex csinf(float complex z);$
|
|
$long double complex csinl(long double complex z);$
|
|
|
|
Return~
|
|
return complex sine of z
|
|
|
|
Description~
|
|
These functions compute the complex sine of z.
|
|
The mathematical definition of the complex sine is:
|
|
sin(z) = 1/(2*i) * (exp(z*i) - exp(-z*i))
|
|
|
|
|
|
|
|
ctan() Functions *crv-ctan* *crv-ctanf* *crv-ctanl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <complex.h>$
|
|
$double complex ctan(double complex z);$
|
|
$float complex ctanf(float complex z);$
|
|
$long double complex ctanl(long double complex z);$
|
|
|
|
Return~
|
|
return complex tangent of z
|
|
|
|
Description~
|
|
These functions compute the complex tangent of z.
|
|
The mathematical definition of the complex tangent is:
|
|
tan(z) = -i * (exp(z*i) - exp(-z*i)) / (exp(z*i) + exp(-z*i))
|
|
|
|
NOTE: The complex tangent has poles at PI/2 + 2n, where n is an integer.
|
|
$ctan()$may signal overflow if z is too close to a pole.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.3.4 Hyperbolic *crv-libCHHyper*
|
|
|
|
|
|
cacosh() Functions *crv-cacosh* *crv-cacoshf* *crv-cacoshl*
|
|
------------------
|
|
Synopsis~
|
|
$#include <complex.h>$
|
|
$double complex cacosh(double complex z);$
|
|
$float complex cacoshf(float complex z);$
|
|
$long double complex cacoshl(long double complex z);$
|
|
|
|
Return~
|
|
return complex arc hyperbolic cosine of z
|
|
Range: real is >= 0, imaginary is [-iPI, +iPI]
|
|
|
|
Description~
|
|
These functions compute the complex arc hyperbolic cosine of z.
|
|
Domain: real of z >= 1
|
|
|
|
|
|
|
|
casinh() Functions *crv-casinh* *crv-casinhf* *crv-casinhl*
|
|
------------------
|
|
Synopsis~
|
|
$#include <complex.h>$
|
|
$double complex casinh(double complex z);$
|
|
$float complex casinhf(float complex z);$
|
|
$long double complex casinhl(long double complex z);$
|
|
|
|
Return~
|
|
return complex arc hyperbolic sine of z
|
|
Range: real is unbounded, imaginary is [-iPI/2, +iPI/2]
|
|
|
|
Description~
|
|
These functions compute the complex arc hyperbolic sine of z.
|
|
Domain: imaginary in range [-i, +i]
|
|
|
|
|
|
|
|
catanh() Functions *crv-catanh* *crv-catanhf* *crv-catanhl*
|
|
------------------
|
|
Synopsis~
|
|
$#include <complex.h>$
|
|
$double complex catanh(double complex z);$
|
|
$float complex catanhf(float complex z);$
|
|
$long double complex catanhl(long double complex z);$
|
|
|
|
Return~
|
|
return complex arc hyperbolic tangent of z
|
|
Range: imaginary is unbounded, real is [-PI/2, +PI/2]
|
|
|
|
Description~
|
|
These functions compute the complex arc hyperbolic tangent of z.
|
|
Domain: real in range [-1, +1]
|
|
|
|
|
|
|
|
ccosh() Functions *crv-ccosh* *crv-ccosfh* *crv-ccoslh*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <complex.h>$
|
|
$double complex ccosh(double complex z);$
|
|
$float complex ccoshf(float complex z);$
|
|
$long double complex ccoshl(long double complex z);$
|
|
|
|
Return~
|
|
return complex hyperbolic cosine of z
|
|
|
|
Description~
|
|
These functions compute the complex hyperbolic cosine of z.
|
|
The mathematical definition of the complex hyperbolic cosine is:
|
|
cosh(z) = 1/2 * (exp(z) + exp(-z))
|
|
|
|
|
|
|
|
csinh() Functions *crv-csinh* *crv-csinhf* *crv-csinhl*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <complex.h>$
|
|
$double complex csinh(double complex z);$
|
|
$float complex csinhf(float complex z);$
|
|
$long double complex csinhl(long double complex z);$
|
|
|
|
Return~
|
|
return complex hyperbolic sine of z
|
|
|
|
Description~
|
|
These functions compute the complex hyperbolic sine of z.
|
|
The mathematical definition of the complex hyperbolic sine is:
|
|
sinh(z) = 1/2 * (exp(z) - exp(-z)) / 2
|
|
|
|
|
|
|
|
ctanh() Functions *crv-ctanh* *crv-ctanhf* *crv-ctanhl*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <complex.h>$
|
|
$double complex ctanh(double complex z);$
|
|
$float complex ctanhf(float complex z);$
|
|
$long double complex ctanhl(long double complex z);$
|
|
|
|
Return~
|
|
return complex hyperbolic tangent of z
|
|
|
|
Description~
|
|
These functions compute the complex hyperbolic tangent of z.
|
|
The mathematical definition of the complex hyperbolic tangent is:
|
|
tanh(z) = sinh(z) / cosh(z)
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.3.5 Exponential & Logarithmic *crv-libCHExpLog*
|
|
|
|
|
|
cexp() Functions *crv-cexp* *crv-cexpf* *crv-cexpl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <complex.h>$
|
|
$double complex cexp(double complex z);$
|
|
$float complex cexpf(float complex z);$
|
|
$long double complex cexpl(long double complex z);$
|
|
|
|
Return~
|
|
return complex base e exponential of z
|
|
|
|
Description~
|
|
These functions compute e (the base of natural logarithms) raised to the power
|
|
of z. Mathematically, this corresponds to the value
|
|
|
|
exp(z) = exp(creal(z)) * (cos(cimag(z)) + I * sin(cimag(z)))
|
|
|
|
|
|
|
|
clog() Functions *crv-clog* *crv-clogf* *crv-clogl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <complex.h>$
|
|
$double complex clog(double complex z);$
|
|
$float complex clogf(float complex z);$
|
|
$long double complex clogl(long double complex z);$
|
|
|
|
Return~
|
|
return complex natural logarithm of z
|
|
Range: real > 0
|
|
|
|
Description~
|
|
These functions compute the complex natural logarithm of z (base e).
|
|
Domain: imaginary is [-iPI, +iPI], real is unbounded
|
|
|
|
The mathematical definition is:
|
|
log(z) = log(cabs(z)) + I * carg(z)
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.3.6 Power & Absolute *crv-libCHPower*
|
|
|
|
|
|
cabs() Functions *crv-cabs* *crv-cabsf* *crv-cabsl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <complex.h>$
|
|
$double cabs(double complex z);$
|
|
$float cabsf(float complex z);$
|
|
$long double cabsl(long double complex z);$
|
|
|
|
Return~
|
|
return absolute value of z
|
|
|
|
Description~
|
|
These functions compute the absolute value of the complex number z.
|
|
|
|
------------------------
|
|
absolute value = \|creal(z)^2 + cimag(z)^2
|
|
|
|
|
|
|
|
cpow() Functions *crv-cpow* *crv-cpowf* *crv-cpowl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <complex.h>$
|
|
$double complex cpow(double complex base, double complex power);$
|
|
$float complex cpowf(float complex base, double complex power);$
|
|
$long double complex cpowl(long double complex base,$
|
|
$ long doubl complex power);$
|
|
|
|
Return~
|
|
return complex power of z
|
|
|
|
Description~
|
|
These functions compute the complex power function x^y
|
|
($base$raised to the power$power$).
|
|
|
|
This is equivalent to:
|
|
exp(y * log(x))
|
|
|
|
|
|
|
|
csqrt() Functions *crv-csqrt* *crv-csqrtf* *crv-csqrtl*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <complex.h>$
|
|
$double complex csqrt(double complex z);$
|
|
$float complex csqrtf(float complex z);$
|
|
$long double complex csqrtl(long double complex z);$
|
|
|
|
Return~
|
|
return complex square root of z
|
|
Range: real >= 0
|
|
|
|
Description~
|
|
These functions compute the complex square root of z.
|
|
Domain: imaginary unbounded, real >= 0
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.3.7 Manipulating *crv-libCHMani*
|
|
|
|
|
|
carg() Functions *crv-carg* *crv-cargf* *crv-cargl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <complex.h>$
|
|
$double carg(double complex z);$
|
|
$float cargf(float complex z);$
|
|
$long double cargl(long double complex z);$
|
|
|
|
Return~
|
|
return argument of z
|
|
Range: [-PI, +PI]
|
|
|
|
Description~
|
|
These functions compute the argument of the complex number z.
|
|
The argument of a complex number is the angle in the complex plane between the
|
|
positive real axis and a line passing through zero and the number.
|
|
Domain: branch cut along the positive real axis
|
|
|
|
|
|
|
|
cimag() Functions *crv-cimag* *crv-cimagf* *crv-cimagl*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <complex.h>$
|
|
$double cimag(double complex z);$
|
|
$float cimagf(float complex z);$
|
|
$long double cimagl(long double complex z);$
|
|
|
|
Return~
|
|
return imaginary part of z
|
|
|
|
Description~
|
|
These functions compute the imaginary part of the complex number z.
|
|
|
|
|
|
|
|
conj() Functions *crv-conj* *crv-conjf* *crv-conjl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <complex.h>$
|
|
$double complex conj(double complex z);$
|
|
$float complex conjf(float complex z);$
|
|
$long double complex conjl(long double complex z);$
|
|
|
|
Return~
|
|
return complex conjugate value of z
|
|
|
|
Description~
|
|
These functions compute the complex conjugate of the complex number z.
|
|
The conjugate of a complex number has the same real part and a negated
|
|
imaginary part. In other words, conj(a + bi) = a + -bi.
|
|
|
|
|
|
|
|
cproj() Functions *crv-cproj* *crv-cprojf* *crv-cprojl*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <complex.h>$
|
|
$double complex cproj(double complex z);$
|
|
$float complex cprojf(float complex z);$
|
|
$long double complex cprojl(long double complex z);$
|
|
|
|
Return~
|
|
return value of projection onto the Riemann sphere
|
|
|
|
Description~
|
|
These functions compute the projection of the complex value z onto the Riemann
|
|
sphere. Values with a infinite imaginary part are projected to positive
|
|
infinity on the real axis, even if the real part is NaN. If the real part is
|
|
infinite, the result is equivalent to
|
|
INFINITY + I * copysign (0.0, cimag(z))
|
|
|
|
|
|
|
|
creal() Functions *crv-creal* *crv-crealf* *crv-creall*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <complex.h>$
|
|
$double creal(double complex z);$
|
|
$float crealf(float complex z);$
|
|
$long double creall(long double complex z);$
|
|
|
|
Return~
|
|
return real part of z
|
|
|
|
Description~
|
|
These functions compute the real part of the complex number z.
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
II.4 <ctype.h> Character *crv-libCtypeH*
|
|
|
|
|
|
This header declares functions useful for case mapping and classifying
|
|
characters.
|
|
|
|
Quicklink:
|
|
$isalnum()$ Func |crv-isalnum|
|
|
$isalpha()$ Func |crv-isalpha|
|
|
$isblank()$ Func |crv-isblank|
|
|
$iscntrl()$ Func |crv-iscntrl|
|
|
$isdigit()$ Func |crv-isdigit|
|
|
$isgraph()$ Func |crv-isgraph|
|
|
$islower()$ Func |crv-islower|
|
|
$isprint()$ Func |crv-isprint|
|
|
$ispunct()$ Func |crv-ispunct|
|
|
$isspace()$ Func |crv-isspace|
|
|
$isupper()$ Func |crv-isupper|
|
|
$isxdigit()$ Func |crv-isxdigit|
|
|
$tolower()$ Func |crv-tolower|
|
|
$toupper()$ Func |crv-toupper|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.4.1 Character Handling *crv-libCharHandling*
|
|
|
|
Each of the functions in this section tests for membership in a particular
|
|
class of characters; each has a name starting with is. Each of them takes
|
|
one argument, which is a character to test, and returns an int which is
|
|
treated as a boolean value. The character argument is passed as an int,
|
|
and it may be the constant value EOF instead of a real character.
|
|
|
|
The attributes of any given character can vary between locales.
|
|
|
|
|
|
$int isalnum(int c);$ *crv-isalnum*
|
|
Returns true if c is an alphanumeric character (a letter or number); in
|
|
other words, if either$isalpha$or$isdigit$is true of a character, then
|
|
$isalnum$ is also true.
|
|
|
|
|
|
$int isalpha(int c);$ *crv-isalpha*
|
|
Returns true if c is an alphabetic character (a letter). If$islower$or
|
|
$isupper$is true of a character, then$isalpha$is also true.
|
|
It returns also true, if c is one of a local-specific set of characters for
|
|
which none of$iscntrl$,$isdigt$,$ispunct$ or$isspcace$is true.
|
|
|
|
In some locales, there may be additional characters for which isalpha
|
|
is true - letters which are neither upper case nor lower case. But in
|
|
the standard C locale, there are no such additional characters.
|
|
|
|
|
|
$int isblank(int c);$ *crv-isblank*
|
|
Returns true if c is a blank character; that is, a space or a tab.
|
|
|
|
|
|
$int iscntrl(int c);$ *crv-iscntrl*
|
|
Returns true if c is a control character (that is, a character that is
|
|
not a printing character).
|
|
|
|
|
|
$int isdigit(int c);$ *crv-isdigit*
|
|
Returns true if c is a decimal digit (0 through 9).
|
|
|
|
|
|
$int isgraph(int c);$ *crv-isgraph*
|
|
Returns true if c is a graphic character; that is any printing character
|
|
except a space character.
|
|
|
|
|
|
$int islower(int c);$ *crv-islower*
|
|
Returns true if c is a lower-case letter or is one of a local-specific set
|
|
of characters for which none of$iscntrl$,$isdigt$,$ispunct$ or$isspcace$is
|
|
true.
|
|
|
|
|
|
$int isprint(int c);$ *crv-isprint*
|
|
Returns true if c is a printing character. Printing characters include
|
|
all the graphic characters, plus the space (' ') character.
|
|
|
|
|
|
$int ispunct(int c);$ *crv-ispunct*
|
|
Returns true if c is a punctuation character. This means any printing
|
|
character for that is neither$isalnum$nor$isspace$is true (no
|
|
alphanumeric and no space character).
|
|
|
|
|
|
$int isspace(int c);$ *crv-isspace*
|
|
Returns true if c is a whitespace character. In the standard "C" locale,
|
|
$isspace$returns true for only the standard whitespace characters:
|
|
' ' space
|
|
'\f' formfeed
|
|
'\n' newline
|
|
'\r' carriage return
|
|
'\t' horizontal tab
|
|
'\v' vertical tab
|
|
|
|
|
|
$int isupper(int c);$ *crv-isupper*
|
|
Returns true if c is an upper-case letter or is one of a local-specific set
|
|
of characters for which none of$iscntrl$,$isdigt$,$ispunct$ or$isspcace$is
|
|
true.
|
|
|
|
|
|
$int isxdigit(int c);$ *crv-isxdigit*
|
|
Returns true if c is a hexadecimal digit. Hexadecimal digits include the
|
|
normal decimal digits 0 through 9 and the letters A through F and
|
|
a through f.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.4.2 Character Mapping *crv-libCharMapping*
|
|
|
|
This section explains the functions for performing case mappings on
|
|
characters.
|
|
These functions take one argument of type int, which is the character to
|
|
convert, and return the converted character as an int. If the conversion is
|
|
not applicable to the argument given, the argument is returned unchanged.
|
|
|
|
|
|
$int tolower(int c);$ *crv-tolower*
|
|
If c is an upper-case letter,$tolower$returns the corresponding lower-case
|
|
letter. If c is not an upper-case letter, c is returned unchanged.
|
|
|
|
$int toupper(int c);$ *crv-toupper*
|
|
If c is a lower-case letter,$toupper$returns the corresponding upper-case
|
|
letter. If c is not an lower-case letter, c is returned unchanged.
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
II.5 <errno.h> Error Codes *crv-libErrnoH*
|
|
|
|
This header file defines macros used for reporting of error conditions.
|
|
All macros expand to integer constant expressions of type$int$with distinct
|
|
positive values.
|
|
|
|
Additional macro definitions may be specified by the implementation. They
|
|
begin with E followed by digits or begin with E followed by uppercase letters.
|
|
|
|
|
|
EDOM Macro *crv-EDOM*
|
|
----------
|
|
Domain error; used by mathematical functions when an argument value does not
|
|
fall into the domain over which the function is defined.
|
|
|
|
|
|
EILSEQ Macro *crv-EILSEQ*
|
|
------------
|
|
While decoding a multibyte character the function came along an invalid or an
|
|
incomplete sequence of bytes or the given wide character is invalid.
|
|
|
|
|
|
ERANGE Macro *crv-ERANGE*
|
|
------------
|
|
Range error; used by mathematical functions when the result value is not
|
|
representable because of overflow or underflow.
|
|
|
|
|
|
errno Macro/Variable *crv-errno*
|
|
--------------------
|
|
$errno$is either a macro or an external variable of type int (implementation-
|
|
defined).
|
|
|
|
The$errno$variable is used for holding implementation-defined error codes
|
|
reported by library routines. See above for error code macros specified by the
|
|
standard C language.
|
|
The value of$errno$is set to 0 at program startup, but is never set to 0
|
|
by any library function. Therefore,$errno$should be set to 0 before calling a
|
|
library function and then inspected afterward.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.6 <fenv.h> FPU Status *crv-libFenvH*
|
|
|
|
This header declares types, macros and functions to provide access to the
|
|
floating-point environment (floating-point status word and control modes).
|
|
|
|
Quicklink:
|
|
$FE_ALL_EXCEPT$ Macro |crv-FE_ALL_EXCEPT|
|
|
$FE_DIVBYZERO$ Macro |crv-FE_DIVBYZERO|
|
|
$FE_DOWNWARD$ Macro |crv-FE_DOWNWARD|
|
|
$FE_INEXACT$ Macro |crv-FE_INEXACT|
|
|
$FE_INVALID$ Macro |crv-FE_INVALID|
|
|
$FE_OVERFLOW$ Macro |crv-FE_OVERFLOW|
|
|
$FE_TONEAREST$ Macro |crv-FE_TONEAREST|
|
|
$FE_TOWARDZERO$ Macro |crv-FE_TOWARDZERO|
|
|
$FE_UNDERFLOW$ Macro |crv-FE_UNDERFLOW|
|
|
$FE_UPWARD$ Macro |crv-FE_UPWARD|
|
|
$FENV_ACCESS$ Pragma |crv-FENV_ACCESS|
|
|
$feclearexcept()$ Func |crv-feclearexcept|
|
|
$fegetenv()$ Func |crv-fegetenv|
|
|
$fegetexceptflag()$ Func |crv-fegetexceptflag|
|
|
$fegetround()$ Func |crv-fegetround|
|
|
$feholdexcept()$ Func |crv-feholdexcept|
|
|
$feraiseexcept()$ Func |crv-feraiseexcept|
|
|
$fesetenv()$ Func |crv-fesetenv|
|
|
$fesetexceptflag()$ Func |crv-fesetexceptflag|
|
|
$fesetround()$ Func |crv-fesetround|
|
|
$fetestexcept()$ Func |crv-fetestexcept|
|
|
$feupdateenv()$ Func |crv-feupdateenv|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.6.1 Pragmas *crv-libFHPrag*
|
|
|
|
FENV_ACCESS Pragma *crv-FENV_ACCESS*
|
|
------------------
|
|
Synopsis~
|
|
$#include <fenv.h>$
|
|
$#pragma STDC FENV_ACCESS on/off-switch$
|
|
|
|
$on/off-switch$is$ON$,$OFF$or$DEFAULT$
|
|
|
|
Description~
|
|
This pragma provides a means to inform the compiler when a program might
|
|
access the floating-point environment (FPU or software emulation of FP) to
|
|
test status flags or run under non-default control modes. An "off"-state
|
|
signals that a program does not test status flags and does not run under
|
|
non-default control modes. Knowing this the compiler can do better
|
|
optimization that could subvert flag tests or mode changes.
|
|
|
|
When inside a compound statement, the pragma takes effect from its occurrence
|
|
until end of compound statement or until the next$FENV_ACCESS$is encountered;
|
|
at the end of a compound statement the state of the pragma is restored to its
|
|
state just before entering that compound statement.
|
|
When outside a compound statement, the pragma takes effect from its occurrence
|
|
until end of source-file or until the next$FENV_ACCESS$is encountered.
|
|
The default state of this pragma is implementation-defined.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.6.2 Exceptions *crv-libFHExceptions*
|
|
|
|
The following functions allow to query and manipulate the floating-point
|
|
status word. They can be used to check for untrapped exceptions when it's
|
|
convenient, rather than worrying about them in the middle of a calculation.
|
|
|
|
The macros below represent the various IEEE 754 exceptions. Not all FPUs
|
|
report all the different exceptions. Each constant is defined if and only if
|
|
the FPU compiling for supports that exception.$#ifdef$can be used to test for
|
|
FPU support.
|
|
Additional macro definitions may be specified by the implementation. They
|
|
begin with FE_ followed by uppercase letters.
|
|
|
|
|
|
FE_INEXACT Macro *crv-FE_INEXACT*
|
|
----------------
|
|
The inexact exception.
|
|
|
|
|
|
FE_DIVBYZERO Macro *crv-FE_DIVBYZERO*
|
|
------------------
|
|
The divide by zero exception.
|
|
|
|
|
|
FE_UNDERFLOW Macro *crv-FE_UNDERFLOW*
|
|
------------------
|
|
The underflow exception.
|
|
|
|
|
|
FE_OVERFLOW Macro *crv-FE_OVERFLOW*
|
|
-----------------
|
|
The overflow exception.
|
|
|
|
|
|
FE_INVALID Macro *crv-FE_INVALID*
|
|
----------------
|
|
The invalid exception.
|
|
|
|
|
|
FE_ALL_EXCEPT Macro *crv-FE_ALL_EXCEPT*
|
|
-------------------
|
|
This macro is the bitwise OR of all exception macros which are supported by
|
|
the FP implementation.
|
|
|
|
|
|
feclearexcept() Function *crv-feclearexcept*
|
|
------------------------
|
|
Synopsis~
|
|
$#include <fenv.h>$
|
|
$int feclearexcept(int excepts);$
|
|
|
|
Return~
|
|
zero in case the operation was successful, otherwise a non-zero value
|
|
|
|
Description~
|
|
This function clears all of the supported exception flags indicated by
|
|
$excepts$.
|
|
|
|
|
|
fegetexceptflag() Function *crv-fegetexceptflag*
|
|
--------------------------
|
|
Synopsis~
|
|
$#include <fenv.h>$
|
|
$int fegetexceptflag(fexcept_t *flagp, int excepts);$
|
|
|
|
Return~
|
|
zero in case the operation was successful, otherwise a non-zero value
|
|
|
|
Description~
|
|
This function attempts to store in the variable pointed to by$flagp$an
|
|
implementation-defined value representing the current setting of the
|
|
exception flags indicated by$excepts$.
|
|
|
|
|
|
feraiseexcept() Function *crv-feraiseexcept*
|
|
------------------------
|
|
Synopsis~
|
|
$#include <fenv.h>$
|
|
$int feraiseexcept(int excepts);$
|
|
|
|
Return~
|
|
zero in case the operation was successful, otherwise a non-zero value
|
|
|
|
Description~
|
|
This function attempts to raises the supported exceptions indicated by
|
|
$excepts$. If more than one exception bit in$excepts$is set the order in which
|
|
the exceptions are raised is undefined except that overflow ($FE_OVERFLOW$) or
|
|
underflow ($FE_UNDERFLOW$) are raised before inexact ($FE_INEXACT$). Whether
|
|
for overflow or underflow the inexact exception is also raised is also
|
|
implementation dependent.
|
|
|
|
|
|
fesetexceptflag() Function *crv-fesetexceptflag*
|
|
--------------------------
|
|
Synopsis~
|
|
$#include <fenv.h>$
|
|
$int fesetexceptflag(fexcept_t *flagp, int excepts);$
|
|
|
|
Return~
|
|
zero in case the operation was successful, otherwise a non-zero value
|
|
|
|
Description~
|
|
This function attempts to restore the flags for the exceptions indicated by
|
|
$excepts$to the values stored in the variable pointed to by $flagp$.
|
|
|
|
|
|
fetestexcept() Function *crv-fetestexcept*
|
|
-----------------------
|
|
Synopsis~
|
|
$#include <fenv.h>$
|
|
$int fetestexcept(int excepts);$
|
|
|
|
Return~
|
|
flags which are set
|
|
|
|
Description~
|
|
Test whether the exception flags indicated by the parameter$except$are
|
|
currently set. If any of them are, a nonzero value is returned which specifies
|
|
which exceptions are set. Otherwise the result is zero.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.6.3 Rounding *crv-libFHRounding*
|
|
|
|
Floating-point calculations are carried out internally with extra precision,
|
|
and then rounded to fit into the destination type. This ensures that results
|
|
are as precise as the input data. IEEE 754 defines four possible rounding
|
|
modes:
|
|
|
|
- Round to nearest
|
|
This is the default mode. It should be used unless there is a specific need
|
|
for one of the others. In this mode results are rounded to the nearest
|
|
representable value. If the result is midway between two representable
|
|
values, the even representable is chosen. Even here means the lowest-order
|
|
bit is zero. This rounding mode prevents statistical bias and guarantees
|
|
numeric stability: round-off errors in a lengthy calculation will remain
|
|
smaller than half of$FLT_EPSILON$.
|
|
|
|
- Round toward plus Infinity
|
|
All results are rounded to the smallest representable value which is greater
|
|
than the result.
|
|
|
|
- Round toward minus Infinity
|
|
All results are rounded to the largest representable value which is less
|
|
than the result.
|
|
|
|
- Round toward zero
|
|
All results are rounded to the largest representable value whose magnitude
|
|
is less than that of the result. In other words, if the result is negative
|
|
it is rounded up; if it is positive, it is rounded down.
|
|
|
|
For examples of effects see |crv-FLT_ROUNDS|.
|
|
|
|
$<fenv.h>$defines constants which you can use to refer to the various rounding
|
|
modes. Each one will be defined if and only if the FPU supports the
|
|
corresponding rounding mode.
|
|
|
|
|
|
FE_TONEAREST Macro *crv-FE_TONEAREST*
|
|
------------------
|
|
Round to nearest.
|
|
|
|
|
|
FE_UPWARD Macro *crv-FE_UPWARD*
|
|
---------------
|
|
Round toward +∞.
|
|
|
|
|
|
FE_DOWNWARD Macro *crv-FE_DOWNWARD*
|
|
-----------------
|
|
Round toward -∞.
|
|
|
|
|
|
FE_TOWARDZERO Macro *crv-FE_TOWARDZERO*
|
|
-------------------
|
|
Round toward zero.
|
|
|
|
|
|
Underflow is an unusual case. Normally, IEEE 754 floating point numbers are
|
|
always normalized. Numbers smaller than 2^r (where r is the minimum exponent
|
|
cannot be represented as normalized numbers. Rounding all such numbers to zero
|
|
or 2^r would cause some algorithms to fail at 0. Therefore, they are left in
|
|
denormalized form. That produces loss of precision, since some bits of the
|
|
mantissa are stolen to indicate the decimal point.
|
|
|
|
If a result is too small to be represented as a denormalized number, it is
|
|
rounded to zero. However, the sign of the result is preserved; if the
|
|
calculation was negative, the result is negative zero. Negative zero can also
|
|
result from some operations on infinity, such as 4/-∞. Negative zero
|
|
behaves identically to zero except when the copysign or signbit functions are
|
|
used to check the sign bit directly.
|
|
|
|
|
|
At any time one of the above four rounding modes is selected. The following
|
|
functions allow to get and set the rounding modes:
|
|
|
|
|
|
fegetround() Function *crv-fegetround*
|
|
---------------------
|
|
Synopsis~
|
|
$#include <fenv.h>$
|
|
$int fegetround(void);$
|
|
|
|
Return~
|
|
currently selected rounding mode
|
|
|
|
Description~
|
|
Returns the currently selected rounding mode, represented by one of the values
|
|
of the defined rounding mode macros.
|
|
|
|
|
|
fesetround() Function *crv-fesetround*
|
|
---------------------
|
|
Synopsis~
|
|
$#include <fenv.h>$
|
|
$int fesetround(int round);$
|
|
|
|
Return~
|
|
zero if it changed the rounding mode, a nonzero value if the mode is not
|
|
supported
|
|
|
|
Description~
|
|
Changes the currently selected rounding mode to$round$. If$round$does not
|
|
correspond to one of the supported rounding modes nothing is changed.
|
|
|
|
You should avoid changing the rounding mode if possible. It can be an
|
|
expensive operation; also, some hardware requires you to compile your
|
|
program differently for it to work. The resulting code may run slower. See
|
|
your compiler documentation for details.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.6.4 Environment *crv-libFHEnv*
|
|
|
|
The functions in this section manage the floating-point environment.
|
|
|
|
*crv-fentv_t*
|
|
The functions to save and restore the floating-point environment all use a
|
|
variable of type$fenv_t$to store information. This type is defined in
|
|
$<fenv.h>$. Its size and contents are implementation-defined. This variable
|
|
should not be manipulated directly.
|
|
|
|
|
|
fegetenv() Function *crv-fegetenv*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <fenv.h>$
|
|
$int fegetenv(fenv_t *envp);$
|
|
|
|
Return~
|
|
zero in case the operation was successful, otherwise a non-zero value
|
|
|
|
Description~
|
|
Store the floating-point environment in the variable pointed to by$envp$.
|
|
|
|
|
|
feholdexcept() Function *crv-feholdexcept*
|
|
-----------------------
|
|
Synopsis~
|
|
$#include <fenv.h>$
|
|
$int feholdexcept(fenv_t *envp);$
|
|
|
|
Return~
|
|
zero in case the operation was successful, otherwise a non-zero value
|
|
|
|
Description~
|
|
Store the current floating-point environment in the object pointed to by
|
|
$envp$. Then clear all exception flags, and set the FPU to trap no exceptions.
|
|
Not all FPUs support trapping no exceptions; if$feholdexcept$cannot set this
|
|
mode, it returns nonzero value.
|
|
|
|
|
|
fesetenv() Function *crv-fesetenv*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <fenv.h>$
|
|
$int fesetenv(const fenv_t *envp);$
|
|
|
|
Return~
|
|
zero in case the operation was successful, otherwise a non-zero value
|
|
|
|
Description~
|
|
Set the floating-point environment to that described by$envp$.
|
|
|
|
|
|
feupdateenv() Function *crv-feupdateenv*
|
|
----------------------
|
|
Synopsis~
|
|
$#include <fenv.h>$
|
|
$int feupdateenv(const fenv_t *envp);$
|
|
|
|
Return~
|
|
zero in case the operation was successful, otherwise a non-zero value
|
|
|
|
Description~
|
|
Like$fesetenv()$, this function sets the floating-point environment to that
|
|
described by$envp$. However, if any exceptions were flagged in the status word
|
|
before$feupdateenv()$was called, they remain flagged after the call. In other
|
|
words, after$feupdateenv()$is called, the status word is the bitwise OR of the
|
|
previous status word and the one saved in$envp$.
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
II.7 <float.h> Floating Point *crv-libFloatH*
|
|
|
|
This header file defines several macros that expand to various
|
|
implementation-specific limits and parameters describing floating-point
|
|
properties.
|
|
NOTE: The values are platform- and implementation-specific.The ISO C standard
|
|
specifies minimum and maximum values for most of these parameters.
|
|
|
|
Macro names starting with FLT_ refer to the float type, while names beginning
|
|
with DBL_ refer to the double type and names beginning with LDBL_ refer to the
|
|
long double type.
|
|
|
|
Quicklink:
|
|
$FLT_DIG $ Macro |crv-FLT_DIG|
|
|
$FLT_EPSILON $ Macro |crv-FLT_EPSILON|
|
|
$FLT_MANT_DIG $ Macro |crv-FLT_MANT_DIG|
|
|
$FLT_MAX $ Macro |crv-FLT_MAX|
|
|
$FLT_MAX_10_EXP $ Macro |crv-FLT_MAX_10_EXP|
|
|
$FLT_MAX_EXP $ Macro |crv-FLT_MAX_EXP|
|
|
$FLT_MIN $ Macro |crv-FLT_MIN|
|
|
$FLT_MIN_10_EXP $Macro |crv-FLT_MIN_10_EXP|
|
|
$FLT_MIN_EXP $ Macro |crv-FLT_MIN_EXP|
|
|
$FLT_RADIX $ Macro |crv-FLT_RADIX|
|
|
$FLT_ROUNDS $ Macro |crv-FLT_ROUNDS|
|
|
$DBL_DIG $ Macro |crv-DBL_DIG|
|
|
$DBL_EPSILON $ Macro |crv-DBL_EPSILON|
|
|
$DBL_MANT_DIG $ Macro |crv-DBL_MANT_DIG|
|
|
$DBL_MAX $ Macro |crv-DBL_MAX|
|
|
$DBL_MAX_10_EXP $ Macro |crv-DBL_MAX_10_EXP|
|
|
$DBL_MAX_EXP $ Macro |crv-DBL_MAX_EXP|
|
|
$DBL_MIN $ Macro |crv-DBL_MIN|
|
|
$DBL_MIN_10_EXP $Macro |crv-DBL_MIN_10_EXP|
|
|
$DBL_MIN_EXP $ Macro |crv-DBL_MIN_EXP|
|
|
$LDBL_DIG $ Macro |crv-LDBL_DIG|
|
|
$LDBL_EPSILON $ Macro |crv-LDBL_EPSILON|
|
|
$LDBL_MANT_DIG $ Macro |crv-LDBL_MANT_DIG|
|
|
$LDBL_MAX $ Macro |crv-LDBL_MAX|
|
|
$LDBL_MAX_10_EXP$ Macro |crv-LDBL_MAX_10_EXP|
|
|
$LDBL_MAX_EXP $ Macro |crv-LDBL_MAX_EXP|
|
|
$LDBL_MIN $ Macro |crv-LDBL_MIN|
|
|
$LDBL_MIN_10_EXP $Macro |crv-LDBL_MIN_10_EXP|
|
|
$LDBL_MIN_EXP $ Macro |crv-LDBL_MIN_EXP|
|
|
|
|
|
|
|
|
FLT_ROUNDS Macro *crv-FLT_ROUNDS*
|
|
----------------
|
|
This value characterizes the rounding mode for floating point addition. The
|
|
following values indicate standard rounding modes:
|
|
|
|
Value | Mode
|
|
--------+----------------------------------------------------------------
|
|
-1 | the mode is indeterminable
|
|
0 | rounding is towards zero, see |crv-libFHRounding|
|
|
1 | rounding is to the nearest number, see |crv-libFHRounding|
|
|
2 | rounding is towards positive infinity, see |crv-libFHRounding|
|
|
3 | rounding is towards negative infinity, see |crv-libFHRounding|
|
|
|
|
Any other value represents a machine-dependent nonstandard rounding mode.
|
|
|
|
On most machines, the value is 1, in accordance with the IEEE standard for
|
|
floating point.
|
|
|
|
Here is a table showing how certain values round for each possible value
|
|
of$FLT_ROUNDS$, if the other aspects of the representation match the IEEE
|
|
single-precision standard:
|
|
|
|
Value | 0 | 1 | 2 | 3
|
|
------------+------+-------------+-------------+-------------
|
|
1.00000003 | 1.0 | 1.0 | 1.00000012 | 1.0
|
|
1.00000007 | 1.0 | 1.00000012 | 1.00000012 | 1.0
|
|
-1.00000003 | -1.0 | -1.0 | -1.0 | -1.00000012
|
|
-1.00000007 | -1.0 | -1.00000012 | -1.0 | -1.00000012
|
|
|
|
|
|
|
|
FLT_RADIX Macro *crv-FLT_RADIX*
|
|
---------------
|
|
This is the value of the base, or radix, of the exponent representation. In
|
|
the very most times the value is 2 (except IBM 360 and derivatives).
|
|
|
|
|
|
FLT_MANT_DIG Macro *crv-FLT_MANT_DIG*
|
|
DBL_MANT_DIG Macro *crv-DBL_MANT_DIG*
|
|
LDBL_MANT_DIG Macro *crv-LDBL_MANT_DIG*
|
|
------------------
|
|
This is the number of base-$FLT_RADIX$digits in the floating point mantissa.
|
|
|
|
|
|
FLT_DIG Macro *crv-FLT_DIG*
|
|
DBL_DIG Macro *crv-DBL_DIG*
|
|
LDBL_DIG Macro *crv-LDBL_DIG*
|
|
--------------
|
|
This is the number of decimal digits of precision.
|
|
To satisfy standard C, the values supposed to be at least:
|
|
FLT_DIG >= 6
|
|
DBL_DIG >= 10
|
|
LDBL_DIG >= 10
|
|
|
|
Technically, if p and b are the precision and base (respectively) for the
|
|
representation, then the decimal precision q is the maximum number of decimal
|
|
digits such that any floating point number with q base 10 digits can be
|
|
rounded to a floating point number with p base b digits and back again,
|
|
without change to the q decimal digits.
|
|
|
|
|
|
FLT_MIN_EXP Macro *crv-FLT_MIN_EXP*
|
|
DBL_MIN_EXP Macro *crv-DBL_MIN_EXP*
|
|
LDBL_MIN_EXP Macro *crv-LDBL_MIN_EXP*
|
|
------------------
|
|
This is the minimum negative integer value for an exponent in base$FLT_RADIX$.
|
|
|
|
|
|
FLT_MIN_10_EXP Macro *crv-FLT_MIN_10_EXP*
|
|
DBL_MIN_10_EXP Macro *crv-DBL_MIN_10_EXP*
|
|
LDBL_MIN_10_EXP Macro *crv-LDBL_MIN_10_EXP*
|
|
---------------------
|
|
This is the minimum negative integer value for an exponent in base 10.
|
|
To satisfy standard C, the values supposed to be at least:
|
|
FLT_MIN_10_EXP <= -37
|
|
DBL_MIN_10_EXP <= -37
|
|
LDBL_MIN_10_EXP <= -37
|
|
|
|
|
|
FLT_MAX_EXP Macro *crv-FLT_MAX_EXP*
|
|
DBL_MAX_EXP Macro *crv-DBL_MAX_EXP*
|
|
LDBL_MAX_EXP Macro *crv-LDBL_MAX_EXP*
|
|
------------------
|
|
This is the maximum integer value for an exponent in base$FLT_RADIX$.
|
|
|
|
|
|
FLT_MAX_10_EXP Macro *crv-FLT_MAX_10_EXP*
|
|
DBL_MAX_10_EXP Macro *crv-DBL_MAX_10_EXP*
|
|
LDBL_MAX_10_EXP Macro *crv-LDBL_MAX_10_EXP*
|
|
---------------------
|
|
This is the maximum integer value for an exponent in base 10.
|
|
To satisfy standard C, the values supposed to be at least:
|
|
FLT_MAX_10_EXP >= -37
|
|
DBL_MAX_10_EXP >= -37
|
|
LDBL_MAX_10_EXP >= -37
|
|
|
|
|
|
|
|
FLT_MAX Macro *crv-FLT_MAX*
|
|
DBL_MAX Macro *crv-DBL_MAX*
|
|
LDBL_MAX Macro *crv-LDBL_MAX*
|
|
--------------
|
|
The value is the maximum finite number representable.
|
|
To satisfy standard C, the values supposed to be at least:
|
|
FLT_MAX >= 1E+37
|
|
DBL_MAX >= 1E+37
|
|
LDBL_MAX >= 1E+37
|
|
|
|
The smallest representable number is -FLT_MAX, -DBL_MAX, -LDBL_MAX.
|
|
|
|
|
|
FLT_MIN Macro *crv-FLT_MIN*
|
|
DBL_MIN Macro *crv-DBL_MIN*
|
|
LDBL_MIN Macro *crv-LDBL_MIN*
|
|
--------------
|
|
The value is the minimum number representable.
|
|
To satisfy standard C, the values supposed to be at least:
|
|
FLT_MIN <= 1E-37
|
|
DBL_MIN <= 1E-37
|
|
LDBL_MIN <= 1E-37
|
|
|
|
|
|
FLT_EPSILON Macro *crv-FLT_EPSILON*
|
|
DBL_EPSILON Macro *crv-DBL_EPSILON*
|
|
LDBL_EPSILON Macro *crv-LDBL_EPSILON*
|
|
------------------
|
|
This is the maximum positive floating point number such that
|
|
1.0 +$FLT_EPSILON$!= 1.0 is true (least significant digit representable).
|
|
|
|
To satisfy standard C, the values supposed to be at least:
|
|
FLT_EPSILON >= 1E-5
|
|
DBL_EPSILON >= 1E-9
|
|
LDBL_EPSILON >= 1E-9
|
|
|
|
|
|
|
|
==============================================================================
|
|
II.8 <inttypes.h> Absolute Value *crv-libInttypesH*
|
|
|
|
This header extends the$<stdint.h>$header (->|crv-libStdintH|). It provides
|
|
macros for format conversion of integer types and provides functions for
|
|
manipulating greatest-width integer types.
|
|
|
|
Quicklink:
|
|
$imaxdiv_t$ Type |crv-imaxdiv_t|
|
|
$imaxabs$ Func |crv-imaxabs|
|
|
$imaxdiv$ Func |crv-imaxdiv|
|
|
|
|
$PRIdN$ Macro |crv-PRIdN|
|
|
$PRIdLEASTN$ Macro |crv-PRIdLEASTN|
|
|
$PRIdFASTN$ Macro |crv-PRIdFASTN|
|
|
$PRIdMAX$ Macro |crv-PRIdMAX|
|
|
$PRIdPTR$ Macro |crv-PRIdPTR|
|
|
|
|
$PRIiN$ Macro |crv-PRIiN|
|
|
$PRIiLEASTN$ Macro |crv-PRIiLEASTN|
|
|
$PRIiFASTN$ Macro |crv-PRIiFASTN|
|
|
$PRIiMAX$ Macro |crv-PRIiMAX|
|
|
$PRIiPTR$ Macro |crv-PRIiPTR|
|
|
|
|
$PRIoN$ Macro |crv-PRIoN|
|
|
$PRIoLEASTN$ Macro |crv-PRIoLEASTN|
|
|
$PRIoFASTN$ Macro |crv-PRIoFASTN|
|
|
$PRIoMAX$ Macro |crv-PRIoMAX|
|
|
$PRIoPTR$ Macro |crv-PRIoPTR|
|
|
|
|
$PRIuN$ Macro |crv-PRIuN|
|
|
$PRIuLEASTN$ Macro |crv-PRIuLEASTN|
|
|
$PRIuFASTN$ Macro |crv-PRIuFASTN|
|
|
$PRIuMAX$ Macro |crv-PRIuMAX|
|
|
$PRIuPTR$ Macro |crv-PRIuPTR|
|
|
|
|
$PRIxN$ Macro |crv-PRIxN|
|
|
$PRIxLEASTN$ Macro |crv-PRIxLEASTN|
|
|
$PRIxFASTN$ Macro |crv-PRIxFASTN|
|
|
$PRIxMAX$ Macro |crv-PRIxMAX|
|
|
$PRIxPTR$ Macro |crv-PRIxPTR|
|
|
|
|
$PRIXN$ Macro |crv-PRIXN|
|
|
$PRIXLEASTN$ Macro |crv-PRIXLEASTN|
|
|
$PRIXFASTN$ Macro |crv-PRIXFASTN|
|
|
$PRIXMAX$ Macro |crv-PRIXMAX|
|
|
$PRIXPTR$ Macro |crv-PRIXPTR|
|
|
|
|
$SCNdN$ Macro |crv-SCNdN|
|
|
$SCNdLEASTN$ Macro |crv-SCNdLEASTN|
|
|
$SCNdFASTN$ Macro |crv-SCNdFASTN|
|
|
$SCNdMAX$ Macro |crv-SCNdMAX|
|
|
$SCNdPTR$ Macro |crv-SCNdPTR|
|
|
|
|
$SCNiN$ Macro |crv-SCNiN|
|
|
$SCNiLEASTN$ Macro |crv-SCNiLEASTN|
|
|
$SCNiFASTN$ Macro |crv-SCNiFASTN|
|
|
$SCNiMAX$ Macro |crv-SCNiMAX|
|
|
$SCNiPTR$ Macro |crv-SCNiPTR|
|
|
|
|
$SCNoN$ Macro |crv-SCNoN|
|
|
$SCNoLEASTN$ Macro |crv-SCNoLEASTN|
|
|
$SCNoFASTN$ Macro |crv-SCNoFASTN|
|
|
$SCNoMAX$ Macro |crv-SCNoMAX|
|
|
$SCNoPTR$ Macro |crv-SCNoPTR|
|
|
|
|
$SCNuN$ Macro |crv-SCNuN|
|
|
$SCNuLEASTN$ Macro |crv-SCNuLEASTN|
|
|
$SCNuFASTN$ Macro |crv-SCNuFASTN|
|
|
$SCNuMAX$ Macro |crv-SCNuMAX|
|
|
$SCNuPTR$ Macro |crv-SCNuPTR|
|
|
|
|
$SCNxN$ Macro |crv-SCNxN|
|
|
$SCNxLEASTN$ Macro |crv-SCNxLEASTN|
|
|
$SCNxFASTN$ Macro |crv-SCNxFASTN|
|
|
$SCNxMAX$ Macro |crv-SCNxMAX|
|
|
$SCNxPTR$ Macro |crv-SCNxPTR|
|
|
|
|
$strtoimax$ Func |crv-strtoimax|
|
|
$strtoumax$ Func |crv-strtoumax|
|
|
$wcstoimax$ Func |crv-wcstoimax|
|
|
$wcstoumax$ Func |crv-wcstoumax|
|
|
|
|
|
|
Macros *crv-__STDC_FORMAT_MACROS*
|
|
------
|
|
The following macros expand to a string (in most cases a single character)
|
|
containing a conversion specifier suitable for use within format arguments
|
|
of formated input/output functions, like$printf()$or$scanf()$.
|
|
They are only defined when$__STDC_FORMAT_MACROS$is defined before including
|
|
$<inttypes.h>$.
|
|
For each type declared in$<stdint.h>$, corresponding macros for conversion
|
|
specifiers for use with the formatted input/output functions are defined.
|
|
|
|
The macro names have a prefix PRI for the printf family or SCN for the
|
|
scanf family functions followed by the conversion specifier, followed by name
|
|
that is similar to the type name this macro is for, followed by a number N.
|
|
The number N represents the width of the type as specified in$<stdint.h>.$
|
|
|
|
Example: The macro$PRIxFAST32$can be used in a format string to print an
|
|
integer value of type$int_fast32_t$in hexedecimal format ('x').
|
|
|
|
Usage see example below.
|
|
|
|
|
|
Format Specifiers for ..printf
|
|
------------------------------
|
|
|
|
Signed Integers:
|
|
$PRIdN$ width N, decimal notation *crv-PRIdN*
|
|
$PRIdLEASTN$ minimum width N, decimal notation *crv-PRIdLEASTN*
|
|
$PRIdFASTN$ width N, fast to operate with, decimal not. *crv-PRIdFASTN*
|
|
$PRIdMAX$ type$intmax_t$, decimal notation *crv-PRIdMAX*
|
|
$PRIdPTR$ type$intptr_t$, decimal notation *crv-PRIdPTR*
|
|
|
|
$PRIiN$ width N, decimal notation *crv-PRIiN*
|
|
$PRIiLEASTN$ minimum width N, decimal notation *crv-PRIiLEASTN*
|
|
$PRIiFASTN$ width N, fast to operate with, decimal not. *crv-PRIiFASTN*
|
|
$PRIiMAX$ type$intmax_t$, decimal notation *crv-PRIiMAX*
|
|
$PRIiPTR$ type$intptr_t$, decimal notation *crv-PRIiPTR*
|
|
|
|
Unsigned Integers:
|
|
$PRIoN$ width N, octal notation *crv-PRIoN*
|
|
$PRIoLEASTN$ minimum width N, octal notation *crv-PRIoLEASTN*
|
|
$PRIoFASTN$ width N, fast to operate with, octal not. *crv-PRIoFASTN*
|
|
$PRIoMAX$ type$intmax_t$, octal notation *crv-PRIoMAX*
|
|
$PRIoPTR$ type$intptr_t$, octal notation *crv-PRIoPTR*
|
|
|
|
$PRIuN$ width N, decimal notation *crv-PRIuN*
|
|
$PRIuLEASTN$ minimum width N, decimal notation *crv-PRIuLEASTN*
|
|
$PRIuFASTN$ width N, fast to operate with, decimal not. *crv-PRIuFASTN*
|
|
$PRIuMAX$ type$intmax_t$, decimal notation *crv-PRIuMAX*
|
|
$PRIuPTR$ type$intptr_t$, decimal notation *crv-PRIuPTR*
|
|
|
|
$PRIxN$ width N, lowercase hex. notation *crv-PRIxN*
|
|
$PRIxLEASTN$ minimum width N, lowercase hex. notation *crv-PRIxLEASTN*
|
|
$PRIxFASTN$ width N, fast operation, lowercase hex. not *crv-PRIxFASTN*
|
|
$PRIxMAX$ type$intmax_t$, lowercase hex. notation *crv-PRIxMAX*
|
|
$PRIxPTR$ type$intptr_t$, lowercase hex. notation *crv-PRIxPTR*
|
|
|
|
$PRIXN$ width N, uppercase hex. notation *crv-PRIXN*
|
|
$PRIXLEASTN$ minimum width N, uppercase hex. notation *crv-PRIXLEASTN*
|
|
$PRIXFASTN$ width N, fast operation, uppercase hex. not. *crv-PRIXFASTN*
|
|
$PRIXMAX$ type$intmax_t$, uppercase hex. notation *crv-PRIXMAX*
|
|
$PRIXPTR$ type$intptr_t$, uppercase hex. notation *crv-PRIXPTR*
|
|
|
|
|
|
Format Specifiers for ..scanf
|
|
-----------------------------
|
|
|
|
Signed Integers:
|
|
$SCNdN$ width N, decimal notation *crv-SCNdN*
|
|
$SCNdLEASTN$ minimum width N, decimal notation *crv-SCNdLEASTN*
|
|
$SCNdFASTN$ width N, fast to operate with, decimal not. *crv-SCNdFASTN*
|
|
$SCNdMAX$ type$intmax_t$, decimal notation *crv-SCNdMAX*
|
|
$SCNdPTR$ type$intptr_t$, decimal notation *crv-SCNdPTR*
|
|
|
|
$SCNiN$ width N, decimal notation *crv-SCNiN*
|
|
$SCNiLEASTN$ minimum width N, decimal notation *crv-SCNiLEASTN*
|
|
$SCNiFASTN$ width N, fast to operate with, decimal not. *crv-SCNiFASTN*
|
|
$SCNiMAX$ type$intmax_t$, decimal notation *crv-SCNiMAX*
|
|
$SCNiPTR$ type$intptr_t$, decimal notation *crv-SCNiPTR*
|
|
|
|
Unsigned Integers:
|
|
$SCNoN$ width N, octal notation *crv-SCNoN*
|
|
$SCNoLEASTN$ minimum width N, octal notation *crv-SCNoLEASTN*
|
|
$SCNoFASTN$ width N, fast to operate with, octal not. *crv-SCNoFASTN*
|
|
$SCNoMAX$ type$intmax_t$, octal notation *crv-SCNoMAX*
|
|
$SCNoPTR$ type$intptr_t$, octal notation *crv-SCNoPTR*
|
|
|
|
$SCNuN$ width N, decimal notation *crv-SCNuN*
|
|
$SCNuLEASTN$ minimum width N, decimal notation *crv-SCNuLEASTN*
|
|
$SCNuFASTN$ width N, fast to operate with, decimal not. *crv-SCNuFASTN*
|
|
$SCNuMAX$ type$intmax_t$, decimal notation *crv-SCNuMAX*
|
|
$SCNuPTR$ type$intptr_t$, decimal notation *crv-SCNuPTR*
|
|
|
|
$SCNxN$ width N, hex. notation *crv-SCNxN*
|
|
$SCNxLEASTN$ minimum width N, hex. notation *crv-SCNxLEASTN*
|
|
$SCNxFASTN$ width N, fast operation, hex. not *crv-SCNxFASTN*
|
|
$SCNxMAX$ type$intmax_t$, hex. notation *crv-SCNxMAX*
|
|
$SCNxPTR$ type$intptr_t$, hex. notation *crv-SCNxPTR*
|
|
|
|
|
|
Example: >
|
|
#define __STDC_FORMAT_MACROS
|
|
|
|
#include <inttypes.h>
|
|
#include <stdio.h>
|
|
|
|
int main(void)
|
|
{
|
|
int16_t n = -123;
|
|
|
|
printf("Value is %4" PRIu16 "\n", n);
|
|
}
|
|
|
|
|
|
|
|
imaxdiv_t Type *crv-imaxdiv_t*
|
|
--------------
|
|
This is a structure type used to hold the result returned by the$imaxdiv()$
|
|
function. It holds both, the quotient and the remainder from the division.
|
|
|
|
|
|
|
|
imaxabs() Function *crv-imaxabs*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <inttypes.h>$
|
|
$intmax_t imaxabs(intmax_t j);$
|
|
|
|
Return~
|
|
absolute value of$j$
|
|
|
|
Description~
|
|
This function computes the absolute value of an integer$j$.
|
|
|
|
|
|
|
|
imaxdiv() Function *crv-imaxdiv*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <inttypes.h>$
|
|
$intdiv_t imaxdiv(intmax_t numerator, intmax_t denominator );$
|
|
|
|
Return~
|
|
returns result of division and modulo operation, both stored in$intdiv_t$
|
|
structur
|
|
|
|
Description~
|
|
This functions computes$numerator / denominator$and$numerator % denominator$in
|
|
a single operation.
|
|
|
|
|
|
|
|
strtoimax() Function *crv-strtoimax*
|
|
--------------------
|
|
Synopsis~
|
|
$#include <inttypes.h>$
|
|
$intmax_t strtoimax(const char *restrict string, char **restrict tailptr,$
|
|
$int base);$
|
|
|
|
Return~
|
|
converted value
|
|
|
|
Description~
|
|
This function ("string-to-imax") converts the initial part of$string$to a
|
|
signed integer, which is returned as a value of type$intmax_t$.
|
|
See$strol()$for description of parameters (|crv-libstrtol|).
|
|
|
|
|
|
|
|
strtoumax() Function *crv-strtoumax*
|
|
--------------------
|
|
Synopsis~
|
|
$#include <inttypes.h>$
|
|
$uintmax_t strtoumax(const char *restrict string, char **restrict tailptr,$
|
|
$int base);$
|
|
|
|
Return~
|
|
converted value
|
|
|
|
Description~
|
|
This function ("string-to-umax") converts the initial part of$string$to a
|
|
signed integer, which is returned as a value of type$uintmax_t$.
|
|
See$stroul()$for description of parameters (|crv-libstrtoul|).
|
|
|
|
|
|
|
|
wcstoimax() Function *crv-wcstoimax*
|
|
--------------------
|
|
Synopsis~
|
|
$#include <stddef.h> // for wchar_t$
|
|
$#include <inttypes.h>$
|
|
$wchar_t wcstoimax(const wchar_t *restrict string,$
|
|
$wchar_t **restrict tailptr, int base);$
|
|
|
|
Return~
|
|
converted value
|
|
|
|
Description~
|
|
This function is equivalent to the$strtoimax()$function in nearly all aspects
|
|
but handles wide character strings (see |crv-libstrtoimax| for further
|
|
information).
|
|
|
|
|
|
|
|
wcstoumax() Function *crv-wcstoumax*
|
|
--------------------
|
|
Synopsis~
|
|
$#include <stddef.h> // for wchar_t$
|
|
$#include <inttypes.h>$
|
|
$wchar_t wcstoimax(const wchar_t *restrict string,$
|
|
$wchar_t **restrict tailptr, int base);$
|
|
|
|
Return~
|
|
converted value
|
|
|
|
Description~
|
|
This function is equivalent to the$strtoumax()$function in nearly all aspects
|
|
but handles wide character strings (see |crv-libstrtoumax| for further
|
|
information).
|
|
|
|
|
|
|
|
==============================================================================
|
|
II.9 <iso646.h> Alternatives *crv-libIso646H*
|
|
|
|
This header defines some macros. They can be used for alternative spellings.
|
|
|
|
Macro | Expands to
|
|
----------+------------
|
|
$and$ | $&&$
|
|
$and_eq$ | $&=$
|
|
$bitand$ | $&$
|
|
$bitor$ | $|$
|
|
$compl$ | $~$
|
|
$not$ | $!$
|
|
$not_eq$ | $!=$
|
|
$or$ | $||$
|
|
$or_eq$ | $|=$
|
|
$xor$ | $^$
|
|
$xor_eq$ | $^=$
|
|
|
|
|
|
|
|
==============================================================================
|
|
II.10 <limits.h> Limits of Integer Types *crv-libLimitsH*
|
|
|
|
This header file defines several macros that expand to various limits and
|
|
parameters of the integer types.
|
|
NOTE: The values are platform- and implementation-specific.The ISO C standard
|
|
specifies minimum and maximum values for most of these parameters.
|
|
|
|
The macros of this header can be grouped in:
|
|
- range of integer type
|
|
- width of type
|
|
- selection of conversion and its properties
|
|
|
|
|
|
Quicklink:
|
|
$CHAR_BIT$ Macro |crv-CHAR_BIT|
|
|
$CHAR_MAX$ Macro |crv-CHAR_MAX|
|
|
$CHAR_MIN$ Macro |crv-CHAR_MIN|
|
|
$INT_MAX$ Macro |crv-INT_MAX|
|
|
$INT_MIN$ Macro |crv-INT_MIN|
|
|
$LONG_LONG_MAX$ Macro |crv-LONG_LONG_MAX|
|
|
$LONG_LONG_MIN$ Macro |crv-LONG_LONG_MIN|
|
|
$LONG_MAX$ Macro |crv-LONG_MAX|
|
|
$LONG_MIN$ Macro |crv-LONG_MIN|
|
|
$MB_LEN_MAX$ Macro |crv-MB_LEN_MAX|
|
|
$SCHAR_MAX$ Macro |crv-SCHAR_MAX|
|
|
$SCHAR_MIN$ Macro |crv-SCHAR_MIN|
|
|
$SHRT_MAX$ Macro |crv-SHRT_MAX|
|
|
$SHRT_MIN$ Macro |crv-SHRT_MIN|
|
|
$UCHAR_MAX$ Macro |crv-UCHAR_MAX|
|
|
$UINT_MAX$ Macro |crv-UINT_MAX|
|
|
$ULONG_LONG_MAX$Macro |crv-ULONG_LONG_MAX|
|
|
$ULONG_MAX$ Macro |crv-ULONG_MAX|
|
|
$USHRT_MAX$ Macro |crv-USHRT_MAX|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.10.1 Range of Integer Type *crv-libLHRange*
|
|
|
|
Each signed integer type has a pair of macros which give the smallest and
|
|
largest values that it can hold. Each unsigned integer type has one such
|
|
macro, for the maximum value; the minimum value is, of course, zero.
|
|
|
|
The values of these macros are all integer constant expressions. The MAX and
|
|
MIN macros for$char$and$short int$types have values of type$int$. The MAX and
|
|
MIN macros for the other types have values of the same type described by
|
|
the macro - thus,$ULONG_MAX$has type$unsigned long int$.
|
|
|
|
SCHAR_MIN Macro *crv-SCHAR_MIN*
|
|
SCHAR_MAX Macro *crv-SCHAR_MAX*
|
|
---------------
|
|
minimum / maximum value that can be represented by a$signed char$
|
|
|
|
|
|
UCHAR_MAX Macro *crv-UCHAR_MAX*
|
|
---------------
|
|
maximum value that can be represented by an$unsigned char$
|
|
|
|
|
|
CHAR_MIN Macro *crv-CHAR_MIN*
|
|
CHAR_MAX Macro *crv-CHAR_MAX*
|
|
--------------
|
|
minimum / maximum value that can be represented by a$char$
|
|
|
|
|
|
SHRT_MIN Macro *crv-SHRT_MIN*
|
|
SHRT_MAX Macro *crv-SHRT_MAX*
|
|
--------------
|
|
minimum / maximum value that can be represented by a$signed short int$
|
|
|
|
|
|
USHRT_MAX Macro *crv-USHRT_MAX*
|
|
---------------
|
|
maximum value that can be represented by an$unsigned short int$
|
|
|
|
|
|
INT_MIN Macro *crv-INT_MIN*
|
|
INT_MAX Macro *crv-INT_MAX*
|
|
-------------
|
|
minimum / maximum value that can be represented by a$signed int$
|
|
|
|
UINT_MAX Macro *crv-UINT_MAX*
|
|
--------------
|
|
maximum value that can be represented by an$unsigned int$
|
|
|
|
|
|
LONG_MIN Macro *crv-LONG_MIN*
|
|
LONG_MAX Macro *crv-LONG_MAX*
|
|
--------------
|
|
minimum / maximum value that can be represented by a$signed long int$
|
|
|
|
|
|
ULONG_MAX Macro *crv-ULONG_MAX*
|
|
---------------
|
|
maximum value that can be represented by an$unsigned long int$
|
|
|
|
|
|
LONG_LONG_MIN Macro *crv-LONG_LONG_MIN*
|
|
LONG_LONG_MAX Macro *crv-LONG_LONG_MAX*
|
|
-------------------
|
|
minimum / maximum value that can be represented by a$signed long long int$
|
|
|
|
|
|
ULONG_LONG_MAX Macro *crv-ULONG_LONG_MAX*
|
|
--------------------
|
|
maximum value that can be represented by an$unsigned long long int$
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.10.2 Width of Type *crv-libLHWidth*
|
|
|
|
CHAR_BIT Macro *crv-CHAR_BIT*
|
|
--------------
|
|
this is the number of bits in a$char$- eight, on most systems. The value
|
|
has type$int$.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.10.3 Conversion and Properties *crv-libLHConv*
|
|
|
|
A characteristic of each multibyte character set is the maximum number of
|
|
bytes that can be necessary to represent one character. This information
|
|
is quite important when writing code that uses the conversion functions.
|
|
|
|
MB_LEN_MAX Macro *crv-MB_LEN_MAX*
|
|
----------------
|
|
Specifies the maximum number of bytes in the multibyte sequence for a single
|
|
character in any of the supported locales. This is a compile-time constant.
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
II.11 <local.h> Localization *crv-libLocalH*
|
|
|
|
This header defines macros and declares functions for setting local specific
|
|
things.
|
|
|
|
Quicklink:
|
|
$LC_ALL$ Macro |crv-LC_ALL|
|
|
$LC_COLLATE$ Macro |crv-LC_COLLATE|
|
|
$LC_CTYPE$ Macro |crv-LC_CTYPE|
|
|
$LC_MONETARY$ Macro |crv-LC_MONETARY|
|
|
$LC_NUMERIC$ Macro |crv-LC_NUMERIC|
|
|
$lconf$ Type |crv-lconf|
|
|
$localeconf()$ Func |crv-localeconv|
|
|
$setlocale()$ Func |crv-setlocale|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.11.1 Categories *crv-libLocHCat*
|
|
|
|
The purposes that locales serve are grouped into categories, so that a user
|
|
or a program can choose the locale for each category independently.
|
|
The following macro names are both an environment variable that
|
|
a user can set, and a macro name that can be used as an argument
|
|
to$setlocale()$.
|
|
Additional macro definitions beginning with LC_ followed by uppercase letters
|
|
my be specified by the compiler.
|
|
|
|
|
|
LC_COLLATE Macro *crv-LC_COLLATE*
|
|
----------------
|
|
This category applies to collation of strings (functions$strcoll()$and
|
|
$strxfrm()$).
|
|
|
|
|
|
LC_CTYPE Macro *crv-LC_CTYPE*
|
|
--------------
|
|
This category applies to classification and conversion of characters, and to
|
|
multibyte and wide characters.
|
|
|
|
|
|
LC_MONETARY Macro *crv-LC_MONETARY*
|
|
-----------------
|
|
This category applies to formatting monetary values.
|
|
|
|
|
|
LC_NUMERIC Macro *crv-LC_NUMERIC*
|
|
----------------
|
|
This category applies to formatting numeric values that are not monetary.
|
|
|
|
|
|
LC_ALL Macro *crv-LC_ALL*
|
|
------------
|
|
This is not an environment variable; it is only a macro that can be use with
|
|
$setlocale()$to set a single locale for all purposes. Setting this environment
|
|
variable overwrites all selections by the other LC_* variables.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.11.2 Standard Locales *crv-libLocHLoc*
|
|
|
|
There are two standard locales:
|
|
|
|
"C"
|
|
This is the standard C locale. The attributes and behavior it provides are
|
|
specified in the ISO C standard. This is the default.
|
|
For "C" the members of the$lconf$structure have the following values: >
|
|
char *decimal_point // "."
|
|
char *mon_decimal_point // ""
|
|
char *thousands_sep // ""
|
|
char *mon_thousands_sep // ""
|
|
char *grouping // ""
|
|
char *mon_grouping // ""
|
|
char int_frac_digits // CHAR_MAX
|
|
char frac_digits // CHAR_MAX
|
|
char *currency_symbol // ""
|
|
char *int_curr_symbol // ""
|
|
char p_cs_precedes // CHAR_MAX
|
|
char n_cs_precedes // CHAR_MAX
|
|
char int_p_cs_precedes // CHAR_MAX
|
|
char int_n_cs_precedes // CHAR_MAX
|
|
char p_sep_by_space // CHAR_MAX
|
|
char n_sep_by_space // CHAR_MAX
|
|
char int_p_sep_by_space // CHAR_MAX
|
|
char int_n_sep_by_space // CHAR_MAX
|
|
char *positive_sign // ""
|
|
char *negative_sign // ""
|
|
char p_sign_posn // CHAR_MAX
|
|
char n_sign_posn // CHAR_MAX
|
|
char int_p_sign_posn // CHAR_MAX
|
|
char int_n_sign_posn // CHAR_MAX
|
|
An empty string or$CHAR_MAX$indicates that the value is not available
|
|
in this local.
|
|
|
|
""
|
|
The empty name says to select a locale based on environment variables,
|
|
see categories (|crv-libLocHCat|).
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.11.3 Information Structure *crv-libLocHInfo*
|
|
|
|
|
|
lconf Type *crv-lconf*
|
|
----------
|
|
$lconf$is a structure giving information about numeric and monetary notation.
|
|
According to standard C this structure must have at least the following
|
|
elements.
|
|
If a member of the structure has type$char$, and the value is$CHAR_MAX$,
|
|
it means that the current locale has no value for that parameter.
|
|
|
|
|
|
$char *decimal_point$ *crv-decimal_point*
|
|
$char *mon_decimal_point$ *crv-mon_decimal_point*
|
|
These are the decimal-point separators used in formatting non-monetary and
|
|
monetary quantities, respectively.
|
|
|
|
|
|
$char *thousands_sep$ *crv-thousands_sep*
|
|
$char *mon_thousands_sep$ *crv-mon_thousands_sep*
|
|
These are the separators used to delimit groups of digits to the left of the
|
|
decimal point in formatting non-monetary and monetary quantities,
|
|
respectively.
|
|
|
|
|
|
$char *grouping$ *crv-grouping*
|
|
$char *mon_grouping$ *crv-mon_grouping*
|
|
These are strings that specify how to group the digits to the left of the
|
|
decimal point.$grouping$applies to non-monetary quantities and$mon_grouping$
|
|
applies to monetary quantities. Use either$thousands_sep$or$mon_thousands_sep$
|
|
to separate the digit groups.
|
|
|
|
Each member of these strings is to be interpreted as an integer value of type
|
|
$char$. Successive numbers (from left to right) give the sizes of successive
|
|
groups (from right to left, starting at the decimal point.) The last member
|
|
is either 0, in which case the previous member is used over and over again
|
|
for all the remaining groups, or$CHAR_MAX$, in which case there is no more
|
|
grouping - or, put another way, any remaining digits form one large group
|
|
without separators.
|
|
|
|
For example, if grouping is "\04\03\02", the correct grouping for the number
|
|
123456787654321 is 12, 34, 56, 78, 765, 4321. This uses a group of 4 digits
|
|
at the end, preceded by a group of 3 digits, preceded by groups of 2 digits
|
|
(as many as needed). With a separator of ,, the number would be printed as
|
|
12,34,56,78,765,4321.
|
|
|
|
A value of "\03" indicates repeated groups of three digits, as normally used
|
|
in the U.S.
|
|
|
|
|
|
$char int_frac_digits$ *crv-int_frac_digits*
|
|
$char frac_digits$ *crv-frac_digits*
|
|
These are small integers indicating how many fractional digits (to the right
|
|
of the decimal point) should be displayed in a monetary value in international
|
|
and local formats, respectively.
|
|
|
|
|
|
$char *currency_symbol$ *crv-currency_symbol*
|
|
The local currency symbol for the selected locale.
|
|
|
|
|
|
$char *int_curr_symbol$ *crv-int_curr_symbol*
|
|
The international currency symbol for the selected locale. The value should
|
|
normally consist of a three-letter abbreviation.
|
|
|
|
|
|
$char p_cs_precedes$ *crv-p_cs_precedes*
|
|
$char n_cs_precedes$ *crv-n_cs_precedes*
|
|
$char int_p_cs_precedes$ *crv-int_p_cs_precedes*
|
|
$char int_n_cs_precedes$ *crv-int_n_cs_precedes*
|
|
These members are 1 if the$currency_symbol$or$int_curr_symbol$strings should
|
|
precede the value of a monetary amount, or 0 if the strings should follow
|
|
the value. The$p_cs_precedes$and$int_p_cs_precedes$members apply to positive
|
|
amounts (or zero), and the$n_cs_precedes$and$int_n_cs_precedes$members apply
|
|
to negative amounts.
|
|
The members with the$int_ prefix$apply to the$int_curr_symbol$while the other
|
|
two apply to$currency_symbol$.
|
|
|
|
|
|
$char p_sep_by_space$ *crv-p_sep_by_space*
|
|
$char n_sep_by_space$ *crv-n_sep_by_space*
|
|
$char int_p_sep_by_space$ *crv-int_p_sep_by_space*
|
|
$char int_n_sep_by_space$ *crv-int_n_sep_by_space*
|
|
These members are 1 if a space should appear between the$currency_symbol$
|
|
or$int_curr_symbol$strings and the amount, or 0 if no space should appear.
|
|
The$p_sep_by_space$and$int_p_sep_by_space$members apply to positive amounts
|
|
(or zero), and the$n_sep_by_space$and$int_n_sep_by_space$members apply to
|
|
negative amounts.
|
|
The members with the$int_ prefix$apply to the$int_curr_symbol$while the other
|
|
two apply to$currency_symbol$. There is one specialty with
|
|
the$int_curr_symbol$though. Since all legal values contain a space at the
|
|
end the string one either$printf()$this space (if the currency symbol must
|
|
appear in front and must be separated) or one has to avoid printing this
|
|
character at all (especially when at the end of the string).
|
|
|
|
|
|
$char *positive_sign$ *crv-positive_sign*
|
|
$char *negative_sign$ *crv-negative_sign*
|
|
These are strings used to indicate positive (or zero) and negative monetary
|
|
quantities, respectively.
|
|
|
|
|
|
$char p_sign_posn$ *crv-p_sign_posn*
|
|
$char n_sign_posn$ *crv-n_sign_posn*
|
|
$char int_p_sign_posn$ *crv-int_p_sign_posn*
|
|
$char int_n_sign_posn$ *crv-int_n_sign_posn*
|
|
These members are small integers that indicate how to position the sign for
|
|
nonnegative and negative monetary quantities, respectively. (The string used
|
|
by the sign is what was specified with$positive_sign$or$negative_sign$.)
|
|
The possible values are as follows:
|
|
|
|
0 The currency symbol and quantity should be surrounded by parentheses.
|
|
|
|
1 Print the sign string before the quantity and currency symbol.
|
|
|
|
2 Print the sign string after the quantity and currency symbol.
|
|
|
|
3 Print the sign string right before the currency symbol.
|
|
|
|
4 Print the sign string right after the currency symbol.
|
|
|
|
CHAR_MAX "Unspecified". Both members have this value in the standard C
|
|
locale.
|
|
|
|
The members with the$int_ prefix$apply to the$int_curr_symbol$while the other
|
|
two apply to$currency_symbol$.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.11.4 Functions *crv-libLocHFunc*
|
|
|
|
|
|
setlocale() Function *crv-setlocale*
|
|
--------------------
|
|
Synopsis~
|
|
$#include <locale.h>$
|
|
$char *setlocale(int category, const char *locale);$
|
|
|
|
Return~
|
|
see description
|
|
|
|
Description~
|
|
This function sets the current locale for category$category$to$locale$.
|
|
|
|
If category is$ LC_ALL$, this specifies the locale for all purposes. The other
|
|
possible values of$category$specify an single purpose
|
|
(see Categories |crv-libLocHCat| ).
|
|
|
|
This function can also be used to find out the current locale by passing a null
|
|
pointer as the$locale$argument. In this case, a string is returned that is the
|
|
name of the locale currently selected for category$category$.
|
|
|
|
The string returned should not be modified.
|
|
|
|
When the current locale for category$LC_ALL$is read, the value encodes the
|
|
entire combination of selected locales for all categories.
|
|
|
|
It is not guaranteed that the returned pointer remains valid over time, so a
|
|
copy must be made.
|
|
|
|
When the$locale$argument is not a null pointer, the string returned reflects
|
|
the newly-modified locale.
|
|
|
|
If an empty string for$locale$is specified, this means to read the appropriate
|
|
environment variable and use its value to select the locale for$category$.
|
|
|
|
If a nonempty string is given for$locale$, then the locale of that name is
|
|
used if possible.
|
|
|
|
If an invalid locale name is specified,$setlocale()$returns a null pointer
|
|
and leaves the current locale unchanged.
|
|
|
|
|
|
|
|
localeconf() Function *crv-localeconv*
|
|
---------------------
|
|
Synopsis~
|
|
$#include <locale.h>$
|
|
$struct lconv *localeconv(void);$
|
|
|
|
Return~
|
|
pointer to structure$lconv$, representing the current local settings
|
|
|
|
Description~
|
|
This function returns a pointer to the structure$lconv$whose components
|
|
contain information about how numeric and monetary values should be
|
|
formatted in the current locale.
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
II.12 <math.h> Mathematics *crv-libMathH*
|
|
|
|
This header file defines macros and declares functions that allow to do
|
|
mathematics.
|
|
|
|
Quicklink:
|
|
$acos()$ Func |crv-acos|
|
|
$acosf()$ Func |crv-acosf|
|
|
$acosh()$ Func |crv-acosh|
|
|
$acoshf()$ Func |crv-acoshf|
|
|
$acoshl()$ Func |crv-acoshl|
|
|
$acosl()$ Func |crv-acosl|
|
|
$asin()$ Func |crv-asin|
|
|
$asinf()$ Func |crv-asinf|
|
|
$asinh()$ Func |crv-asinh|
|
|
$asinhf()$ Func |crv-asinhf|
|
|
$asinhl()$ Func |crv-asinhl|
|
|
$asinl()$ Func |crv-asinl|
|
|
$atan()$ Func |crv-atan|
|
|
$atanf()$ Func |crv-atanf|
|
|
$atanh()$ Func |crv-atanh|
|
|
$atanhf()$ Func |crv-atanhf|
|
|
$atanhl()$ Func |crv-atanhl|
|
|
$atanl()$ Func |crv-atanl|
|
|
$atan2()$ Func |crv-atan2|
|
|
$atan2f()$ Func |crv-atan2f|
|
|
$atan2l()$ Func |crv-atan2l|
|
|
$cbrt()$ Func |crv-cbrt|
|
|
$cbrtf()$ Func |crv-cbrtf|
|
|
$cbrtl()$ Func |crv-cbrtl|
|
|
$ceil()$ Func |crv-ceil|
|
|
$ceilf()$ Func |crv-ceilf|
|
|
$ceill()$ Func |crv-ceill|
|
|
$copysign()$ Func |crv-copysign|
|
|
$copysignf()$ Func |crv-copysignf|
|
|
$copysignl()$ Func |crv-copysignl|
|
|
$cos()$ Func |crv-cos|
|
|
$cosf()$ Func |crv-cosf|
|
|
$cosh()$ Func |crv-cosh|
|
|
$coshf()$ Func |crv-coshf|
|
|
$coshl()$ Func |crv-coshl|
|
|
$cosl()$ Func |crv-cosl|
|
|
$erf()$ Func |crv-erf|
|
|
$erff()$ Func |crv-erff|
|
|
$erfl()$ Func |crv-erfl|
|
|
$erfc()$ Func |crv-erfc|
|
|
$erfcf()$ Func |crv-erfcf|
|
|
$erfcl()$ Func |crv-erfcl|
|
|
$exp2()$ Func |crv-exp2|
|
|
$exp2f()$ Func |crv-exp2f|
|
|
$exp2l()$ Func |crv-exp2l|
|
|
$exp()$ Func |crv-exp|
|
|
$expf()$ Func |crv-expf|
|
|
$expl()$ Func |crv-expl|
|
|
$expm1()$ Func |crv-expm1|
|
|
$expm1f()$ Func |crv-expm1f|
|
|
$expm1l()$ Func |crv-expm1l|
|
|
$fabs()$ Func |crv-fabs|
|
|
$fabsf()$ Func |crv-fabsf|
|
|
$fabsl()$ Func |crv-fabsl|
|
|
$fdim()$ Func |crv-fdim|
|
|
$fdimf()$ Func |crv-fdimf|
|
|
$fdiml()$ Func |crv-fdiml|
|
|
$floor()$ Func |crv-floor|
|
|
$floorf()$ Func |crv-floorf|
|
|
$floorl()$ Func |crv-floorl|
|
|
$fmin()$ Func |crv-fmin|
|
|
$fminf()$ Func |crv-fminf|
|
|
$fminl()$ Func |crv-fminl|
|
|
$fma()$ Func |crv-fma|
|
|
$fmaf()$ Func |crv-fmaf|
|
|
$fmal()$ Func |crv-fmal|
|
|
$fmax()$ Func |crv-fmax|
|
|
$fmaxf()$ Func |crv-fmaxf|
|
|
$fmaxl()$ Func |crv-fmaxl|
|
|
$fmod()$ Func |crv-fmod|
|
|
$fmodf()$ Func |crv-fmodf|
|
|
$fmodl()$ Func |crv-fmodl|
|
|
$FP_FAST_FMA$ Macro |crv-FP_FAST_FMA|
|
|
$FP_FAST_FMAF$ Macro |crv-FP_FAST_FMAF|
|
|
$FP_FAST_FMAL$ Macro |crv-FP_FAST_FMAL|
|
|
$FP_ILOGB0$ Macro |crv-FP_ILOGB0|
|
|
$FP_ILOGBNAN$ Macro |crv-FP_ILOGBNAN|
|
|
$frexp()$ Func |crv-frexp|
|
|
$frexpf()$ Func |crv-frexpf|
|
|
$frexpl()$ Func |crv-frexpl|
|
|
$hypot()$ Func |crv-hypot|
|
|
$hypotf()$ Func |crv-hypotf|
|
|
$hypotl()$ Func |crv-hypotl|
|
|
$ilogb()$ Func |crv-ilogb|
|
|
$ilogbf()$ Func |crv-ilogbf|
|
|
$ilogbl()$ Func |crv-ilogbl|
|
|
$isfinite()$ Macro |crv-isfinite|
|
|
$isgreater()$ Macro |crv-isgreater|
|
|
$isgreaterequal()$Macro |crv-isgreaterequal|
|
|
$isinf()$ Macro |crv-isinf|
|
|
$isless()$ Macro |crv-isless|
|
|
$islessequal()$ Macro |crv-islessequal|
|
|
$islessgreater()$ Macro |crv-islessgreater|
|
|
$isnan()$ Macro |crv-isnan|
|
|
$isnormal()$ Macro |crv-isnormal|
|
|
$isunordered()$ Macro |crv-isunordered|
|
|
$ldexp()$ Func |crv-ldexp|
|
|
$ldexpf()$ Func |crv-ldexpf|
|
|
$ldexpl()$ Func |crv-ldexpl|
|
|
$lgamma()$ Func |crv-lgamma|
|
|
$lgammaf()$ Func |crv-lgammaf|
|
|
$lgammal()$ Func |crv-lgammal|
|
|
$log()$ Func |crv-log|
|
|
$logf()$ Func |crv-logf|
|
|
$logl()$ Func |crv-logl|
|
|
$log10()$ Func |crv-log10|
|
|
$log10f()$ Func |crv-log10f|
|
|
$log10l()$ Func |crv-log10l|
|
|
$log1p()$ Func |crv-log1p|
|
|
$log1pf()$ Func |crv-log1pf|
|
|
$log1pl()$ Func |crv-log1pl|
|
|
$log2()$ Func |crv-log2|
|
|
$log2f()$ Func |crv-log2f|
|
|
$log2l()$ Func |crv-log2l|
|
|
$logb()$ Func |crv-logb|
|
|
$logbf()$ Func |crv-logbf|
|
|
$logbl()$ Func |crv-logbl|
|
|
$lrint()$ Func |crv-lrint|
|
|
$lrintf()$ Func |crv-lrintf|
|
|
$lrintl()$ Func |crv-lrintl|
|
|
$llrint()$ Func |crv-llrint|
|
|
$llrintf()$ Func |crv-llrintf|
|
|
$llrintl()$ Func |crv-llrintl|
|
|
$lround()$ Func |crv-lround|
|
|
$lroundf()$ Func |crv-lroundf|
|
|
$lroundl()$ Func |crv-lroundl|
|
|
$llround()$ Func |crv-llround|
|
|
$llroundf()$ Func |crv-llroundf|
|
|
$llroundl()$ Func |crv-llroundl|
|
|
$modf()$ Func |crv-modf|
|
|
$modff()$ Func |crv-modff|
|
|
$modfl()$ Func |crv-modfl|
|
|
$nan()$ Func |crv-nan|
|
|
$nanf()$ Func |crv-nanf|
|
|
$nanl()$ Func |crv-nanl|
|
|
$nearbyint()$ Func |crv-nearbyint|
|
|
$nearbyintf()$ Func |crv-nearbyintf|
|
|
$nearbyintl()$ Func |crv-nearbyintl|
|
|
$nextafter()$ Func |crv-nextafter|
|
|
$nextafterf()$ Func |crv-nextafterf|
|
|
$nextafterl()$ Func |crv-nextafterl|
|
|
$nexttoward()$ Func |crv-nexttoward|
|
|
$nexttowardf()$ Func |crv-nexttowardf|
|
|
$nexttowardl()$ Func |crv-nexttowardl|
|
|
$pow()$ Func |crv-pow|
|
|
$powf()$ Func |crv-powf|
|
|
$powl()$ Func |crv-powl|
|
|
$remainder()$ Func |crv-remainder|
|
|
$remainderf()$ Func |crv-remainderf|
|
|
$remainderl()$ Func |crv-remainderl|
|
|
$remquo()$ Func |crv-remquo|
|
|
$remquof()$ Func |crv-remquof|
|
|
$remquol()$ Func |crv-remquol|
|
|
$rint()$ Func |crv-rint|
|
|
$rintf()$ Func |crv-rintf|
|
|
$rintl()$ Func |crv-rintl|
|
|
$round()$ Func |crv-round|
|
|
$roundf()$ Func |crv-roundf|
|
|
$roundl()$ Func |crv-roundl|
|
|
$scalbn()$ Func |crv-scalbn|
|
|
$scalbnf()$ Func |crv-scalbnf|
|
|
$scalbnl()$ Func |crv-scalbnl|
|
|
$scalbln()$ Func |crv-scalbln|
|
|
$scalblnf()$ Func |crv-scalblnf|
|
|
$scalblnl()$ Func |crv-scalblnl|
|
|
$signbit()$ Macro |crv-signbit|
|
|
$signgam$ Var |crv-signgam|
|
|
$sin()$ Func |crv-sin|
|
|
$sinf() $ Func |crv-sinf|
|
|
$sinh()$ Func |crv-sinh|
|
|
$sinhf()$ Func |crv-sinhf|
|
|
$sinhl()$ Func |crv-sinhl|
|
|
$sinl()$ Func |crv-sinl|
|
|
$sqrt()$ Func |crv-sqrt|
|
|
$sqrtf()$ Func |crv-sqrtf|
|
|
$sqrtl()$ Func |crv-sqrtl|
|
|
$tan()$ Func |crv-tan|
|
|
$tanf()$ Func |crv-tanf|
|
|
$tanh()$ Func |crv-tanh|
|
|
$tanhf()$ Func |crv-tanhf|
|
|
$tanhl()$ Func |crv-tanhl|
|
|
$tanl()$ Func |crv-tanl|
|
|
$tgamma()$ Func |crv-tgamma|
|
|
$tgammaf()$ Func |crv-tgammaf|
|
|
$tgammal()$ Func |crv-tgammal|
|
|
$trunc()$ Func |crv-trunc|
|
|
$truncf()$ Func |crv-truncf|
|
|
$truncl()$ Func |crv-truncl|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.12.1 Error Conditions *crv-libMHErr*
|
|
|
|
All functions declared in$<math.h>$do handle errors in a very similar way.
|
|
|
|
If an argument is outside the domain over a function is defined a domain
|
|
error occurs, then$errno$is set to$EDOM$. The value that the function returns
|
|
is implementation specific.
|
|
|
|
If the result of a function cannot be represented in the type of return value,
|
|
a range error occurs.
|
|
If the result overflows, the function returns the value of the macro
|
|
$HUGE_VAL$, with the same sign as the correct value of the function;
|
|
$errno$is set to$ERANGE$.
|
|
|
|
If the result underflows, the function returns 0; whether or not$errno$is
|
|
set to$ERANGE$is implementation-defined.
|
|
|
|
|
|
HUGE_VAL Macro *crv-HUGE_VAL*
|
|
HUGE_VALF Macro *crv-HUGE_VALF*
|
|
HUGE_VALL Macro *crv-HUGE_VALL*
|
|
---------------
|
|
This macro expands to a positive$double$constant. On machines that use
|
|
IEEE 754 floating point format,$HUGE_VAL$is infinity. On other machines,
|
|
it's typically the largest positive number that can be represented.
|
|
$HUGE_VALF$and$HUGE_VALL$are the analogs for$float$and$long double$.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.12.2 Classification Macros *crv-libMHClass*
|
|
|
|
|
|
fpclassify() Macro *crv-fpclassify*
|
|
------------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$int fpclassify(float-type x;$
|
|
|
|
Return~
|
|
FP_NAN
|
|
The floating-point number x is "Not a Number"
|
|
|
|
FP_INFINITE
|
|
The value of x is either plus or minus infinity.
|
|
|
|
FP_ZERO
|
|
The value of x is zero.
|
|
|
|
FP_SUBNORMAL
|
|
Numbers whose absolute value is too small to be represented in the normal
|
|
format are represented in an alternate, denormalized format
|
|
(see |crv-dtFormatsFPBasics|)
|
|
|
|
FP_NORMAL
|
|
This value is returned for all other values of x. It indicates that there
|
|
is nothing special about the number.
|
|
|
|
Description~
|
|
This is a generic macro which works on all floating-point types.
|
|
It classifies its argument as NaN, infinite, normal, subnormal, zero or into
|
|
another implementation-defined category.
|
|
|
|
|
|
|
|
isfinite() Macro *crv-isfinite*
|
|
----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$int isfinite(float-type x);$
|
|
|
|
Return~
|
|
0: x is not finite
|
|
else x is finite
|
|
|
|
Description~
|
|
This is a generic macro which works on all floating-point types.
|
|
This macro returns a nonzero value if x is finite: not plus or minus infinity,
|
|
and not NaN. It is equivalent to
|
|
$(fpclassify (x) != FP_NAN && fpclassify (x) != FP_INFINITE)$
|
|
|
|
|
|
|
|
isnormal() Macro *crv-isnormal*
|
|
----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$int isnormal(float-type x);$
|
|
|
|
Return~
|
|
0: x is not normal
|
|
else x is normal
|
|
|
|
Description~
|
|
This is a generic macro which works on all floating-point types.
|
|
This macro returns a nonzero value if x is finite and normalized.
|
|
It is equivalent to
|
|
$(fpclassify (x) == FP_NORMAL)$
|
|
|
|
|
|
|
|
isnan() Macro *crv-isnan*
|
|
-------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$int isnan(float-type x);$
|
|
|
|
Return~
|
|
0: x is not NaN
|
|
else x is NaN
|
|
|
|
Description~
|
|
This is a generic macro which works on all floating-point types.
|
|
This macro returns a nonzero value if x is NaN. It is equivalent to
|
|
$(fpclassify (x) == FP_NAN)$
|
|
|
|
|
|
|
|
isinf() Macro *crv-isinf*
|
|
-------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$int isinf(float-type x);$
|
|
|
|
Return~
|
|
0: x is not infinite
|
|
else x is infinite
|
|
|
|
Description~
|
|
This is a generic macro which works on all floating-point types.
|
|
This macro returns a nonzero value if x is infinte. It is equivalent to
|
|
$(fpclassify (x) == FP_INFINITE)$
|
|
~
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.12.3 Comparison Macros *crv-libMHCmp*
|
|
|
|
All macros below are generic macros that work on all floating-point types.
|
|
|
|
|
|
isgreater() Macro *crv-isgreater*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$int isgreater(float-type x, float-type y);$
|
|
|
|
Return~
|
|
0: x is not greater y
|
|
else x is greater y
|
|
|
|
Description~
|
|
This macro determines whether the argument x is greater than y.
|
|
It is equivalent to (x) > (y), but no exception is raised if x or y are NaN.
|
|
|
|
|
|
|
|
isgreaterequal() Macro *crv-isgreaterequal*
|
|
----------------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$int isgreaterequal(float-type x, float-type y);$
|
|
|
|
Return~
|
|
0: x is not greater or equal y
|
|
else x is greater or equal y
|
|
|
|
Description~
|
|
This macro determines whether the argument x is greater than or equal to y.
|
|
It is equivalent to (x) >= (y), but no exception is raised if x or y are NaN.
|
|
|
|
|
|
|
|
isless() Macro *crv-isless*
|
|
--------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$int isless(float-type x, float-type y);$
|
|
|
|
Return~
|
|
0: x is not less y
|
|
else x is less y
|
|
|
|
Description~
|
|
This macro determines whether the argument x is less than y. It is equivalent
|
|
to (x) < (y), but no exception is raised if x or y are NaN.
|
|
|
|
|
|
|
|
islessequal() Macro *crv-islessequal*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$int islessequal(float-type x, float-type y);$
|
|
|
|
Return~
|
|
0: x is not less or equal y
|
|
else x is less or equal y
|
|
|
|
Description~
|
|
This macro determines whether the argument x is less than or equal to y. It is
|
|
equivalent to (x) <= (y), but no exception is raised if x or y are NaN.
|
|
|
|
|
|
|
|
islessgreater() Macro *crv-islessgreater*
|
|
---------------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$int islessgreater(float-type x, float-type y);$
|
|
|
|
Return~
|
|
0: x is not less or greater y
|
|
else x is less or greater y
|
|
|
|
Description~
|
|
This macro determines whether the argument x is less or greater than y. It is
|
|
equivalent to (x) < (y) || (x) > (y) (although it only evaluates x and y
|
|
once), but no exception is raised if x or y are NaN.
|
|
This macro is not equivalent to x != y, because that expression is true if x
|
|
or y are NaN.
|
|
|
|
|
|
|
|
isunordered() Macro *crv-isunordered*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$int isunordered(float-type x, float-type y);$
|
|
|
|
Return~
|
|
0: x and y are not unordered
|
|
else x or y is unordered
|
|
|
|
Description~
|
|
This macro determines whether its arguments are unordered. In other words,
|
|
it is true if x or y are NaN, and false otherwise.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.12.4 Trigonometric *crv-libMHTrig*
|
|
|
|
|
|
asin() Functions *crv-asin* *crv-asinf* *crv-asinl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double asin(double x);$
|
|
$float asinf(float x);$
|
|
$long double asinl(long double x);$
|
|
|
|
Return~
|
|
range -PI/2...+PI/2
|
|
|
|
Description~
|
|
These functions compute the arc sine of x. The value is in units of radians.
|
|
The arc sine function is defined mathematically only over the domain -1 to 1.
|
|
If x is outside the domain, asin signals a domain error.
|
|
|
|
|
|
|
|
acos() Functions *crv-acos* *crv-acosf* *crv-acosl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double acos(double x);$
|
|
$float acosf(float x);$
|
|
$long double acosl(long double x);$
|
|
|
|
Return~
|
|
range 0...PI
|
|
|
|
Description~
|
|
These functions compute the arc cosine of x. The value is in units of radians.
|
|
The arc cosine function is defined mathematically only over the domain -1 to
|
|
1. If x is outside the domain, acos signals a domain error.
|
|
|
|
|
|
atan() Functions *crv-atan* *crv-atanf* *crv-atanl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double atan(double x);$
|
|
$float atanf(float x);$
|
|
$long double atanl(long double x);$
|
|
|
|
Return~
|
|
range -PI/2...+PI/2
|
|
|
|
Description~
|
|
These functions compute the arc tangent of x. The value is in units of
|
|
radians.
|
|
|
|
|
|
atan2() Functions *crv-atan2* *crv-atan2f* *crv-atan2l*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double atan2(double x);$
|
|
$float atan2f(float x);$
|
|
$long double atan2l(long double x);$
|
|
|
|
Return~
|
|
range -PI...+PI
|
|
If both x and y are zero, atan2 returns zero.
|
|
|
|
Description~
|
|
This function computes the arc tangent of y/x, but the signs of both arguments
|
|
are used to determine the quadrant of the result, and x is permitted to be
|
|
zero. The return value is given in radians.
|
|
|
|
If x and y are coordinates of a point in the plane, atan2 returns the signed
|
|
angle between the line from the origin to that point and the x-axis.
|
|
Thus, atan2 is useful for converting Cartesian coordinates to polar
|
|
coordinates.
|
|
|
|
|
|
|
|
sin() Functions *crv-sin* *crv-sinf* *crv-sinl*
|
|
---------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double sin(double x);$
|
|
$float sinf(float x);$
|
|
$long double sinl(long double x);$
|
|
|
|
Return~
|
|
range -1...+1
|
|
|
|
Description~
|
|
These functions return the sine of x, where x is given in radians.
|
|
|
|
|
|
cos() Functions *crv-cos* *crv-cosf* *crv-cosl*
|
|
---------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double cos(double x);$
|
|
$float cosf(float x);$
|
|
$long double cosl(long double x);$
|
|
|
|
Return~
|
|
range -1...+1
|
|
|
|
Description~
|
|
These functions return the cosine of x, where x is given in radians.
|
|
|
|
|
|
tan() Functions *crv-tan* *crv-tanf* *crv-tanl*
|
|
---------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double tan(double x);$
|
|
$float tanf(float x);$
|
|
$long double tanl(long double x);$
|
|
|
|
Return~
|
|
tangent of x
|
|
|
|
Description~
|
|
These functions return the tangent of x, where x is given in radians.
|
|
Mathematically, the tangent function has singularities at odd multiples of
|
|
PI/2. If the argument x is too close to one of these singularities,$tan()$
|
|
will signal overflow.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.12.5 Hyperbolic *crv-libMHHyper*
|
|
|
|
|
|
sinh() Functions *crv-sinh* *crv-sinhf* *crv-sinhl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double sinh(double x);$
|
|
$float sinhf(float x);$
|
|
$long double sinhl(long double x);$
|
|
|
|
Return~
|
|
hyperbolic sine of x
|
|
|
|
Description~
|
|
These functions return the hyperbolic sine of x, defined mathematically as
|
|
(exp(x) - exp(-x)) / 2. They may signal overflow if x is too large.
|
|
|
|
|
|
|
|
cosh() Functions *crv-cosh* *crv-coshf* *crv-coshl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double cosh(double x);$
|
|
$float coshf(float x);$
|
|
$long double coshl(long double x);$
|
|
|
|
Return~
|
|
hyperbolic cosine of x
|
|
|
|
Description~
|
|
These function return the hyperbolic cosine of x, defined mathematically as
|
|
(exp(x) + exp(-x)) / 2. They may signal overflow if x is too large.
|
|
|
|
|
|
|
|
tanh() Functions *crv-tanh* *crv-tanhf* *crv-tanhl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double tanh(double x);$
|
|
$float tanhf(float x);$
|
|
$long double tanhl(long double x);$
|
|
|
|
Return~
|
|
hyperbolic tangent of x
|
|
|
|
Description~
|
|
These functions return the hyperbolic tangent of x, defined mathematically as
|
|
sinh(x) / cosh(x). They may signal overflow if x is too large.
|
|
|
|
|
|
|
|
asinh() Functions *crv-asinh* *crv-asinhf* *crv-asinhl*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double asinh(double x);$
|
|
$float asinhf(float x);$
|
|
$long double asinhl(long double x);$
|
|
|
|
Return~
|
|
inverse hyperbolic sine of x
|
|
|
|
Description~
|
|
These functions return the inverse hyperbolic sine of x.
|
|
|
|
|
|
|
|
acosh() Functions *crv-acosh* *crv-acoshf* *crv-acoshl*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double acosh(double x);$
|
|
$float acoshf(float x);$
|
|
$long double acoshl(long double x);$
|
|
|
|
Return~
|
|
inverse hyperbolic cosine of x
|
|
|
|
Description~
|
|
These functions return the inverse hyperbolic cosine of x. If x is less than
|
|
1, acosh signals a domain error.
|
|
|
|
|
|
|
|
atanh() Functions *crv-atanh* *crv-atanhf* *crv-atanhl*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double atanh(double x);$
|
|
$float atanhf(float x);$
|
|
$long double atanhl(long double x);$
|
|
|
|
Return~
|
|
inverse hyperbolic tangent of x
|
|
|
|
Description~
|
|
These functions return the inverse hyperbolic tangent of x. If the absolute
|
|
value of x is greater than 1,$atanh()$signals a domain error; if it is
|
|
equal to 1, it returns infinity.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.12.6 Exponential & Logarithmic *crv-libMHExpLog*
|
|
|
|
|
|
|
|
exp() Functions *crv-exp* *crv-expf* *crv-expl*
|
|
---------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double exp(double x);$
|
|
$float expf(float x);$
|
|
$long double expl(long double x);$
|
|
|
|
Return~
|
|
e^x
|
|
|
|
Description~
|
|
These functions compute e (the base of natural logarithms) raised to the
|
|
power x. If the magnitude of the result is too large to be representable,
|
|
$exp()$signals overflow.
|
|
|
|
|
|
|
|
exp2() Functions *crv-exp2* *crv-exp2f* *crv-exp2l*
|
|
----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double exp2(double x);$
|
|
$float exp2f(float x);$
|
|
$long double exp2l(long double x);$
|
|
|
|
Return~
|
|
2^x
|
|
|
|
Description~
|
|
These functions compute 2 raised to the power x. Mathematically,$exp2(x)$is
|
|
the same as exp(x * log(2)).
|
|
|
|
|
|
|
|
expm1() Functions *crv-expm1* *crv-expm1f* *crv-expm1l*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double expm1(double x);$
|
|
$float expm1f(float x);$
|
|
$long double expm1l(long double x);$
|
|
|
|
Return~
|
|
exp(x)-1
|
|
|
|
Description~
|
|
These functions return a value equivalent to exp(x) - 1. They are computed in a
|
|
way that is accurate even if x is near zero - a case where exp(x) - 1 would be
|
|
inaccurate owing to subtraction of two numbers that are nearly equal.
|
|
|
|
|
|
|
|
|
|
ilogb() Functions *crv-ilogb* *crv-ilogbf* *crv-ilogbl*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$int ilogb(double x);$
|
|
$int ilogbf(float x);$
|
|
$int ilogbl(long double x);$
|
|
|
|
Return~
|
|
|
|
|
|
Description~
|
|
These functions are equivalent to the corresponding logb() functions except
|
|
that they return signed integer values. Since integers cannot represent
|
|
infinity and NaN,$ilogb()$instead returns an integer that can't be the
|
|
exponent of a normal floating-point number, the macros are:
|
|
|
|
FP_ILOGB0 Macro *crv-FP_ILOGB0*
|
|
$ilogb()$returns this value if its argument is 0. The numeric value is
|
|
either$INT_MIN$or$-INT_MAX$.
|
|
|
|
FP_ILOGBNAN Macro *crv-FP_ILOGBNAN*
|
|
$ilogb()$returns this value if its argument is NaN. The numeric value is
|
|
either$INT_MIN$or$INT_MAX$.
|
|
|
|
|
|
|
|
log() Functions *crv-log* *crv-logf* *crv-logl*
|
|
---------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double log(double x);$
|
|
$float logf(float x);$
|
|
$long double logl(long double x);$
|
|
|
|
Return~
|
|
see description
|
|
|
|
Description~
|
|
These functions compute the natural logarithm of x. If x is negative,$log()$
|
|
signals a domain error. If x is zero, it returns negative infinity;
|
|
if x is too close to zero, it may signal overflow.
|
|
|
|
|
|
|
|
log10() Functions *crv-log10* *crv-log10f* *crv-log10l*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double log10(double x);$
|
|
$float log10f(float x);$
|
|
$long double log10l(long double x);$
|
|
|
|
Return~
|
|
base-10 logarithm of x
|
|
|
|
Description~
|
|
These functions return the base-10 logarithm of x.
|
|
$log10(x)$equals$log(x) / log(10)$
|
|
|
|
|
|
|
|
log1p() Functions *crv-log1p* *crv-log1pf* *crv-log1pl*
|
|
------------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double log1p(double x);$
|
|
$float log1pf(float x);$
|
|
$long double log1pl(long double x);$
|
|
|
|
Return~
|
|
log(1+x)
|
|
|
|
Description~
|
|
These functions returns a value equivalent to log(1 + x). They are computed
|
|
in a way that is accurate even if x is near zero.
|
|
|
|
|
|
|
|
log2() Functions *crv-log2* *crv-log2f* *crv-log2l*
|
|
----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double log2(double x);$
|
|
$float log2f(float x);$
|
|
$long double log2l(long double x);$
|
|
|
|
Return~
|
|
base-2 logarithm of x
|
|
|
|
Description~
|
|
These functions return the base-2 logarithm of x.
|
|
$log2(x)$equals$log(x) / log(2)$
|
|
|
|
|
|
|
|
logb() Functions *crv-logb* *crv-logbf* *crv-logbl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double log2(double x);$
|
|
$float log2f(float x);$
|
|
$long double log2l(long double x);$
|
|
|
|
Return~
|
|
see description
|
|
|
|
Description~
|
|
These functions extract the exponent of x and return it as a floating-point
|
|
value. If FLT_RADIX is two,$logb()$is equal to$floor(log2 (x))$, except it's
|
|
probably faster.
|
|
If x is denormalized,$logb()$returns the exponent x would have if it were
|
|
normalized. If x is infinity (positive or negative),$logb()$returns ∞.
|
|
If x is zero,$logb()$returns ∞. It does not signal.
|
|
|
|
|
|
|
|
|
|
frexp() Functions *crv-frexp* *crv-frexpf* *crv-frexpl*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double frexp(double x, int *exponent);$
|
|
$float frexpf(float x, int *exponent);$
|
|
$long double frexpl(long double x, int *exponent);$
|
|
|
|
Return~
|
|
see description
|
|
|
|
Description~
|
|
These functions are used to split the number value into a normalized fraction
|
|
and an exponent.
|
|
If the argument value is not zero, the return value is value times a power
|
|
of two, and is always in the range 1/2 (inclusive) to 1 (exclusive). The
|
|
corresponding exponent is stored in *exponent; the return value multiplied
|
|
by 2 raised to this exponent equals the original number value.
|
|
|
|
For example,$frexp(12.8, &exponent)$returns 0.8 and stores 4 in exponent.
|
|
|
|
If value is zero, then the return value is zero and zero is stored in
|
|
*exponent.
|
|
|
|
|
|
|
|
ldexp() Functions *crv-ldexp* *crv-ldexpf* *crv-ldexpl*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double ldexp(double x, int exponent);$
|
|
$float ldexpf(float x, int exponent);$
|
|
$long double ldexpl(long double x, int exponent);$
|
|
|
|
Return~
|
|
see description
|
|
|
|
Description~
|
|
These functions return the result of multiplying the floating-point number
|
|
value by 2 raised to the power exponent.
|
|
(It can be used to reassemble floating-point numbers that were taken apart
|
|
by$frexp()$) .
|
|
For example,$ldexp(0.8, 4)$returns 12.8.
|
|
|
|
|
|
|
|
modf() Functions *crv-modf* *crv-modff* *crv-modfl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double modf(double x, double *intpart);$
|
|
$float modff(float x, float *intpart);$
|
|
$long double modfl(long double x, long double *intpart);$
|
|
|
|
Return~
|
|
stores the integer part in *intpart, and returns the fractional part
|
|
|
|
Description~
|
|
These functions break the argument value into an integer part and a fractional
|
|
part (between -1 and 1, exclusive). Their sum equals value. Each of the parts
|
|
has the same sign as value, and the integer part is always rounded toward zero.
|
|
|
|
Example:$modf(2.5, &intpart)$returns 0.5 and stores 2.0 into intpart.
|
|
|
|
|
|
|
|
scalbn() Functions *crv-scalbn* *crv-scalbnf* *crv-scalbnl*
|
|
------------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double scalbn(double x, int n);$
|
|
$float scalbnf(float x, int n);$
|
|
$long double scalbnl(long double x, int n);$
|
|
|
|
Return~
|
|
x*FLT_RADIX^n
|
|
|
|
Description~
|
|
These functions compute x * FLT_RADIX^n efficiently (commonly FLT_RADIX is 2).
|
|
n is of type$int$, for type$long int$see$scalbln()$.
|
|
|
|
|
|
|
|
scalbln() Functions *crv-scalbln* *crv-scalblnf* *crv-scalblnl*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double scalbln(double x, long int n);$
|
|
$float scalblnf(float x, long int n);$
|
|
$long double scalblnl(long double x, long int n);$
|
|
|
|
Return~
|
|
x*FLT_RADIX^n
|
|
|
|
Description~
|
|
These functions compute x * FLT_RADIX^n efficiently (commonly FLT_RADIX is 2).
|
|
n is of type$long int$, for type$int$see$scalbn()$.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.12.7 Power & Absolute *crv-libMHPower*
|
|
|
|
|
|
cbrt() Functions *crv-cbrt* *crv-cbrtf* *crv-cbrtl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double cbrt(double x);$
|
|
$float cbrtf(float x);$
|
|
$long double cbrtl(long double x);$
|
|
|
|
Return~
|
|
cube root of x
|
|
|
|
Description~
|
|
These functions return the cube root of x. They cannot fail; every
|
|
representable real value has a representable real cube root.
|
|
|
|
|
|
|
|
fabs() Functions *crv-fabs* *crv-fabsf* *crv-fabsl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double fabs(double x);$
|
|
$float fabsf(float x);$
|
|
$long double fabsl(long double x);$
|
|
|
|
Return~
|
|
absolute of x
|
|
|
|
Description~
|
|
This function returns the absolute value of the floating-point number x.
|
|
|
|
|
|
hypot() Functions *crv-hypot* *crv-hypotf* *crv-hypotl*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double hypot(double x, double y);$
|
|
$float hypotf(float x, float y);$
|
|
$long double hypotl(long double x, long double y);$
|
|
|
|
Return~
|
|
sqrt(x*x + y*y)
|
|
|
|
Description~
|
|
These functions return sqrt(x*x + y*y).
|
|
Normally this function is faster and more accurate than the direct formula.
|
|
|
|
|
|
|
|
pow() Functions *crv-pow* *crv-powf* *crv-powl*
|
|
---------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double pow(double x, double y);$
|
|
$float powf(float x, float y);$
|
|
$long double powl(long double x, long double y);$
|
|
|
|
Return~
|
|
x^y
|
|
|
|
Description~
|
|
These are general exponentiation functions, returning base raised to power
|
|
(x^y).
|
|
|
|
Mathematically,$pow()$would return a complex number when base is negative and
|
|
power is not an integral value.$pow$can't do that, so instead it signals a
|
|
domain error.$pow$may also underflow or overflow the destination type.
|
|
|
|
|
|
|
|
sqrt() Functions *crv-sqrt* *crv-sqrtf* *crv-sqrtl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double sqrt(double x);$
|
|
$float sqrtf(float x);$
|
|
$long double sqrtl(long double x);$
|
|
|
|
Return~
|
|
sqrt(x)
|
|
|
|
Description~
|
|
These functions return the nonnegative square root of x.
|
|
If x is negative,$sqrt()$signals a domain error. Mathematically, it should
|
|
return a complex number.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.12.8 Error & Gamma *crv-libMHErrGam*
|
|
|
|
|
|
erf() Functions *crv-erf* *crv-erff* *crv-erfl*
|
|
---------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double erf(double x);$
|
|
$float erff(float x);$
|
|
$long double erfl(long double x);$
|
|
|
|
Return~
|
|
error function of x
|
|
|
|
Description~
|
|
$erf()$returns the error function of x. The error function is defined as
|
|
erf(x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt
|
|
|
|
|
|
erfc() Functions *crv-erfc* *crv-erfcf* *crv-erfcl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double erf(double x);$
|
|
$float erff(float x);$
|
|
$long double erfl(long double x);$
|
|
|
|
Return~
|
|
1 - error function of x
|
|
|
|
Description~
|
|
$erfc()$returns 1.0 -$erf(x)$, but computed in a fashion that avoids
|
|
round-off error when x is large.
|
|
|
|
|
|
lgamma() Functions *crv-lgamma* *crv-lgammaf* *crv-lgammal*
|
|
------------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double lgamma(double x);$
|
|
$float lgammaf(float x);$
|
|
$long double lgammal(long double x);$
|
|
|
|
Return~
|
|
see description
|
|
|
|
Description~
|
|
$lgamma()$returns the natural logarithm of the absolute value of the gamma
|
|
function of x. The gamma function is defined as
|
|
|
|
gamma(x) = integral from 0 to ∞ of t^(x-1) e^-t dt
|
|
|
|
*crv-signgam*
|
|
The sign of the gamma function is stored in the global variable$signgam$,
|
|
which is declared in$<math.h>$. It is 1 if the intermediate result was
|
|
positive or zero, or -1 if it was negative.
|
|
|
|
To compute the real gamma function $tgamma()$can be used or the values as
|
|
can be computed as follows:
|
|
|
|
lgam = lgamma(x);
|
|
gam = signgam*exp(lgam);
|
|
|
|
|
|
The gamma function has singularities at the non-positive integers.$lgamma()$
|
|
will raise the zero divide exception if evaluated at a singularity.
|
|
|
|
|
|
|
|
tgamma() Functions *crv-tgamma* *crv-tgammaf* *crv-tgammal*
|
|
------------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double tgamma(double x);$
|
|
$float tgammaf(float x);$
|
|
$long double tgammal(long double x);$
|
|
|
|
Return~
|
|
see description
|
|
|
|
Description~
|
|
$tgamma()$applies the gamma function to x. The gamma function is defined as
|
|
gamma (x) = integral from 0 to ∞ of t^(x-1) e^-t dt
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.12.9 Nearest Integer *crv-libMHNear*
|
|
|
|
|
|
ceil() Functions *crv-ceil* *crv-ceilf* *crv-ceill*
|
|
----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double ceil(double x);$
|
|
$float ceilf(float x);$
|
|
$long double ceill(long double x);$
|
|
|
|
Return~
|
|
x rounded upwards
|
|
|
|
Description~
|
|
These functions round x upwards to the nearest integer, returning that value
|
|
as a double. Thus, ceil(1.5)$ is 2.0.
|
|
|
|
|
|
|
|
floor() Functions *crv-floor* *crv-floorf* *crv-floorl*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double floor(double x);$
|
|
$float floorf(float x);$
|
|
$long double floorl(long double x);$
|
|
|
|
Return~
|
|
x rounded downwards
|
|
|
|
Description~
|
|
These functions round x downwards to the nearest integer, returning that value
|
|
as a double. Thus,$floor(1.5)$is 1.0 and$floor(-1.5)$is -2.0.
|
|
|
|
|
|
|
|
trunc() Functions *crv-trunc* *crv-truncf* *crv-truncl*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double trunc(double x);$
|
|
$float truncf(float x);$
|
|
$long double truncl(long double x);$
|
|
|
|
Return~
|
|
x rounded towards zero
|
|
|
|
Description~
|
|
These functions round x towards zero to the nearest integer (returned in
|
|
floating-point format). Thus,$trunc(1.5)$is 1.0 and$trunc(-1.5)$is -1.0.
|
|
|
|
|
|
|
|
rint() Functions *crv-rint* *crv-rintf* *crv-rintl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double rint(double x);$
|
|
$float rintf(float x);$
|
|
$long double rintl(long double x);$
|
|
|
|
Return~
|
|
x rounded according to rounding mode
|
|
|
|
Description~
|
|
These functions round x to an integer value according to the current rounding
|
|
mode (for modes see "II.6.3 Rounding" |crv-libFHRounding|). The default
|
|
rounding mode is to round to the nearest integer.
|
|
If x was not initially an integer, these functions raise the inexact
|
|
exception.
|
|
|
|
|
|
*crv-nearbyint*
|
|
nearbyint() Functions *crv-nearbyintf* *crv-nearbyintl*
|
|
---------------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double nearbyint(double x);$
|
|
$float nearbyintf(float x);$
|
|
$long double nearbyintl(long double x);$
|
|
|
|
Return~
|
|
x rounded according to rounding mode
|
|
|
|
Description~
|
|
These functions return the same value as the$rint()$functions, but do not
|
|
raise the inexact exception if x is not an integer.
|
|
|
|
|
|
|
|
round() Functions *crv-round* *crv-roundf* *crv-roundl*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double round(double x);$
|
|
$float roundf(float x);$
|
|
$long double roundl(long double x);$
|
|
|
|
Return~
|
|
see description
|
|
|
|
Description~
|
|
These functions are similar to$rint()$, but they round halfway cases away from
|
|
zero instead of to the nearest even integer.
|
|
|
|
|
|
|
|
lrint() Functions *crv-lrint* *crv-lrintf* *crv-lrintl*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$long int lrint(double x);$
|
|
$long int lrintf(float x);$
|
|
$long int lrintl(long double x);$
|
|
|
|
Return~
|
|
x rounded according to rounding mode
|
|
|
|
Description~
|
|
These functions are just like$rint()$, but they return a$long int$instead of
|
|
a floating-point number.
|
|
|
|
|
|
|
|
llrint() Functions *crv-llrint* *crv-llrintf* *crv-llrintl*
|
|
------------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$long long int llrint(double x);$
|
|
$long long int llrintf(float x);$
|
|
$long long int llrintl(long double x);$
|
|
|
|
Return~
|
|
x rounded according to rounding mode
|
|
|
|
Description~
|
|
These functions are just like$rint()$, but they return a$long long int$instead
|
|
of a floating-point number.
|
|
|
|
|
|
|
|
lround() Functions *crv-lround* *crv-lroundf* *crv-lroundl*
|
|
------------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$long int lround(double x);$
|
|
$long int lroundf(float x);$
|
|
$long int lroundl(long double x);$
|
|
|
|
Return~
|
|
x rounded
|
|
|
|
Description~
|
|
These functions are just like$round()$, but they return a$long int$instead of
|
|
a floating-point number.
|
|
|
|
|
|
|
|
llround() Functions *crv-llround* *crv-llroundf* *crv-llroundl*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$long long int llround(double x);$
|
|
$long long int llroundf(float x);$
|
|
$long long int llroundl(long double x);$
|
|
|
|
Return~
|
|
x rounded
|
|
|
|
Description~
|
|
These functions are just like$round()$, but they return a$long long int$
|
|
instead of a floating-point number.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.12.10 Remainder *crv-libMHRem*
|
|
|
|
|
|
fmod() Functions *crv-fmod* *crv-fmodf* *crv-fmodl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double fmod(double x, double y);$
|
|
$float fmodf(float x, float y);$
|
|
$long double fmodl(long double x, long double y);$
|
|
|
|
Return~
|
|
see description
|
|
|
|
Description~
|
|
These functions compute the remainder from the division of x by. Specifically,
|
|
the return value is x - n*y, where n is the quotient of x divided by y,
|
|
rounded towards zero to an integer. Thus,$fmod(6.5, 2.3)$ returns 1.9, which
|
|
is 6.5 minus 4.6.
|
|
The result has the same sign as x and has magnitude less than the magnitude
|
|
of y.
|
|
If y is zero,$fmod()$signals a domain error.
|
|
|
|
|
|
*crv-remainder*
|
|
remainder() Functions *crv-remainderf* *crv-remainderl*
|
|
---------------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double remainder(double x, double y);$
|
|
$float remainderf(float x, float y);$
|
|
$long double remainderl(long double x, long double y);$
|
|
|
|
Return~
|
|
see description
|
|
|
|
Description~
|
|
These functions are like$fmod()$except that they rounds the internal quotient
|
|
n to the nearest integer instead of towards zero to an integer.
|
|
For example,$remainder(6.5, 2.3)$returns -0.4, which is 6.5 minus 6.9.
|
|
|
|
The absolute value of the result is less than or equal to half the absolute
|
|
value of y. The difference between$fmod(x, y)$and$remainder(x, y)$is always
|
|
either y, -y, or zero.
|
|
If denominator is zero,$remainder()$signals a domain error.
|
|
|
|
|
|
|
|
remquo() Functions *crv-remquo* *crv-remquof* *crv-remquol*
|
|
------------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double remquo(double x, double y, int *quo);$
|
|
$float remquof(float x, float y, int *quo);$
|
|
$long double remquol(long double x, long double y, int *quo);$
|
|
|
|
Return~
|
|
see description
|
|
|
|
Description~
|
|
These functions compute the same remainder as the$remainder()$functions.
|
|
In *quo they store a value whose sign is the singe of x/y and whose
|
|
magnitude is congruent modulo 2^n to the magnitude of the integral quotient
|
|
of x/y, where n is an implementation-defined integer greater or equal to 3.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.12.11 Manipulating *crv-libMHMani*
|
|
|
|
|
|
*crv-copysign*
|
|
copysign() Functions *crv-copysignf* *crv-copysignl*
|
|
--------------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double copysign(double x, double y);$
|
|
$float copysignf(float x, float y);$
|
|
$long double copysignl(long double x, long double y);$
|
|
|
|
Return~
|
|
x with sign of y
|
|
|
|
Description~
|
|
These functions return x but with the sign of y. They work even if x or y are
|
|
NaN or zero. Both of these can carry a sign (although not all implementations
|
|
support it).
|
|
$copysign()$never raises an exception.
|
|
|
|
|
|
|
|
signbit() Macro *crv-signbit*
|
|
---------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$int signbit(float-type x);$
|
|
|
|
Return~
|
|
0: x has no negative sign
|
|
else x has negative sign
|
|
|
|
Description~
|
|
This is a generic macro which works on all floating-point types.
|
|
This macro returns a nonzero value if x is negative.
|
|
This is not the same as x < 0.0, because IEEE 754 floating point allows zero
|
|
to be signed. The comparison -0.0 < 0.0 is false, but$signbit(-0.0)$ will
|
|
return a nonzero value.
|
|
|
|
|
|
*crv-nextafter*
|
|
nextafter() Functions *crv-nextafterf* *crv-nextafterl*
|
|
---------------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double nextafter(double x, double y);$
|
|
$float nextafterf(float x, float y);$
|
|
$long double nextafetl(long double x, long double y);$
|
|
|
|
Return~
|
|
see description
|
|
|
|
Description~
|
|
These functions return the next representable neighbor of x in the direction
|
|
towards y. The size of the step between x and the result depends on the type
|
|
of the result. If x = y the function simply returns y. If either value is
|
|
NaN, NaN is returned. Otherwise a value corresponding to the value of the
|
|
least significant bit in the mantissa is added or subtracted, depending on
|
|
the direction.
|
|
$nextafter()$will signal overflow or underflow if the result goes outside of
|
|
the range of normalized numbers.
|
|
|
|
|
|
*crv-nexttoward*
|
|
nexttoward() Functions *crv-nexttowardf* *crv-nexttowardl*
|
|
----------------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double nexttoward(double x, long double y);$
|
|
$float nexttowardf(float x, long double y);$
|
|
$long double nexttowardl(long double x, long double y);$
|
|
|
|
Return~
|
|
see description
|
|
|
|
Description~
|
|
These functions are identical to the corresponding versions of$nextafter()$
|
|
except that their second argument is a long double.
|
|
|
|
|
|
|
|
nan() Functions *crv-nan* *crv-nanf* *crv-nanl*
|
|
---------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double nan(const char *tagp);$
|
|
$float nanf(const char *tagp);$
|
|
$long double nanl(const char *tagp);$
|
|
|
|
Return~
|
|
NaN
|
|
|
|
Description~
|
|
These functions return a representation of NaN, provided that NaN is supported
|
|
by the target platform.$nan("n-char-sequence")$is equivalent to
|
|
$strtod("NAN(n-char-sequence)")$.
|
|
|
|
The argument tagp is used in an unspecified manner. On IEEE 754 systems, there
|
|
are many representations of NaN, and tagp selects one. On other systems it may
|
|
do nothing.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.12.12 Miscellaneous *crv-libMHMisc*
|
|
|
|
|
|
fdim() Functions *crv-fdim* *crv-fdimf* *crv-fdiml*
|
|
----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double fdim(double x, double y);$
|
|
$float fdimf(float x, float y);$
|
|
$long double fdiml(long double x, long double y);$
|
|
|
|
Return~
|
|
positive difference
|
|
|
|
Description~
|
|
These functions return the positive difference between x and y. The positive
|
|
difference is x - y if x is greater than y, and 0 otherwise.
|
|
If x, y, or both are NaN, NaN is returned.
|
|
|
|
|
|
|
|
fmin() Functions *crv-fmin* *crv-fminf* *crv-fminl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double fmin(double x, double y);$
|
|
$float fminf(float x, float y);$
|
|
$long double fminl(long double x, long double y);$
|
|
|
|
Return~
|
|
minimum of x and y
|
|
|
|
Description~
|
|
These functions return the lesser of the two values x and y. It is similar to
|
|
the expression ((x) < (y) ? (x) : (y)) except that x and y are only evaluated
|
|
once.
|
|
If an argument is NaN, the other argument is returned. If both arguments are
|
|
NaN, NaN is returned.
|
|
|
|
|
|
|
|
fmax() Functions *crv-fmax* *crv-fmaxf* *crv-fmaxl*
|
|
----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double fmax(double x, double y);$
|
|
$float fmaxf(float x, float y);$
|
|
$long double fmaxl(long double x, long double y);$
|
|
|
|
Return~
|
|
maximum of x and y
|
|
|
|
Description~
|
|
These functions return the greater of the two values x and y.
|
|
If an argument is NaN, the other argument is returned. If both arguments are
|
|
NaN, NaN is returned.
|
|
|
|
|
|
|
|
fma() Functions *crv-fma* *crv-fmaf* *crv-fmal*
|
|
----------------
|
|
Synopsis~
|
|
$#include <math.h>$
|
|
$double fma(double x, double y, double z);$
|
|
$float fmaf(float x, float y, float z);$
|
|
$long double fmal(long double x, long double y, long double z);$
|
|
|
|
Return~
|
|
|
|
Description~
|
|
These functions perform floating-point multiply-add. This is the operation
|
|
(x * y) + z, but the intermediate result is not rounded to the destination
|
|
type. This can sometimes improve the precision of a calculation.
|
|
|
|
This function was introduced because some processors have a special
|
|
instruction to perform multiply-add. The C compiler cannot use it directly,
|
|
because the expression x*y + z is defined to round the intermediate result.
|
|
$fma()$lets you choose when you want to round only once.
|
|
|
|
*crv-FP_FAST_FMA*
|
|
*crv-FP_FAST_FMAF* *crv-FP_FAST_FMAL*
|
|
On processors which do not implement multiply-add in hardware,$fma$can be
|
|
very slow since it must avoid intermediate rounding.
|
|
math.h defines the symbols$FP_FAST_FMA$,$FP_FAST_FMAF$, and$FP_FAST_FMAL$ when
|
|
the corresponding version of$fma()$is no slower than the expression x*y + z.
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
II.13 <setjmp.h> Nonlocal Jumps *crv-libSetjmpH*
|
|
|
|
This header file provides a function, a macro and a data type to perform
|
|
nonlocal exits. Typically this is used to do an intermediate return from a
|
|
nested function call.
|
|
|
|
Quicklink:
|
|
$jmp_buf$ Type |crv-libjmp_buf|
|
|
$longjmp()$ Func |crv-liblongjmp|
|
|
$setjmp()$ Macro |crv-libsetjmp|
|
|
|
|
|
|
|
|
jmp_buf Type *crv-jmp_buf*
|
|
------------
|
|
Objects of type$jmp_buf$hold the state information to be restored by a
|
|
nonlocal exit. The contents of a$jmp_buf$identify a specific place to return
|
|
to.
|
|
|
|
|
|
|
|
setjmp() Macro *crv-setjmp*
|
|
--------------
|
|
Synopsis~
|
|
$#include <setjmp.h>$
|
|
$int setjmp(jmp_buf state);$
|
|
|
|
Return~
|
|
0: if normally executed
|
|
!=0: value passed to$longjmp()$
|
|
|
|
Description~
|
|
When called normally,$setjmp()$stores information about the execution state of
|
|
the program in$state$and returns zero. If$longjmp()$is later used to perform
|
|
a nonlocal exit to this state,$setjmp()$returns a nonzero value.
|
|
|
|
Calls to$setjmp()$are safe in only the following contexts:
|
|
- As the test expression of a selection or iteration statement (such as$if,$
|
|
$switch$, or$while$).
|
|
- As one operand of a equality or comparison operator that appears as the
|
|
test expression of a selection or iteration statement. The other operand
|
|
must be an integer constant expression.
|
|
- As the operand of a unary ! operator, that appears as the test expression
|
|
of a selection or iteration statement.
|
|
- By itself as an expression statement.
|
|
|
|
Return points are valid only during the dynamic extent of the function that
|
|
called$setjmp()$to establish them. If returned via$longjmp()$to a return point
|
|
that was established in a function that has already returned, unpredictable
|
|
and disastrous things are likely to happen.
|
|
|
|
|
|
|
|
longjmp() Function *crv-longjmp*
|
|
------------------
|
|
Synopsis~
|
|
$#include <setjmp.h>$
|
|
$void longjmp(jmp_buf state, int value);$
|
|
|
|
Return~
|
|
none
|
|
|
|
Description~
|
|
This function restores current execution to the state saved in$state$, and
|
|
continues execution from the call to$setjmp()$that established that return
|
|
point. Returning from$setjmp()$by means of$longjmp()$returns the value
|
|
argument that was passed to$longjmp()$, rather than 0.
|
|
(But if value is given as 0, setjmp returns 1).
|
|
|
|
|
|
|
|
==============================================================================
|
|
II.14 <signal.h> Signal Handling *crv-libSignalH*
|
|
|
|
This header file defines macros and declares functions for handling signals.
|
|
|
|
Quicklink:
|
|
$rais()$ Func |crv-rais|
|
|
$sig_atomic_t$ Type |crv-sig_atomic_t|
|
|
$SIG_DFL$ Macro |crv-SIG_DFL|
|
|
$SIG_ERR$ Macro |crv-SIG_ERR|
|
|
$SIG_IGN$ Macro |crv-SIG_IGN|
|
|
$SIGABRT$ Macro |crv-SIGABRT|
|
|
$SIGFPE$ Macro |crv-SIGFPE|
|
|
$SIGILL$ Macro |crv-SIGILL|
|
|
$SIGINT$ Macro |crv-SIGINT|
|
|
$signal()$ Func |crv-signal|
|
|
$SIGSEGV$ Macro |crv-SIGSEGV|
|
|
$SIGTERM$ Macro |crv-SIGTERM|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.14.1 Types *crv-libSHTyp*
|
|
|
|
sig_atomic_t Type *crv-sig_atomic_t*
|
|
-----------------
|
|
This is an integer data type. Objects of this type are always accessed
|
|
atomically. Reading and writing this data type is guaranteed to happen in a
|
|
single instruction, so there's no way for a handler to run "in the middle"
|
|
of an access.
|
|
The type sig_atomic_t is always an integer data type, but which one it is,
|
|
and how many bits it contains, may vary from machine to machine.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.14.2 Signals *crv-libSHSig*
|
|
|
|
Valid signals are:
|
|
|
|
Signal | Description
|
|
-----------+---------------------------------------------------
|
|
$SIGABRT$ | abnormal termination (e.g. call of$abort()$) *crv-SIGABRT*
|
|
$SIGFPE$ | arithmetic error (e.g. division by zero, *crv-SIGFPE*
|
|
| overflow)
|
|
$SIGILL$ | illegal instruction *crv-SIGILL*
|
|
$SIGINT$ | interactive attention signal (e.g. interrupt) *crv-SIGINT*
|
|
$SIGSEGV$ | invalid access to storage *crv-SIGSEGV*
|
|
$SIGTERM$ | termination request sent to the program *crv-SIGTERM*
|
|
|
|
Other signals my be specified by the compiler.
|
|
|
|
It depends on the machine whether this signals are generated by the system
|
|
itself.$raise()$function can be used to send them.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.14.3 Functions *crv-libSHFunc*
|
|
|
|
|
|
signal() Function *crv-signal*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <signal.h>$
|
|
$void (*signal(int sig, void (*handler)(int)))(int);$
|
|
|
|
Return~
|
|
- pointer to previous handler, if call was successful
|
|
-$SIG_ERR$, if call failed
|
|
|
|
Description~
|
|
This function chooses one of three ways in which receipt of the signal$sig$is
|
|
to be handled, these ways are:
|
|
*crv-SIG_DFL* *crv-SIG_IGN*
|
|
- If the value of$handler$is$SIG_DFL$, default handling for that signal
|
|
occurs.
|
|
- If the value of$handler$is$SIG_IGN$, the signal is ignored.
|
|
- If the value of$handler$points to a function, that function is called
|
|
with the argument of the type of signal.
|
|
|
|
For valid signals see II.14.2 (|crv-libSHSig|).
|
|
*crv-SIG_ERR*
|
|
If the call to signal is successful, then it returns a pointer to the previous
|
|
signal handler for the specified signal type. If the call fails, then$SIG_ERR$
|
|
is returned and$errno$is set to a positive value.
|
|
|
|
|
|
|
|
rais() Function *crv-rais*
|
|
---------------
|
|
Synopsis~
|
|
$#include <signal.h>$
|
|
$int raise(int signum);$
|
|
|
|
Return~
|
|
0: signal sent successfully
|
|
else: failed
|
|
|
|
Description~
|
|
The raise function sends the signal$signum$to the calling process.
|
|
About the only reason for failure would be if the value of signum is invalid.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.15 <stdarg.h> Arguments *crv-libStdargH*
|
|
|
|
This header files defines macros which allow to handle functions with an
|
|
unknown number of arguments.
|
|
See |crv-fuDefVarPara| for an example.
|
|
|
|
Quicklink:
|
|
$va_arg()$ Macro |crv-libva_arg|
|
|
$va_copy()$ Macro |crv-libva_copy|
|
|
$va_end()$ Macro |crv-libva_end|
|
|
$va_list$ Type |crv-libva_list|
|
|
$va_start()$ Macro |crv-libva_start|
|
|
|
|
|
|
va_list Type *crv-va_list*
|
|
------------
|
|
This type is used for argument pointer variables.
|
|
|
|
|
|
va_start() Macro *crv-va_start*
|
|
----------------
|
|
Synopsis~
|
|
$#include <signal.h>$
|
|
$void va_start(va_list ap, last-required);$
|
|
|
|
Return~
|
|
none
|
|
|
|
Description~
|
|
This macro initializes the argument pointer variable ap to point to the first
|
|
of the optional arguments of the current function; last-required must be the
|
|
last required argument to the function.
|
|
|
|
|
|
|
|
va_arg() Macro *crv-va_arg*
|
|
--------------
|
|
Synopsis~
|
|
$#include <signal.h>$
|
|
$type va_arg(va_list ap, type);$
|
|
|
|
Return~
|
|
value of next argument
|
|
|
|
Description~
|
|
This macro returns the value of the next optional argument, and modifies the
|
|
value of ap to point to the subsequent argument. Thus, successive uses of
|
|
$va_arg()$return successive optional arguments.
|
|
|
|
The type of the value returned by$va_arg()$is$type$as specified in the call.
|
|
|
|
|
|
|
|
va_end() Macro *crv-va_end*
|
|
--------------
|
|
Synopsis~
|
|
$#include <signal.h>$
|
|
$void va_end(va_list ap);$
|
|
|
|
Return~
|
|
none
|
|
|
|
Description~
|
|
This ends the use of ap. After a$va_end()$call, further$va_arg()$calls with
|
|
the same ap may not work.$va_end()$should be invoked before returning from the
|
|
function in which$va_start()$was invoked with the same ap argument.
|
|
|
|
|
|
|
|
va_copy() Macro *crv-va_copy*
|
|
---------------
|
|
Synopsis~
|
|
$#include <signal.h>$
|
|
$void va_copy (va_list dest, va_list src);$
|
|
|
|
Return~
|
|
none
|
|
|
|
Description~
|
|
The$va_copy()$macro allows copying of objects of type$va_list$even if this is
|
|
not an integral type.
|
|
The copies can be used to parse the list of parameters more than once.
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
II.16 <stdbool.h> Boolean Type *crv-libStdboolH*
|
|
|
|
|
|
bool Macro *crv-bool*
|
|
----------
|
|
expands to$_Bool$
|
|
|
|
|
|
true Macro *crv-true*
|
|
----------
|
|
expands to integer constant 1
|
|
|
|
|
|
false Macro *crv-false*
|
|
-----------
|
|
expands to integer constant 0
|
|
|
|
|
|
__bool_true_false_are_defined Macro *crv-__bool_true_false_are_defined*
|
|
-----------------------------------
|
|
expands to integer constant 1
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
II.17 <stddef.h> Definitions *crv-libStddefH*
|
|
|
|
This header file defines some macros and types (some of them are also defined
|
|
in other header files).
|
|
|
|
Quicklink:
|
|
$prtdiff_t$ Type |crv-prtdiff_t|
|
|
$size_t$ Type |crv-size_t|
|
|
$wchar_t$ Type |crv-wchar_t|
|
|
$NULL$ Macro |crv-NULL|
|
|
$offsetof()$ Macro |crv-offsetof|
|
|
|
|
|
|
prtdiff_t Type *crv-prtdiff_t*
|
|
--------------
|
|
This is the signed integer type of the result of subtracting two pointers.
|
|
For example, with the declaration$char *p1, *p2;$, the expression$p2 - p1$is
|
|
of type$ptrdiff_t$.
|
|
|
|
|
|
size_t Type *crv-size_t*
|
|
-----------
|
|
This is an unsigned integer type used to represent the sizes of objects.
|
|
Also declared in$<stdlib.h>$, see |crv-size_t2|.
|
|
Also declared in$<string.h>$, see |crv-size_t3|.
|
|
Also declared in$<time.h>$, see |crv-size_t4|.
|
|
Also declared in$<stdio.h>$, see |crv-size_t5|;
|
|
Also declared in$<wchar.h>$, see |crv-size_t6|.
|
|
|
|
|
|
wchar_t Type *crv-wchar_t*
|
|
------------
|
|
This data type is used as the base type for wide character strings.
|
|
It's range of values can represent distinct codes for all members of the
|
|
largest extended character set specified among the supported locales.
|
|
Also declared in$<stdlib.h>$, see |crv-libwchar_t2|.
|
|
Also declared in$<wchar.h>$, see |crv-libwchar_t3|.
|
|
|
|
|
|
NULL Macro *crv-NULL*
|
|
----------
|
|
Expands to an implementation-defined null pointer constant.
|
|
Also defined in$<stdlib.h>$, see |crv-NULL2|.
|
|
Also defined in$<string.h>$, see |crv-NULL3|.
|
|
Also defined in$<time.h>$, see |crv-NULL4|.
|
|
Also defined in$<stdio.h>$, see |crv-NULL5|.
|
|
Also defined in$<wchar.h>$, see |crv-NULL6|.
|
|
|
|
|
|
|
|
offsetof() Macro *crv-offsetof*
|
|
----------------
|
|
Synopsis~
|
|
$#include <stddef.h>$
|
|
$size_t offsetof (type, member);$
|
|
|
|
Return~
|
|
offset of$member$in structure$type$
|
|
|
|
Description~
|
|
This expands to an integer constant expression that is the offset of the
|
|
structure member named$member$in the structure type$type$.
|
|
|
|
|
|
|
|
==============================================================================
|
|
II.18 <stdint.h> Integer Type *crv-libStdintH*
|
|
|
|
This header file declares a set of integer types having specified widths and
|
|
defines a set of macros to handle them.
|
|
|
|
Types are defined in the following categories:
|
|
- integer types with a certain exact width
|
|
- integer types having at least a certain width
|
|
- fastest integer types having at least a certain width
|
|
- integer types wide enough to hold pointers
|
|
- integer types having greatest width
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.18.1 Integer Types *crv-libSdHType*
|
|
|
|
II.18.1.1 Exact-Width *crv-libSdHTExact*
|
|
----------------------
|
|
There are integer types representing exactly N bits. The general form is:
|
|
intN_t (signed width N bits width)
|
|
uintN_t (unsigned width N bits width)
|
|
|
|
Common types are:
|
|
$int8_t$ $uint8_t$ *crv-int8_t* *crv-uint8_t*
|
|
$int16_t$ $uint16_t$ *crv-int16_t* *crv-uint16_t*
|
|
$int32_t$ $uint32_t$ *crv-int32_t* *crv-uint32_t*
|
|
$int64_t$ $uint64_t$ *crv-int64_t* *crv-uint64_t*
|
|
These types are optional. The compiler is free to declare others (e.g.
|
|
$int24_t$).
|
|
|
|
|
|
II.18.1.2 Minimum-Width *crv-libSdHTMin*
|
|
-----------------------
|
|
There are integer types with at least N bits width. The general form is:
|
|
int_leastN_t (signed with at least N bits width)
|
|
uint_leastN_t (unsigned with at least N bits width)
|
|
|
|
Common types are:
|
|
$int_least8_t$ $uint_least8_t$ *crv-int_least8_t*
|
|
*crv-uint_least8_t*
|
|
$int_least16_t$ $uint_least16_t$ *crv-int_least16_t*
|
|
*crv-uint_least16_t*
|
|
$int_least32_t$ $uint_least32_t$ *crv-int_least32_t*
|
|
*crv-uint_least32_t*
|
|
$int_least64_t$ $uint_least64_t$ *crv-int_least64_t*
|
|
*crv-uint_least64_t*
|
|
|
|
These types are required. Others may be declared by the compiler.
|
|
|
|
|
|
II.18.1.3 Fastest Minimum-Width *crv-libSdHTFast*
|
|
-------------------------------
|
|
These integer types allow the fastest access while having at least N bits.
|
|
The general form is:
|
|
int_fastN_t (fast signed with at least N bits width)
|
|
uint_fastN_t (fast unsigned with at least N bits width)
|
|
|
|
Common types are:
|
|
$int_fast8_t$ $uint_fast8_t$ *crv-int_fast8_t*
|
|
*crv-uint_fast8_t*
|
|
$int_fast16_t$ $uint_fast16_t$ *crv-int_fast16_t*
|
|
*crv-uint_fast16_t*
|
|
$int_fast32_t$ $uint_fast32_t$ *crv-int_fast32_t*
|
|
*crv-uint_fast32_t*
|
|
$int_fast64_t$ $uint_fast64_t$ *crv-int_fast64_t*
|
|
*crv-uint_fast64_t*
|
|
|
|
These types are required. Others may be declared by the compiler.
|
|
|
|
|
|
II.18.1.4 Greatest-Width *crv-libSdHTGreat*
|
|
------------------------
|
|
These integer types have the widest range possible on the platform on which
|
|
they are being used.
|
|
$intmax_t$ (signed) *crv-intmax_t*
|
|
$uintmax_t$ (unsigned) *crv-uintmax_t*
|
|
These types are required.
|
|
|
|
|
|
II.18.1.5 Hold Pointer *crv-libSdHTPtr*
|
|
----------------------
|
|
These integer types are wide enough to store a pointer of type$void$.
|
|
$intptr_t$ (signed) *crv-intptr_t*
|
|
$uintptr_t$ (unsigned) *crv-uintptr_t*
|
|
|
|
These types are optional.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.18.2 Limits *crv-libSdHTLim*
|
|
*crv-__STDC_LIMIT_MACROS*
|
|
The following macros specify the minimum and maximum of the types declared
|
|
in$<stdint.h>$. They are defined only if$__STDC_LIMIT_MACROS$is defined before
|
|
including$<stdint.h>$.
|
|
|
|
II.18.2.1 Exact-Width *crv-libSdHLExact*
|
|
---------------------
|
|
Signed integer minimum:
|
|
INTN_MIN, N is the number of bits
|
|
Value: -2^(N-1)
|
|
Common macros:
|
|
$INT8_MIN$ *crv-INT8_MIN*
|
|
$INT16_MIN$ *crv-INT16_MIN*
|
|
$INT32_MIN$ *crv-INT32_MIN*
|
|
$INT64_MIN$ *crv-INT64_MIN*
|
|
|
|
Signed integer maximum:
|
|
INTN_MAX, N is the number of bits
|
|
Value: 2^(N-1) - 1
|
|
Common macros:
|
|
$INT8_MAX$ *crv-INT8_MAX*
|
|
$INT16_MAX$ *crv-INT16_MAX*
|
|
$INT32_MAX$ *crv-INT32_MAX*
|
|
$INT64_MAX$ *crv-INT64_MAX*
|
|
|
|
Unsigned integer minimum:
|
|
is always 0
|
|
|
|
Unsigned integer maximum:
|
|
UINTN_MAX, N is the number of bits
|
|
Value: 2^N - 1
|
|
Common macros:
|
|
$UINT8_MAX$ *crv-UINT8_MAX*
|
|
$UINT16_MAX$ *crv-UINT16_MAX*
|
|
$UINT32_MAX$ *crv-UINT32_MAX*
|
|
$UINT64_MAX$ *crv-UINT64_MAX*
|
|
|
|
|
|
|
|
II.18.2.2 Minimum-Width *crv-libSdHLMin*
|
|
-----------------------
|
|
Signed integer minimum:
|
|
INT_LEASTN_MIN, N is the number of bits
|
|
Value: <= -2^(N-1)
|
|
Common macros:
|
|
$INT_LEAST8_MIN$ *crv-INT_LEAST8_MIN*
|
|
$INT_LEAST16_MIN$ *crv-INT_LEAST16_MIN*
|
|
$INT_LEAST32_MIN$ *crv-INT_LEAST32_MIN*
|
|
$INT_LEAST64_MIN$ *crv-INT_LEAST64_MIN*
|
|
|
|
Signed integer maximum:
|
|
INT_LEASTN_MAX, N is the number of bits
|
|
Value: >= 2^(N-1) - 1
|
|
Common macros:
|
|
$INT_LEAST8_MAX$ *crv-INT_LEAST8_MAX*
|
|
$INT_LEAST16_MAX$ *crv-INT_LEAST16_MAX*
|
|
$INT_LEAST32_MAX$ *crv-INT_LEAST32_MAX*
|
|
$INT_LEAST64_MAX$ *crv-INT_LEAST64_MAX*
|
|
|
|
Unsigned integer minimum:
|
|
is always 0
|
|
|
|
Unsigned integer maximum:
|
|
UINT_LEASTN_MAX, N is the number of bits
|
|
Value: >= 2^N - 1
|
|
Common macros:
|
|
$UINT_LEAST8_MAX$ *crv-UINT_LEAST8_MAX*
|
|
$UINT_LEAST16_MAX$ *crv-UINT_LEAST16_MAX*
|
|
$UINT_LEAST32_MAX$ *crv-UINT_LEAST32_MAX*
|
|
$UINT_LEAST64_MAX$ *crv-UINT_LEAST64_MAX*
|
|
|
|
|
|
|
|
II.18.2.3 Fastest Minimum-Width *crv-libSdHLFast*
|
|
-------------------------------
|
|
Signed integer minimum:
|
|
INT_FASTN_MIN, N is the number of bits
|
|
Value: <= -2^(N-1)
|
|
Common macros:
|
|
$INT_FAST8_MIN$ *crv-INT_FAST8_MIN*
|
|
$INT_FAST16_MIN$ *crv-INT_FAST16_MIN*
|
|
$INT_FAST32_MIN$ *crv-INT_FAST32_MIN*
|
|
$INT_FAST64_MIN$ *crv-INT_FAST64_MIN*
|
|
|
|
Signed integer maximum:
|
|
INT_FASTN_MAX, N is the number of bits
|
|
Value: >= 2^(N-1) - 1
|
|
Common macros:
|
|
$INT_FAST8_MAX$ *crv-INT_FAST8_MAX*
|
|
$INT_FAST16_MAX$ *crv-INT_FAST16_MAX*
|
|
$INT_FAST32_MAX$ *crv-INT_FAST32_MAX*
|
|
$INT_FAST64_MAX$ *crv-INT_FAST64_MAX*
|
|
|
|
Unsigned integer minimum:
|
|
is always 0
|
|
|
|
Unsigned integer maximum:
|
|
UINT_FASTN_MAX, N is the number of bits
|
|
Value: >= 2^N - 1
|
|
Common macros:
|
|
$UINT_FAST8_MAX$ *crv-UINT_FAST8_MAX*
|
|
$UINT_FAST16_MAX$ *crv-UINT_FAST16_MAX*
|
|
$UINT_FAST32_MAX$ *crv-UINT_FAST32_MAX*
|
|
$UINT_FAST64_MAX$ *crv-UINT_FAST64_MAX*
|
|
|
|
|
|
|
|
II.18.2.4 Greatest-Width *crv-libSdHLGreat*
|
|
------------------------
|
|
Minimum value of greatest-width signed integer type:
|
|
$ INTMAX_MIN$ <= -(2^63) *crv-INTMAX_MIN*
|
|
|
|
Maximum value of greatest-width signed integer type:
|
|
$ INTMAX_MAX$ >= 2^63 - 1 *crv-INTMAX_MAX*
|
|
|
|
Minimum value of greatest-width unsigned integer type:
|
|
0
|
|
Maximum value of greatest-width unsigned integer type:
|
|
$ UINTMAX_MAX$ >= 2^64 - 1 *crv-UINTMAX_MAX*
|
|
|
|
|
|
|
|
II.18.2.5 Hold Pointer *crv-libSdHLPtr*
|
|
----------------------
|
|
Minimum value of pointer holding signed integer type:
|
|
$INTPTR_MIN$ <= -(2^15) *crv-INTPTR_MIN*
|
|
|
|
Maximum value of pointer holding signed integer type:
|
|
$INTPTR_MAX$ >= 2^15 - 1 *crv-INTPTR_MAX*
|
|
|
|
Minimum value of pointer holding unsigned integer type:
|
|
0
|
|
|
|
Maximum value of pointer holding unsigned integer type:
|
|
$UINTPTR_MAX$ >= 2^16 - 1 *crv-UINTPTR_MAX*
|
|
|
|
|
|
|
|
II.18.2.6 Others *crv-libSdHLOther*
|
|
----------------
|
|
Limits of$ptrdiff_t$:
|
|
$PTRDIFF_MIN$ *crv-PTRDIFF_MIN*
|
|
$PTRDIFF_MAX$ *crv-PTRDIFF_MAX*
|
|
|
|
Limits of$sig_atomic_t$:
|
|
$SIG_ATOMIC_MIN$ *crv-SIG_ATOMIC_MIN*
|
|
$SIG_ATOMIC_MAX$ *crv-SIG_ATOMIC_MAX*
|
|
|
|
Limits of$size_t$:
|
|
$SIZE_MAX$ *crv-SIZE_MAX*
|
|
|
|
Limits of$wchar_t$:
|
|
$WCHAR_MIN$ *crv-WCHAR_MIN*
|
|
$WCHAR_MAX$ *crv-WCHAR_MAX*
|
|
Also defined in$<wctype.h>$, see |crv-libWCHAR_MIN2|, |crv-libWCHAR_MAX2|.
|
|
|
|
Limits of$wint_t$:
|
|
$WINT_MIN$ *crv-WINT_MIN*
|
|
$WINT_MAX$ *crv-WINT_MAX*
|
|
|
|
|
|
|
|
-----------------------------------------------------------------------------
|
|
II.18.3 Macros *crv-libSdHMac*
|
|
|
|
|
|
INTMAX_C() Macro *crv-INTMAX_C*
|
|
----------------
|
|
Synopsis~
|
|
$#include <stdint.h>$
|
|
$INTMAX_C(val);$
|
|
|
|
Description~
|
|
expands to an integer constant value$val$of type$intmax_t$
|
|
|
|
|
|
UINTMAX_C() Macro *crv-UINTMAX_C*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdint.h>$
|
|
$UINTMAX_C(val);$
|
|
|
|
Description~
|
|
expands to an integer constant value$val$of type$uintmax_t$
|
|
|
|
|
|
*crv-INT8_C* *crv-INT16_C*
|
|
INTN_C() Macro *crv-INT32_C* *crv-INT64_C*
|
|
--------------
|
|
Synopsis~
|
|
$#include <stdint.h>$
|
|
$INT8_C(val);$
|
|
$INT16_C(val);$
|
|
$INT32_C(val);$
|
|
$INT64_C(val);$
|
|
|
|
Description~
|
|
expands to an integer constant value$val$of type$int_leastN_t$(N number of
|
|
bits)
|
|
|
|
|
|
*crv-UINT8_C* *crv-UINT16_C*
|
|
UINTN_C() Macro *crv-UINT32_C* *crv-UINT64_C*
|
|
---------------
|
|
Synopsis~
|
|
$#include <stdint.h>$
|
|
$UINT8_C(val);$
|
|
$UINT16_C(val);$
|
|
$UINT32_C(val);$
|
|
$UINT64_C(val);$
|
|
|
|
Description~
|
|
expands to an integer constant value$val$of type$uint_leastN_t$(N number of
|
|
bits)
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
II.19 <stdio.h> Input/Output *crv-libStdioH*
|
|
|
|
This header file declares types, macros and functions to perform input/output
|
|
operations.
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.19.1 Types *crv-libSIOHType*
|
|
|
|
Quicklink:
|
|
$size_t$ Type |crv-size_t5|
|
|
$FILE$ Type |crv-FILE|
|
|
$fpos_t$ Type |crv-fpos_t|
|
|
|
|
|
|
size_t Type *crv-size_t5*
|
|
-----------
|
|
This is an unsigned integer type used to represent the sizes of objects.
|
|
Also declared in$<stddef.h>$, see |crv-size_t|.
|
|
Also declared in$<string.h>$, see |crv-size_t2|.
|
|
Also declared in$<stdlib.h>$, see |crv-size_t3|.
|
|
Also declared in$<time.h>$, see |crv-size_t4|.
|
|
Also declared in$<wchar.h>$, see |crv-size_t6|.
|
|
|
|
|
|
FILE Type *crv-FILE*
|
|
---------
|
|
This is the data type used to represent stream objects. A FILE object holds
|
|
all of the internal state information about the connection to the associated
|
|
file.
|
|
|
|
|
|
fpos_t Type *crv-fpos_t*
|
|
-----------
|
|
This is the type of an object that can encode information about the file
|
|
position of a stream.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.19.2 Macros *crv-libSIOHMac*
|
|
|
|
Quicklink:
|
|
$_IOFBF$ Macro |crv-_IOFBF|
|
|
$_IOLBF$ Macro |crv-_IOLBF|
|
|
$_IONBF$ Macro |crv-_IONBF|
|
|
$BUFSIZ$ Macro |crv-BUFSIZ|
|
|
$BUFSIZ$ Macro |crv-BUFSIZ|
|
|
$FOPEN_MAX$ Macro |crv-FOPEN_MAX|
|
|
$FILENAME_MAX$ Macro |crv-FILENAME_MAX|
|
|
$L_tmpnam$ Macro |crv-L_tmpnam|
|
|
$NULL$ Macro |crv-NULL5|
|
|
$SEEK_SET$ Macro |crv-SEEK_SET|
|
|
$SEEK_CUR$ Macro |crv-SEEK_CUR|
|
|
$SEEK_END$ Macro |crv-SEEK_END|
|
|
$stderr$ Macro |crv-stderr|
|
|
$stdin$ Macro |crv-stdin|
|
|
$stdout$ Macro |crv-stdout|
|
|
|
|
|
|
|
|
NULL Macro *crv-NULL5*
|
|
----------
|
|
Expands to an implementation-defined null pointer constant.
|
|
Also defined in$<stddef.h>$, see |crv-libNULL|.
|
|
Also defined in$<stdlib.h>$, see |crv-libNULL2|.
|
|
Also defined in$<string.h>$, see |crv-libNULL3|.
|
|
Also defined in$<time.h>$, see |crv-libNULL4|.
|
|
Also defined in$<wchar.h>$, see |crv-libNULL6|.
|
|
|
|
|
|
|
|
_IOFBF Macro *crv-_IOFBF*
|
|
_IOLBF Macro *crv-_IOLBF*
|
|
_IONBF Macro *crv-_IONBF*
|
|
------------
|
|
This macros expand to an constant integer expression that can be used as the
|
|
mode argument to the$setvbuf()$function.
|
|
|
|
$_IOFBF$ specifies that the stream should be fully buffered
|
|
$_IOLBF$ specifies that the stream should be line buffered
|
|
$_IONBF$ specifies that the stream should be unbuffered
|
|
|
|
|
|
|
|
BUFSIZ Macro *crv-BUFSIZ*
|
|
------------
|
|
The value of this macro is an integer constant expression that is good to use
|
|
for the size argument to$setvbuf()$. This value is guaranteed to be at least
|
|
256.
|
|
|
|
|
|
|
|
EOF Macro *crv-EOF*
|
|
---------
|
|
This is returned by a number of narrow stream functions to indicate an
|
|
end-of-file condition, or some other error situation.
|
|
|
|
|
|
|
|
FOPEN_MAX Macro *crv-FOPEN_MAX*
|
|
---------------
|
|
The value of this macro is an integer constant expression that represents the
|
|
minimum number of streams that the implementation guarantees can be open
|
|
simultaneously.
|
|
|
|
|
|
|
|
FILENAME_MAX Macro *crv-FILENAME_MAX*
|
|
------------------
|
|
The value of this macro is an integer constant expression that represents
|
|
the maximum length of a file name string.
|
|
|
|
|
|
|
|
L_tmpnam Macro *crv-L_tmpnam*
|
|
--------------
|
|
The value of this macro is an integer constant expression that represents the
|
|
minimum size of a string large enough to hold a file name generated by the
|
|
$tmpnam()$function.
|
|
|
|
|
|
|
|
|
|
SEEK_SET Macro *crv-SEEK_SET*
|
|
SEEK_CUR Macro *crv-SEEK_CUR*
|
|
SEEK_END Macro *crv-SEEK_END*
|
|
--------------
|
|
These are integer constants which are used as the whence argument to the
|
|
fseek() or fseeko() functions.
|
|
|
|
$SEEK_SET$ specifies that the offset provided is relative to the beginning
|
|
of the file
|
|
$SEEK_CUR$ specifies that the offset provided is relative to the current
|
|
file position
|
|
$SEEK_END$ specifies that the offset provided is relative to the end of the
|
|
file
|
|
|
|
|
|
TMP_MAX Macro *crv-TMP_MAX*
|
|
-------------
|
|
This is the maximum number of unique filenames that the function$tmpnam()$can
|
|
generate.
|
|
|
|
|
|
|
|
stderr Macro *crv-stderr*
|
|
stdin Macro *crv-stdin*
|
|
stdout Macro *crv-stdout*
|
|
------------
|
|
These macros expand to pointers to$FILE$types which correspond to the standard
|
|
error, standard input and standard output streams. These streams are text
|
|
streams.
|
|
|
|
The standard input stream is the normal source of input for the program.
|
|
The standard output stream is the normal source of output from the program.
|
|
The standard error stream is used for error messages and diagnostics issued
|
|
by the program.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.19.3 Streams and Files *crv-libSIOHStrmFile*
|
|
|
|
Streams provide a higher-level interface between program and input/output
|
|
device. There are two types of streams: text and binary streams.
|
|
|
|
Text and binary streams differ in several ways:
|
|
|
|
- The data read from a text stream is divided into lines which are
|
|
terminated by newline ('\n') characters, while a binary stream is simply a
|
|
long series of characters.
|
|
A text stream might on some systems fail to handle lines more than 254
|
|
characters long (including the terminating newline character).
|
|
|
|
- On some systems, text files can contain only printing characters,
|
|
horizontal tab characters, and newlines, and so text streams may not
|
|
support other characters. However, binary streams can handle any character
|
|
value.
|
|
|
|
- Space characters that are written immediately preceding a newline
|
|
character in a text stream may disappear when the file is read in again.
|
|
|
|
- More generally, there need not be a one-to-one mapping between characters
|
|
that are read from or written to a text stream, and the characters in the
|
|
actual file.
|
|
|
|
Binary streams transfers data without changing (1:1 copy).
|
|
|
|
On some systems text and binary streams use different file formats, the only
|
|
way to read or write "an ordinary file of text" that can work with other
|
|
text-oriented programs is through a text stream.
|
|
|
|
At startup of a program there are three text streams available: standard
|
|
input, standard output and standard error. See |crv-libstdout| for further
|
|
information.
|
|
|
|
|
|
Files are associated with streams. A file must be opened to be used. One of
|
|
the attributes of an open file is its file position that keeps track of where
|
|
in the file the next character is to be read or written.
|
|
The file position is normally set to the beginning of the file when it is
|
|
opened, and each time a character is read or written, the file position is
|
|
incremented, so access to the file is normally sequential.
|
|
|
|
Ordinary files permit read or write operations at any position within the
|
|
file. Some other kinds of files may also permit this. Files which do permit
|
|
this are sometimes referred to as random-access files. The file position
|
|
can be changed using the$fseek()$function on a stream.
|
|
|
|
Streams that are opened for append access are treated specially for output:
|
|
output to such files is always appended sequentially to the end of the
|
|
file, regardless of the file position. However, the file position is still
|
|
used to control where in the file reading is done.
|
|
|
|
Each opening of a file creates a separate file position. Thus, if a file is
|
|
opened twice - even in the same program - two streams with independent
|
|
file positions are generated.
|
|
|
|
|
|
An open file must be closed,$fclose()$can be used to do that. If$main()$
|
|
returns or$exit()$is called, all opened files are closed automatically.
|
|
Other path to program termination (e.g.$abort()$) do not need to close
|
|
files (dependes on compiler).
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.19.4 File Operations *crv-libSIOHFOp*
|
|
|
|
|
|
remove() Function *crv-remove*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int remove(const char *file_name);$
|
|
|
|
Return~
|
|
0: successful
|
|
nonzero: failed
|
|
|
|
Description~
|
|
Remove the file (unlink it) with name$*file$points to. Any subsequent attempt
|
|
to open it again will fail. If the file is currently open, then the result is
|
|
implementation-defined.
|
|
|
|
|
|
|
|
rename() Function *crv-rename*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int rename(const char *oldname, const char *newname);$
|
|
|
|
Return~
|
|
0: successful
|
|
else: failed
|
|
|
|
Description~
|
|
This function renames the file$oldname$to$newname$. The file formerly
|
|
accessible under the name$oldname$is afterwards accessible as$newname$instead.
|
|
If the new file exists before renaming, then the result is
|
|
implementation-defined.
|
|
|
|
|
|
|
|
tmpfile() Function *crv-tmpfile*
|
|
------------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$FILE *tmpfile(void);$
|
|
|
|
Return~
|
|
NULL: failed
|
|
else: pointer to stream of the created file
|
|
|
|
Description~
|
|
This function creates a temporary binary file for update mode, as if by
|
|
calling$fopen()$with mode "wb+". The file is deleted automatically when it is
|
|
closed or when the program terminates.
|
|
|
|
|
|
|
|
tmpnam() Function *crv-tmpnam*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$char *tmpnam(char *result);$
|
|
|
|
Return~
|
|
NULL: failed
|
|
else: pointer to name of file
|
|
|
|
Description~
|
|
This function constructs and returns a valid file name that does not refer to
|
|
any existing file. If the$result$argument is a null pointer, the return value
|
|
is a pointer to an internal static string, which might be modified by
|
|
subsequent calls. Otherwise, the$result$argument should be a pointer to an
|
|
array of at least$L_tmpnam$characters, and the result is written into that
|
|
array. In this case the value of the argument is returned.
|
|
Each call of$tmpnam()$generates a different name, up to$TMP_MAX$times.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.19.5 File Access *crv-libSIOHFAcc*
|
|
|
|
|
|
fclose() Function *crv-fclose*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int fclose(FILE *stream);$
|
|
|
|
Return~
|
|
0: success
|
|
EOF: failed
|
|
|
|
Description~
|
|
This function causes$stream$to be closed and the connection to the
|
|
corresponding file to be broken. Any buffered output is written and any
|
|
buffered input is discarded.
|
|
|
|
|
|
|
|
fflush() Function *crv-fflush*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int fflush(FILE *stream);$
|
|
|
|
Return~
|
|
0: success
|
|
EOF: failed
|
|
|
|
Description~
|
|
This function causes any buffered output on$stream$to be delivered to the
|
|
file. If$stream$is a null pointer, then$fflush()$causes buffered output on all
|
|
open output streams to be flushed.
|
|
|
|
|
|
|
|
fopen() Function *crv-fopen*
|
|
----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$FILE *fopen(const char *file_name, const char *opentype);$
|
|
|
|
Return~
|
|
NULL: failed
|
|
else: pointer to stream of opened file
|
|
|
|
Description~
|
|
This function opens a stream for I/O to the file$file_name$, and returns a
|
|
pointer to the stream.
|
|
The$opentype$argument is a string that controls how the file is opened and
|
|
specifies attributes of the resulting stream. It must begin with one of the
|
|
following sequences of characters, other may follow (implementation-defined):
|
|
|
|
Mode | Description
|
|
------------+--------------------------------------------------------------
|
|
$r$ | open text file for reading
|
|
$w$ | truncate to zero length or create text file for writing
|
|
$a$ | append; open or create text file for writing at end-of-file
|
|
$rb$ | open binary file for reading
|
|
$wb$ | truncate to zero length or create binary file for writing
|
|
$ab$ | append; open or create binary file for writing at end-of-file
|
|
$r+$ | open text file for reading and writing
|
|
$w+$ | truncate to zero length or create text file for reading and
|
|
| writing
|
|
$a+$ | append; open or create text file for reading and writing,
|
|
| writing at end-of-file
|
|
$r+b or rb+$| open binary file for reading and writing
|
|
$w+b or wb+$| truncate to zero length or create binary file for reading
|
|
| and writing
|
|
$a+b or ab+$| append; open or create binary file for reading and writing,
|
|
| writing at end-of-file
|
|
|
|
|
|
|
|
|
|
freopen() Function *crv-freopen*
|
|
------------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$FILE *freopen(const char *file_name, const char *opentype, FILE *stream);$
|
|
|
|
Return~
|
|
NULL: failed
|
|
else: pointer to stream of opened file
|
|
|
|
Description~
|
|
This function is like a combination of$fclose()$and$fopen()$. It first closes
|
|
the stream referred to by$stream$, ignoring any errors that are detected in
|
|
the process. Then the file named by$file_name$is opened with mode$opentype$as
|
|
for$fopen()$, and associated with the same stream object$stream$.
|
|
|
|
This is traditionally been used to connect a standard stream such as$stdin$
|
|
with a file.
|
|
|
|
|
|
|
|
setbuf() Function *crv-setbuf*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$void setbuf(FILE *stream, char *buf);$
|
|
|
|
Return~
|
|
none
|
|
|
|
Description~
|
|
If$buf$is a null pointer, the effect of this function is equivalent to calling
|
|
$setvbuf()$with a mode argument of$_IONBF$. Otherwise, it is equivalent to
|
|
calling$setvbuf()$with$buf$, and a mode of$_IOFBF$and a size argument of
|
|
$BUFSIZ$.
|
|
|
|
This function is provided for compatibility with old code; use$setvbuf()$in
|
|
all new programs.
|
|
|
|
|
|
|
|
setvbuf() Function *crv-setvbuf*
|
|
------------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int setvbuf(FILE *stream, char *buf, int mode, size_t size);$
|
|
|
|
Return~
|
|
0: success
|
|
nonzero: failed
|
|
|
|
Description~
|
|
This function is used to specify that the stream$stream$should have the
|
|
buffering mode$mode$, which can be:
|
|
|
|
$_IOFBF$ full buffering |crv-lib_IOFBF|
|
|
$_IOLBF$ line buffering |crv-lib_IOLBF|
|
|
$_IONBF$ unbuffered input/output |crv-lib_IONBF|
|
|
|
|
If a null pointer as the$buf$argument is specified, then$setvbuf()$allocates
|
|
a buffer itself. This buffer will be freed when closing the stream.
|
|
|
|
Otherwise,$buf$should be a character array that can hold at least$size$
|
|
characters. This space should not be freed as long as the stream remains open
|
|
and this array remains its buffer.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.19.6 Formatted Input/Output *crv-libSIOHIO*
|
|
|
|
|
|
II.19.6.1 Format Control *crv-libSIOHIOFormat*
|
|
------------------------
|
|
|
|
II.19.6.1.1 Output, printf() *crv-libSIOHIOFout*
|
|
-----------------------------
|
|
The family of printf() functions write output to a stream, under control of
|
|
the format string. The format specifies how subsequent arguments are converted
|
|
to output.
|
|
A format string for output has the following syntax:
|
|
$%[flags][width][.precision][modifier]type$
|
|
|
|
[flags] control convertion (optional)
|
|
[width] number of characters to output (optional)
|
|
[.precision] precision of number (optional)
|
|
[modifier] overrides size (type) of argument (optional)
|
|
[type] type of conversion (required)
|
|
|
|
|
|
[flag] control convertion (optional)
|
|
|
|
zero or more flags may be specified
|
|
|
|
flag | Description
|
|
-------+---------------------------------------------------------------------
|
|
$-$ | value is left-justified (default is right-justified)
|
|
$+$ | forces to show sign of value (+ or -)
|
|
| default is to show only - for negative values, overrules space
|
|
space | print " " in front of positive value, print - for negative value
|
|
$#$ | convert to alternative form:
|
|
| $o$ increase precision to force the first digit to be a zero
|
|
|
|
|
| $x$or$X$ nonzero result will have prefix "0x" or "0X"
|
|
|
|
|
| $a$,$A$,
|
|
| $e$,$E$,
|
|
| $f$,$F$,
|
|
| $g$or$G$ result will always have decimal point
|
|
|
|
|
| $g$or$G$ trailing zeros are not removed
|
|
|
|
|
$0$ | for $d, i, o, u, x, X, a, A, e, E, f, F, g, G$conversions leading
|
|
| zeros are used to pad to the field width instead of spaces
|
|
|
|
|
|
[width] number of characters to output (optional)
|
|
This is a decimal integer specifying the minimum field width. If the normal
|
|
conversion produces fewer characters than this, the field is padded with
|
|
spaces to the specified width. If the normal conversion produces more
|
|
characters than this, the field is not truncated. Normally, the output is
|
|
right-justified within the field.
|
|
A field width of$*$may be specified. This means that the next argument
|
|
in the argument list (before the actual value to be printed) is used as the
|
|
field width. The value must be an integer of type$int$. If the value is
|
|
negative, this means to set the$-$flag and to use the absolute value as
|
|
the field width.
|
|
|
|
[.precision] precision of number (optional)
|
|
The precision specifies the number of digits to be written for the numeric
|
|
conversions. If the precision is specified, it consists of a period ($.$)
|
|
followed optionally by a decimal integer (which defaults to zero if
|
|
omitted).
|
|
|
|
A precision of$*$may be specified. This means that the next argument
|
|
in the argument list (before the actual value to be printed) is used as the
|
|
precision. The value must be an integer of type$int$, and is ignored if it
|
|
is negative.
|
|
If$*$is specified for both the field width and precision, the field width
|
|
argument precedes the precision argument.
|
|
|
|
|
|
precision | Description
|
|
-----------+-----------------------------------------------------------------
|
|
(none) | default precision:
|
|
| 1 for$d, i, o, u, x, X$types. Precision gives the minimum number
|
|
| of digits to appear.
|
|
| 6 for$f, F, e, E$types. Precision gives the number of digits to
|
|
| appear after decimal point.
|
|
| For$g, G$types all digits are printed.
|
|
| For$s$type all characters of the string are printed, not
|
|
| including the terminating null character.
|
|
| For$a, A$and$FLT_RADIX$of 2: precision is sufficient for an
|
|
| exact representation of the value.
|
|
| For$a, A$and$FLT_RADIX$not equal to 2: precision is sufficient
|
|
| to distinguish values of type$double$.
|
|
|
|
|
$.$or$.0$ | For$d, i, o, u, x, X$types the default precision is used, unless
|
|
| the value is 0, then no characters are printed.
|
|
| For$f, F, e, E$types no decimal-point and no decimal-digits are
|
|
| printed..
|
|
| For$g, G$types precision is assumed to be 1.
|
|
| For$s$type nothing is printed.
|
|
| For$a, A$types no decimal-point and no decimal-digits appear.
|
|
|
|
|
$.N$ | For$d, i, o, u, x, X$types. At least N digits appear, if
|
|
| necessary output is expanded with leading zeros.
|
|
| For$f, F, e, E$types. N digits appear after decimal point.
|
|
| For$g, G$types N digits are printed.
|
|
| For$s$type a maximum of N characters of the string are printed,
|
|
| not including the terminating null character.
|
|
| For$a, A$types N specifies the number of digits after decimal
|
|
| point.
|
|
|
|
|
|
|
|
|
|
|
[modifier] overrides size (type) of argument (optional)
|
|
The modifier character is used to specify the data type of the corresponding
|
|
argument if it differs from the default type.
|
|
|
|
|
|
modifier | Description
|
|
----------+------------------------------------------------------------------
|
|
$hh$ | Specifies that the argument is a$signed char$or$unsigned char$,
|
|
| as appropriate. A$char$argument is converted to an$int$or
|
|
|$unsigned int$by the default argument promotions anyway, but this
|
|
| modifier says to convert it back to a$char$again.
|
|
|
|
|
$h$ | Specifies that the argument is a$short int$or$unsigned short int$
|
|
| as appropriate. A$short$argument is converted to an$int$or
|
|
|$unsigned int$by the default argument promotions anyway, but this
|
|
| modifier says to convert it back to a$short$again.
|
|
|
|
|
$l$ | Specifies that the argument is a$long int$or$unsigned long int$,
|
|
| as appropriate. Two l characters is like the L modifier, below
|
|
| If used with$%c$or$%s$the corresponding parameter is considered
|
|
| as a wide character or wide character string respectively.
|
|
|
|
|
$ll$ | Specifies that a following$d, i, o, u, x, X$applies to a
|
|
|$long long int$or$unsigned long long int$argument; or that a
|
|
|$n$applies to a pointer to$long long int$.
|
|
|
|
|
$L$ | Specifies that a following$a, A, e, E, f, F, g, G$conversion
|
|
| specifier applies to a$long double$argument.
|
|
|
|
|
$j$ | Specifies that a following$d, i, o, u, x, X$applies to$intmax_t$
|
|
| or$uintmax_t$, or that a following$n$applies to pointer to
|
|
|$intmax_t$.
|
|
|
|
|
$t$ | Specifies that a following$d, i, o, u, x, X$applies to a
|
|
|$ptrdiff_t$or the corresponding unsigned integer type argument;
|
|
| or that a$n$applies to a pointer to a$ptrdiff_t$argument.
|
|
|
|
|
$z$ | Specifies that the following$d, i, o, u, x, X$applies to a
|
|
|$size_t$or the corresponding singed integer type argument;
|
|
| or that a$n$applies to a pointer to a signed integer type
|
|
| corresponding to$size_t$argument.
|
|
|
|
|
|
[type] type of conversion (required)
|
|
|
|
The conversion specifier specifies the conversion to be applied.
|
|
|
|
type | Description
|
|
--------+------------------------------------------------------------------
|
|
$ d, i$ | type$signed int$, output decicmal, style [-]dddd
|
|
$o$ | type$unsigned int$, output octal, style: dddd
|
|
$u$ | type$unsigned int$, output decimal, style dddd
|
|
$x$ | type$unsigned int$, output hexadecimal, style dddd using a...f
|
|
$X$ | type$unsigned int$, output hexadecimal, style dddd using A...F
|
|
$f, F$ | type$double$, output decimal, style [-]ddd.ddd
|
|
$e$ | type$double$, output decimal, style [-]d.ddde+/-dd
|
|
$E$ | type$double$, output decimal, style [-]d.dddE+/-dd
|
|
$g$ | type$double$, printed as type$e$if exponent is less than -4
|
|
| or greater than or equal to the precision. Otherwise$f$is used.
|
|
$G$ | type$double$, printed as type$E$if exponent is less than -4
|
|
| or greater than or equal to the precision. Otherwise$F$is used.
|
|
$a$ | type$double$, style [-]0xh.hhhhp+/-d
|
|
| h: hexadecimal digit 0...9, a...f
|
|
| d: decimal digit
|
|
$A$ | type$double$, style [-]0Xh.hhhhP+/-d
|
|
| h: hexadecimal digit 0...9, A...F
|
|
| d: decimal digit
|
|
$c$ | no$l$modifier: type$char$, single character is printed
|
|
| with$l$modifier: type$wchar_t$, single character is printed
|
|
$s$ | no$l$modifier: pointer to array of$char$, string is printed
|
|
| with$l$modifier: pointer to array of$char$, string is printed
|
|
$p$ | type pointer to$void$, value of pointer is printed in an
|
|
| implementation-defined way
|
|
$n$ | argument is a pointer to$signed int$into which is written the
|
|
| number of characters written to the output stream so far
|
|
$%$ | a % is printed
|
|
|
|
|
|
|
|
|
|
II.19.6.1.2 Input, scanf() *crv-libSIOHIOFin*
|
|
---------------------------
|
|
The family of scanf() functions read input from a stream, under control of
|
|
the format string. The format specifies how the input is to be stored in
|
|
the appropriate variable(s).
|
|
A white-space character may match with any whitespace character (space, tab,
|
|
carriage return, new line, vertical tab, or formfeed).
|
|
Other characters in the format string that are not part of conversion
|
|
specifications must match characters in the input stream exactly; if this is
|
|
not the case, a matching failure occurs and scanning is stopped.
|
|
|
|
A format string for input has the following syntax:
|
|
$%[*][width][modifier]type$
|
|
|
|
[*] assignment suppressor (optional)
|
|
[width] maximum number of characters to be read (optional)
|
|
[modifier] overrides size (type) of argument (optional)
|
|
[type] type of conversion (required)
|
|
|
|
|
|
[*] assignment suppressor (optional)
|
|
The assignment suppressor$*$says to ignore the text read for this
|
|
specification. When scanf() finds a conversion specification that uses this
|
|
flag, it reads input as directed by the rest of the conversion
|
|
specification, but it discards this input, does not use a pointer argument,
|
|
and does not increment the count of successful assignments.
|
|
|
|
|
|
[width] maximum number of characters to be read (optional)
|
|
This is a decimal integer that specifies the maximum field width. Reading of
|
|
characters from the input stream stops either when this maximum is reached
|
|
or when a non-matching character is found, whichever happens first. Then
|
|
what was read so far is converted and stored in the variable.
|
|
|
|
Most conversions discard initial whitespace characters (those that don't are
|
|
explicitly documented), and these discarded characters don't count towards
|
|
the maximum field width. String input conversions store a null character
|
|
to mark the end of the input; the maximum field width does not include this
|
|
terminator.
|
|
|
|
|
|
[modifier] overrides size (type) of argument (optional)
|
|
The modifier character is used to specify the data type of the corresponding
|
|
argument if it differs from the default type.
|
|
|
|
|
|
modifier | Description
|
|
----------+------------------------------------------------------------------
|
|
$hh$ | Specifies that a following$d, i, o, u, x, X, n$conversion applies
|
|
| to an argument with type pointer to$signed char$or
|
|
| $unsigned char$
|
|
|
|
|
$h$ | Specifies that a following$d, i, o, u, x, X, n$conversion applies
|
|
| to an argument with type pointer to$short int$or$unsigned short$.
|
|
|
|
|
$l$ | Specifies that a following$d, i, o, u, x, X, n$conversion applies
|
|
| to an argument with type pointer to$long int$or
|
|
|$unsigned long int$; or that a following$a, A, e, E, f, F, g, G$
|
|
| converstion applies to an argument with type pointer to$double$;
|
|
| or that a following$c, s, [$conversion applies to an argument
|
|
| with type pointer to$wchar_t$.
|
|
|
|
|
$ll$ | Specifies that a following$d, i, o, u, x, X, n$argument applies
|
|
| to an argument with type pointer to$long long int$or
|
|
| $unsigned long long int$.
|
|
|
|
|
$L$ | Specifies that a following$a, A, e, E, f, F, g, G$conversion
|
|
| applies to an argument of type pointer to$long double$argument.
|
|
|
|
|
$j$ | Specifies that a following$d, i, o, u, x, X, n$conversion applies
|
|
| to an argument with type pointer to$intmax_t$or$uintmax_t$.
|
|
|
|
|
$t$ | Specifies that a following$d, i, o, u, x, X, n$conversion applies
|
|
| to an argument of type pointer to$ptrdiff_t$or the corresponding
|
|
| unsigned integer type.
|
|
|
|
|
$z$ | Specifies that a following$d, i, o, u, x, X, n$conversion applies
|
|
| to an argument of type pointer to$size_t$or the corresponding
|
|
| singed integer type.
|
|
|
|
|
|
|
|
[type] type of conversion (required)
|
|
|
|
The conversion specifier specifies the conversion to be applied.
|
|
|
|
type | Description
|
|
--------+--------------------------------------------------------------------
|
|
$ d $ | type$signed int$, matches an optionally signed integer written
|
|
| in decimal
|
|
|
|
|
$i$ | type$signed int$, matches an optionally signed integer in any of
|
|
| the formats that the C language defines for specifying an integer
|
|
| constant. The based used depends on the first two characters:
|
|
| - first character 1...9, then base 10 (decimal)
|
|
| - first digit 0, followed by 0..7, then base 8 (octal)
|
|
| - first digit 0, followed by x or X, then base 16 (hexadecimal)
|
|
|
|
|
$o$ | type$unsigned int$, matches octal numbers (digits 0...7 only)
|
|
|
|
|
$u$ | type$unsigned int$, matches decimal numbers (digits 0...9 only)
|
|
|
|
|
$x, X$ | type$unsigned int$, matches hexadecimal numbers (characters 0...9,
|
|
| a-f, A-F only). The number may be prefixed with 0x or 0X.
|
|
|
|
|
$f, F$ | matches an optionally signed floating point number
|
|
$e, E$ |
|
|
$g, G$ |
|
|
$a, A$ |
|
|
|
|
|
$c$ | Matches a string of one or more characters; the number of
|
|
| characters read is controlled by the maximum field width given for
|
|
| the conversion. No null character is appended.
|
|
| no$l$modifier: argument is of type pointer to array of$char$
|
|
| with$l$modifier: argument is of type pointer to array of$wchar_t$
|
|
|
|
|
$s$ | Matches a sequence of non-white-space characters. A null
|
|
| character is appended.
|
|
| no$l$modifier: argument is of type pointer to array of$char$
|
|
| with$l$modifier: argument is of type pointer to array of$wchar_t$
|
|
|
|
|
$ [...]$| Matches a nonempty sequence of characters from a set of expected
|
|
| characters enclosed in brackets [...] (scanset). If the first
|
|
| character is a circumflex (^), the selection is inverted, in that
|
|
| case the scanset contains all characters that do NOT appear in the
|
|
| list between [^ and ].
|
|
| A null character is appended.
|
|
| no$l$modifier: argument is of type pointer to array of$char$
|
|
| with$l$modifier: argument is of type pointer to array of$wchar_t$
|
|
|
|
|
$p$ | Matches a pointer value in the same implementation-defined format
|
|
| used by the$%p$output conversion for printf().
|
|
|
|
|
$n$ | No input is consumed. It records the number of characters read so
|
|
| far by this call. Argument is a pointer to$signed int$into which is
|
|
| written the number of characters read from the input stream so far.
|
|
|
|
|
$%$ | Matches a single %. No conversion or assignment occurs.
|
|
|
|
|
|
|
|
|
|
II.19.6.2 Functions *crv-libSIOHIOFunc*
|
|
-------------------
|
|
|
|
Quicklink
|
|
$printf()$ Func |crv-printf|
|
|
$fprintf()$ Func |crv-fprintf|
|
|
$sprintf()$ Func |crv-sprintf|
|
|
$snprintf()$ Func |crv-snprintf|
|
|
$vfprintf()$ Func |crv-vfprintf|
|
|
$vprintf()$ Func |crv-vprintf|
|
|
$vsprintf()$ Func |crv-vsprintf|
|
|
$vsnprintf()$Func |crv-vsnprintf|
|
|
|
|
$fscanf()$ Func |crv-fscanf|
|
|
$scanf()$ Func |crv-scanf|
|
|
$sscanf()$ Func |crv-sscanf|
|
|
$vfscanf()$ Func |crv-vfscanf|
|
|
$vscanf()$ Func |crv-vscanf|
|
|
$vsscanf()$ Func |crv-vsscanf|
|
|
|
|
|
|
|
|
printf() Function *crv-printf*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int printf(const char *format, ...);$
|
|
|
|
Return~
|
|
<0: output error occurred
|
|
>= 0: number of transmitted characters
|
|
|
|
Description~
|
|
This function prints the optional arguments under the control of the format
|
|
string$format$to the standard output stream$stdout$.
|
|
For format string see |crv-libSIOHIOFout|.
|
|
|
|
|
|
|
|
fprintf() Function *crv-fprintf*
|
|
------------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int fprintf(FILE *stream, const char *format, ...);$
|
|
|
|
Return~
|
|
<0: output error occurred
|
|
>= 0: number of transmitted characters
|
|
|
|
Description~
|
|
This function is equivalent to$printf()$, except that the output is written
|
|
to the stream$stream$instead of$stdout$.
|
|
|
|
|
|
|
|
sprintf() Function *crv-sprintf*
|
|
------------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int sprintf(char *s, const char *format, ...);$
|
|
|
|
Return~
|
|
<0: error occurred
|
|
number of characters stored in array, not including terminating null character
|
|
|
|
Description~
|
|
This is like$printf()$, except that the output is stored in the character
|
|
array$s$instead of written to a stream. A null character is written to mark
|
|
the end of the string.
|
|
|
|
|
|
|
|
snprintf() Function *crv-snprintf*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int snprintf(char *s, size_t size, const char *format, ...);$
|
|
|
|
Return~
|
|
<0: error occurred
|
|
The return value is the number of characters which would be generated for the
|
|
given input, excluding the trailing null. If this value is greater or equal
|
|
to$size$, not all characters from the result have been stored in$s$.
|
|
|
|
Description~
|
|
This function is similar to$sprintf()$, except that the$size$argument
|
|
specifies the maximum number of characters to produce. The trailing null
|
|
character is counted towards this limit.
|
|
|
|
|
|
|
|
vprintf() Function *crv-vprintf*
|
|
------------------
|
|
Synopsis~
|
|
$#include <stdarg.h>$
|
|
$#include <stdio.h>$
|
|
$int vprintf(const char *format, va_list ap);$
|
|
|
|
Return~
|
|
<0: output error occurred
|
|
>= 0: number of transmitted characters
|
|
|
|
Description~
|
|
This function is similar to$printf()$except that, instead of taking a variable
|
|
number of arguments directly, it takes an argument list pointer$ap$, which
|
|
must have been initialized by the$va_start()$macro. The$vprintf()$function
|
|
does not invoke the$va_end()$macro.
|
|
|
|
|
|
|
|
vfprintf() Function *crv-vfprintf*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <stdarg.h>$
|
|
$#include <stdio.h>$
|
|
$int vfprintf(FILE *stream, const char *format, va_list ap);$
|
|
|
|
Return~
|
|
<0: output error occurred
|
|
>= 0: number of transmitted characters
|
|
|
|
Description~
|
|
This function is similar to$fprintf()$except that, instead of taking a
|
|
variable number of arguments directly, it takes an argument list pointer$ap$,
|
|
which must have been initialized by the$va_start()$macro. The$vfprintf()$
|
|
function does not invoke the$va_end()$macro.
|
|
|
|
|
|
|
|
vsprintf() Function *crv-vsprintf*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <stdarg.h>$
|
|
$#include <stdio.h>$
|
|
$int vsnprintf(char *s, size_t size, const char *format, va_list ap);$
|
|
|
|
Return~
|
|
<0: error occurred
|
|
number of characters stored in array, not including terminating null character
|
|
|
|
Description~
|
|
This function is similar to$sprintf()$except that, instead of taking a
|
|
variable number of arguments directly, it takes an argument list pointer$ap$,
|
|
which must have been initialized by the$va_start()$macro. The$vsprintf()$
|
|
function does not invoke the$va_end()$macro.
|
|
|
|
|
|
|
|
vsnprintf() Function *crv-vsnprintf*
|
|
--------------------
|
|
Synopsis~
|
|
$#include <stdarg.h>$
|
|
$#include <stdio.h>$
|
|
$int vsnprintf(char *s, size_t size, const char *format, va_list ap);$
|
|
|
|
Return~
|
|
<0: error occurred
|
|
The return value is the number of characters which would be generated for the
|
|
given input, excluding the trailing null. If this value is greater or equal
|
|
to$size$, not all characters from the result have been stored in$s$.
|
|
|
|
Description~
|
|
This function is similar to$snprintf()$except that, instead of taking a
|
|
variable number of arguments directly, it takes an argument list pointer$ap$,
|
|
which must have been initialized by the$va_start()$macro. The$vsnprintf()$
|
|
function does not invoke the$va_end()$macro.
|
|
|
|
|
|
|
|
scanf() Function *crv-scanf*
|
|
----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int scanf(const char *format, ...);$
|
|
|
|
Return~
|
|
The return value is the number of successful assignments. If there is a match
|
|
error, this number can be fewer than provided. If an input error occurs
|
|
before any matches are performed, then$EOF$is returned.
|
|
|
|
Description~
|
|
This function reads formatted input from the standard input stream$stdin$under
|
|
the control of the format string$format$. The optional arguments are pointers
|
|
to the places which receive the resulting values.
|
|
For format string see |crv-libSIOHIOFin|.
|
|
|
|
|
|
|
|
fscanf() Function *crv-fscanf*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int fscanf(FILE *stream, const char *format, ...);$
|
|
|
|
Return~
|
|
|
|
Description~
|
|
This function is equivalent to$scanf()$, except that the input is read from
|
|
the stream$stream$instead of$stdin$.
|
|
|
|
|
|
|
|
sscanf() Function *crv-sscanf*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int sscanf(const char *s, const char *format, ...);$
|
|
|
|
Return~
|
|
|
|
Description~
|
|
This function is similar to$scanf()$, except that the characters are taken
|
|
from the null-terminated string$s$instead of from$stdin$. Reaching the end of
|
|
the string is treated as an end-of-file condition.
|
|
|
|
|
|
vscanf() Function *crv-vscanf*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int vscanf(const char *format, va_list ap);$
|
|
|
|
Return~
|
|
|
|
Description~
|
|
This function is similar to$scanf()$except that, instead of taking a
|
|
variable number of arguments directly, it takes an argument list pointer$ap$,
|
|
which must have been initialized by the$va_start()$macro. The$vscanf()$
|
|
function does not invoke the$va_end()$macro.
|
|
|
|
|
|
|
|
vfscanf() Function *crv-vfscanf*
|
|
------------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int vfscanf(FILE *stream, const char *format, va_list ap);$
|
|
|
|
Return~
|
|
|
|
Description~
|
|
This function is similar to$fscanf()$except that, instead of taking a
|
|
variable number of arguments directly, it takes an argument list pointer$ap$,
|
|
which must have been initialized by the$va_start()$macro. The$vfscanf()$
|
|
function does not invoke the$va_end()$macro.
|
|
|
|
|
|
|
|
vsscanf() Function *crv-vsscanf*
|
|
------------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int vsscanf(const char *s, const char *format, va_list ap);$
|
|
|
|
Return~
|
|
|
|
Description~
|
|
This function is similar to$sscanf()$except that, instead of taking a
|
|
variable number of arguments directly, it takes an argument list pointer$ap$,
|
|
which must have been initialized by the$va_start()$macro. The$vsscanf()$
|
|
function does not invoke the$va_end()$macro.
|
|
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.19.7 Character Input/Output *crv-libSIOHCIO*
|
|
|
|
This section describes functions for performing character-oriented input and
|
|
output.
|
|
|
|
Quicklink:
|
|
$fgetc()$ Func |crv-fgetc|
|
|
$fgets()$ Func |crv-fgets|
|
|
$fputc()$ Func |crv-fputc|
|
|
$fputs()$ Func |crv-fputs|
|
|
$getc()$ Macro |crv-getc|
|
|
$getchar()$ Func |crv-getchar|
|
|
$gets()$ Func |crv-gets|
|
|
$putc()$ Macro |crv-putc|
|
|
$putchar()$ Func |crv-putchar|
|
|
$puts()$ Func |crv-puts|
|
|
$ungetc()$ Func |crv-ungetc|
|
|
|
|
|
|
|
|
fgetc() Function *crv-fgetc*
|
|
----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int fgetc(FILE *stream);$
|
|
|
|
Return~
|
|
character read from stream
|
|
error or end-of-file:$EOF$
|
|
|
|
Description~
|
|
This function reads the next character as an$unsigned char$from the stream
|
|
$stream$and returns its value, converted to an$int$. If an end-of-file
|
|
condition or read error occurs,$EOF$is returned instead.
|
|
|
|
|
|
|
|
fgets() Function *crv-fgets*
|
|
----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$char *fgets(char *s, int count, FILE *stream);$
|
|
|
|
Return~
|
|
If the system is already at end of file when fgets() is called, then the
|
|
contents of the array$s$are unchanged and a null pointer is returned.
|
|
A null pointer is also returned if a read error occurs. Otherwise, the
|
|
return value is the pointer$s$.
|
|
|
|
Description~
|
|
This function reads characters from the stream$stream$up to and including a
|
|
newline character and stores them in the string$s$, adding a null character
|
|
to mark the end of the string.$count$characters must be supplied worth of
|
|
space in$s$, but the number of characters read is at most$count$- 1.
|
|
The extra character space is used to hold the null character at the end of
|
|
the string.
|
|
|
|
|
|
|
|
getc() Macro *crv-getc*
|
|
------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int getc(FILE *stream);$
|
|
|
|
Return~
|
|
character read from stream
|
|
error or end-of-file:$EOF$
|
|
|
|
Description~
|
|
This is just like$fgetc()$, except that it is permissible (and typical) for
|
|
it to be implemented as a macro that evaluates the stream argument more
|
|
than once.$getc()$is often highly optimized, so it is usually the best
|
|
function to use to read a single character.
|
|
|
|
|
|
|
|
getchar() Function *crv-getchar*
|
|
------------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int getchar(void);$
|
|
|
|
Return~
|
|
character read from stream
|
|
error or end-of-file:$EOF$
|
|
|
|
Description~
|
|
This function is equivalent to$getc()$with$stdin$as the value of the stream
|
|
argument.
|
|
|
|
|
|
|
|
gets() Function *crv-gets*
|
|
---------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$char *gets(char *s);$
|
|
|
|
Return~
|
|
If$gets()$encounters a read error or end-of-file, it returns a null pointer;
|
|
otherwise it returns$s$.
|
|
|
|
Description~
|
|
This function reads characters from the stream$stdin$up to the next newline
|
|
character, and stores them in the string$s$. The newline character is
|
|
discarded (note that this differs from the behavior of$fgets()$, which copies
|
|
the newline character into the string).
|
|
|
|
|
|
|
|
ungetc() Function *crv-ungetc*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int ungetc(int c, FILE *stream);$
|
|
|
|
Return~
|
|
$c$pushed back after conversion or$EOF$if the operation fails
|
|
|
|
Description~
|
|
This function pushes back the character$c$onto the input stream$stream$. So
|
|
the next input from$stream$will read$c$before anything else.
|
|
|
|
If$c$is$EOF$,$ungetc()$does nothing and just returns$EOF$. This allows to
|
|
call$ungetc()$with the return value of$getc()$without needing to check for an
|
|
error from$getc()$.
|
|
|
|
The character that is pushed back doesn't have to be the same as the last
|
|
character that was actually read from the stream. In fact, it isn't necessary
|
|
to actually read any characters from the stream before unreading them with
|
|
$ungetc()$. But that is a strange way to write a program; usually$ungetc()$
|
|
is used only to unread a character that was just read from the same stream.
|
|
|
|
Pushing back characters doesn't alter the file; only the internal buffering
|
|
for the stream is affected. If a file positioning function (such as$fseek()$,
|
|
$fseeko()$ or$rewind()$) is called, any pending pushed-back characters are
|
|
discarded.
|
|
|
|
Unreading a character on a stream that is at end of file clears the
|
|
end-of-file indicator for the stream, because it makes the character of
|
|
input available. After reading that character, trying to read again will
|
|
encounter end of file.
|
|
|
|
|
|
|
|
fputc() Function *crv-fputc*
|
|
----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int fputc(int c, FILE *stream);$
|
|
|
|
Return~
|
|
$EOF$is returned if a write error occurs; otherwise the character$c$is
|
|
returned
|
|
|
|
Description~
|
|
This function converts the character$c$to type$unsigned char$, and writes it
|
|
to the stream$stream$.
|
|
|
|
|
|
|
|
fputs() Function *crv-fputs*
|
|
----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int fputs(const char *s, FILE *stream);$
|
|
|
|
Return~
|
|
This function returns$EOF$if a write error occurs, and otherwise a
|
|
non-negative value.
|
|
|
|
Description~
|
|
This function writes the string$s$to the stream$stream$. The terminating
|
|
null character is not written. This function does not add a newline character,
|
|
either. It outputs only the characters in the string.
|
|
|
|
|
|
|
|
putc() Macro *crv-putc*
|
|
------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int putc(int c, FILE *stream);$
|
|
|
|
Return~
|
|
This function returns$EOF$if a write error occurs, and otherwise the
|
|
character written.
|
|
|
|
Description~
|
|
This is just like$fputc()$, except that most systems implement it as a
|
|
macro, making it faster. One consequence is that it may evaluate the stream
|
|
argument more than once, which is an exception to the general rule for
|
|
macros.$putc()$is usually the best function to use for writing a single
|
|
character.
|
|
|
|
|
|
|
|
putchar() Function *crv-putchar*
|
|
------------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int putchar(int c);$
|
|
|
|
Return~
|
|
This function returns$EOF$if a write error occurs, and otherwise the
|
|
character written.
|
|
|
|
Description~
|
|
This function is equivalent to$putc()$with$stdout$as the value of the stream
|
|
argument.
|
|
|
|
|
|
|
|
puts() Function *crv-puts*
|
|
---------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int puts(const char *s);$
|
|
|
|
Return~
|
|
This function returns$EOF$if a write error occurs, and otherwise a
|
|
non-negative value.
|
|
|
|
Description~
|
|
This function writes the string$s$to the stream$stdout$followed by a newline.
|
|
The terminating null character of the string is not written. (Note that
|
|
$fputs()$does not write a newline as this function does.)
|
|
|
|
$puts()$is the most convenient function for printing simple messages.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.19.8 Direct Input/Output *crv-libSIOHDIO*
|
|
|
|
This section describes how to do input and output operations on blocks of
|
|
data. This functions can be used to read and write binary data, as well as to
|
|
read and write text in fixed-size blocks instead of by characters or lines.
|
|
|
|
Binary files are typically used to read and write blocks of data in the same
|
|
format as is used to represent the data in a running program. In other words,
|
|
arbitrary blocks of memory--not just character or string objects--can be
|
|
written to a binary file, and meaningfully read in again by the same program.
|
|
|
|
Storing data in binary form is often considerably more efficient than using
|
|
the formatted I/O functions. Also, for floating-point numbers, the binary form
|
|
avoids possible loss of precision in the conversion process. On the other
|
|
hand, binary files can't be examined or modified easily using many standard
|
|
file utilities (such as text editors), and are not portable between
|
|
different implementations of the language, or different kinds of computers.
|
|
|
|
|
|
fread() Function *crv-fread*
|
|
----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$size_t fread(void *data, size_t size, size_t count, FILE *stream);$
|
|
|
|
Return~
|
|
It returns the number of objects actually read, which might be less than
|
|
$count$if a read error occurs or the end of the file is reached. This
|
|
function returns a value of zero (and doesn't read anything) if
|
|
either$size$or$count$is zero.
|
|
If$fread()$encounters end of file in the middle of an object, it returns
|
|
the number of complete objects read, and discards the partial object.
|
|
Therefore, the stream remains at the actual end of the file.
|
|
|
|
Description~
|
|
This function reads up to$count$objects of size$size$into the array$data$,
|
|
from the stream$stream$.
|
|
|
|
|
|
fwrite() Function *crv-fwrite*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$size_t fwrite(const void *data, size_t size, size_t count, FILE *stream);$
|
|
|
|
Return~
|
|
The return value is normally$count$, if the call succeeds.
|
|
Any other value indicates some sort of error, such as running out of space.
|
|
|
|
Description~
|
|
This function writes up to count objects of size$size$from the array$data$,
|
|
to the stream$stream$.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.19.9 File Positioning *crv-libSIOHFPos*
|
|
|
|
The file position of a stream describes where in the file the stream is
|
|
currently reading or writing. I/O on the stream advances the file position
|
|
through the file.
|
|
|
|
Quicklink:
|
|
$fgetpos()$ Func |crv-fgetpos|
|
|
$fseek()$ Func |crv-fseek|
|
|
$fsetpos()$ Func |crv-fsetpos|
|
|
$ftell()$ Func |crv-ftell|
|
|
$rewind()$ Func |crv-rewind|
|
|
|
|
|
|
|
|
fgetpos() Function *crv-fgetpos*
|
|
------------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int fgetpos(FILE *stream, fpos_t *position);$
|
|
|
|
Return~
|
|
If successful,$fgetpos()$ returns zero; otherwise it returns a nonzero value
|
|
and stores an implementation-defined positive value in$errno$.
|
|
|
|
Description~
|
|
This function stores the value of the file position indicator for the stream
|
|
$stream$in the$fpos_t$object pointed to by$position$.
|
|
|
|
|
|
|
|
fseek() Function *crv-fseek*
|
|
----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int fseek(FILE *stream, long int offset, int whence);$
|
|
|
|
Return~
|
|
0 if successful,
|
|
else failed
|
|
|
|
Description~
|
|
This function is used to change the file position of the stream$stream$. The
|
|
value of$whence$must be one of the constants$SEEK_SET$,$SEEK_CUR$, or
|
|
$SEEK_END$, to indicate whether the offset is relative to the beginning of the
|
|
file, the current file position, or the end of the file, respectively.
|
|
|
|
|
|
|
|
fsetpos() Function *crv-fsetpos*
|
|
------------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int fsetpos(FILE *stream, const fpos_t *position);$
|
|
|
|
Return~
|
|
If successful,$fsetpos()$clears the end-of-file indicator on the stream,
|
|
discards any characters that were "pushed back" by the use of$ungetc()$, and
|
|
returns a value of zero.
|
|
Otherwise, it returns a nonzero value and stores an implementation-defined
|
|
positive value in$errno$.
|
|
|
|
Description~
|
|
This function sets the file position indicator for the stream$stream$to the
|
|
position$position$, which must have been set by a previous call to$fgetpos()$
|
|
on the same stream.
|
|
|
|
|
|
|
|
ftell() Function *crv-ftell*
|
|
----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$long int ftell(FILE *stream);$
|
|
|
|
Return~
|
|
This function can fail if the stream doesn't support file positioning, or if
|
|
the file position can't be represented in a$long int$, and possibly for other
|
|
reasons as well. If a failure occurs, a value of -1L is returned and an
|
|
implementation-defined positive value is stored in$errno$.
|
|
|
|
Description~
|
|
This function returns the current file position of the stream$stream$.
|
|
|
|
|
|
|
|
rewind() Function *crv-rewind*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$void rewind(FILE *stream);$
|
|
|
|
Return~
|
|
none
|
|
|
|
Description~
|
|
This function positions the stream$stream$at the beginning of the file. It is
|
|
equivalent to calling$fseek()$on the stream with an offset argument of 0L and a
|
|
whence argument of$SEEK_SET$, except that the return value is discarded and the
|
|
error indicator for the stream is reset.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.19.10 Error Handling *crv-libSIOHErr*
|
|
|
|
Quicklink:
|
|
$clearerr()$ Func |crv-libclearerr|
|
|
$feof()$ Func |crv-libfeof|
|
|
$ferror()$ Func |crv-libferror|
|
|
$perror()$ Func |crv-libperror|
|
|
|
|
|
|
|
|
clearerr() Function *crv-clearerr*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$void clearerr(FILE *stream);$
|
|
|
|
Return~
|
|
none
|
|
|
|
Description~
|
|
This function clears the end-of-file and error indicators for the stream
|
|
$stream$.
|
|
The file positioning functions also clear the end-of-file indicator for the
|
|
stream.
|
|
|
|
|
|
|
|
feof() Function *crv-feof*
|
|
---------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int feof(FILE *stream);$
|
|
|
|
Return~
|
|
0: no EOF
|
|
else: EOF
|
|
|
|
Description~
|
|
This function returns nonzero if and only if the end-of-file indicator for the
|
|
stream$stream$ is set.
|
|
|
|
|
|
|
|
ferror() Function *crv-ferror*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$int ferror(FILE *stream);$
|
|
|
|
Return~
|
|
0: no error
|
|
else: error indicator is set
|
|
|
|
Description~
|
|
This function returns nonzero if and only if the error indicator for the
|
|
stream $stream$is set, indicating that an error has occurred on a previous
|
|
operation on the stream.
|
|
|
|
|
|
|
|
perror() Function *crv-perror*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$void perror(const char *msg);$
|
|
|
|
Return~
|
|
none
|
|
|
|
Description~
|
|
This function prints an error message to the stream$stderr$. The orientation
|
|
of$stderr$is not changed.
|
|
|
|
If$perror()$is called with a message that is either a null pointer or an empty
|
|
string,$perror()$just prints the error message corresponding to$errno$, adding
|
|
a trailing newline.
|
|
|
|
If it's called with a non-null message argument, then$perror()$prefixes its
|
|
output with this string. It adds a colon and a space character to separate the
|
|
message from the error string corresponding to$errno$.
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
II.20 <stdlib.h> Utilities *crv-libStdlibH*
|
|
|
|
This header file declares types, macros and functions of general utility.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.20.1 Types *crv-libSLHType*
|
|
|
|
Quicklink:
|
|
$dif_t$ Type |crv-libdif_t|
|
|
$ldif_t$ Type |crv-libldif_t|
|
|
$lldif_t$ Type |crv-liblldif_t|
|
|
$size_t$ Type |crv-libsize_t2|
|
|
$wchar_t$ Type |crv-libwchar_t2|
|
|
|
|
|
|
|
|
dif_t Type *crv-dif_t*
|
|
----------
|
|
This is a structure type used to hold the result returned by the$div()$
|
|
function. It has the following members:
|
|
$int quot$: The quotient from the division.
|
|
$int rem$ : The remainder from the division.
|
|
|
|
|
|
ldif_t Type *crv-ldif_t*
|
|
-----------
|
|
This is a structure type used to hold the result returned by the$ldiv()$
|
|
function. It has the following members:
|
|
$long int quot$: The quotient from the division.
|
|
$long int rem$ : The remainder from the division.
|
|
|
|
|
|
lldif_t Type *crv-lldif_t*
|
|
------------
|
|
This is a structure type used to hold the result returned by the$ldiv()$
|
|
function. It has the following members:
|
|
$long long int quot$: The quotient from the division.
|
|
$long long int rem$ : The remainder from the division.
|
|
|
|
|
|
size_t Type *crv-size_t2*
|
|
-----------
|
|
This is an unsigned integer type used to represent the sizes of objects.
|
|
Also declared in$<stddef.h>$, see |crv-libsize_t|.
|
|
Also declared in$<string.h>$, see |crv-libsize_t3|.
|
|
Also declared in$<time.h>$, see |crv-libsize_t4|.
|
|
Also declared in$<stdio.h>$, see |crv-libsize_t5|.
|
|
Also declared in$<wchar.h>$, see |crv-libsize_t6|.
|
|
|
|
|
|
wchar_t Type *crv-wchar_t2*
|
|
------------
|
|
This data type is used as the base type for wide character strings.
|
|
It's range of values can represent distinct codes for all members of the
|
|
largest extended character set specified among the supported locales.
|
|
Also declared in$<stddef.h>$, see |crv-libwchar_t|.
|
|
Also declared in$<wchar.h>$, see |crv-libwchar_t3|.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.20.2 Macros *crv-libSLHMac*
|
|
|
|
Quicklink:
|
|
$EXIT_SUCCESS$ Macro |crv-libEXIT_SUCCESS|
|
|
$EXIT_FAILURE$ Macro |crv-libEXIT_FAILURE|
|
|
$MB_CUR_MAX$ Macro |crv-libMB_CUR_MAX|
|
|
$NULL$ Macro |crv-libNULL2|
|
|
$RAND_MAX$ Macro |crv-libRAND_MAX|
|
|
|
|
|
|
|
|
RAND_MAX Macro *crv-RAND_MAX*
|
|
--------------
|
|
The value of this macro is an integer constant representing the largest value
|
|
the rand function can return. Its value is implementation-defined, but at
|
|
least 32767.
|
|
|
|
|
|
|
|
EXIT_SUCCESS Macro *crv-EXIT_SUCCESS*
|
|
------------------
|
|
This macro can be used with the$exit()$function to indicate successful program
|
|
completion.
|
|
|
|
|
|
|
|
EXIT_FAILURE Macro *crv-EXIT_FAILURE*
|
|
------------------
|
|
This macro can be used with the$exit()$function to indicate unsuccessful
|
|
program completion in a general sense.
|
|
|
|
|
|
|
|
NULL Macro *crv-NULL2*
|
|
----------
|
|
Expands to an implementation-defined null pointer constant.
|
|
Also defined in$<stddef.h>$, see |crv-NULL|.
|
|
Also defined in$<string.h>$, see |crv-NULL3|.
|
|
Also defined in$<time.h>$, see |crv-NULL4|.
|
|
Also defined in$<stdio.h>$, see |crv-NULL5|.
|
|
Also defined in$<wchar.h>$, see |crv-NULL6|.
|
|
|
|
|
|
|
|
MB_CUR_MAX Macro *crv-MB_CUR_MAX*
|
|
----------------
|
|
This macro expands into a positive integer expression that is the maximum
|
|
number of bytes in a multibyte character in the current locale. The value
|
|
is never greater than$MB_LEN_MAX$.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.20.3 Numeric Conversion *crv-libSLHnum*
|
|
|
|
Quicklink:
|
|
$atof()$ Func |crv-atof|
|
|
$atoi()$ Func |crv-atoi|
|
|
$atol()$ Func |crv-atol|
|
|
$atoll()$ Func |crv-atoll|
|
|
$strtod()$ Func |crv-strtod|
|
|
$strtof()$ Func |crv-strtof|
|
|
$strtol()$ Func |crv-strtol|
|
|
$strtold()$ Func |crv-strtold|
|
|
$strtoll()$ Func |crv-strtoll|
|
|
$stroul()$ Func |crv-stroul|
|
|
$strtoull()$Func |crv-strtoull|
|
|
|
|
|
|
|
|
atof() Function *crv-atof*
|
|
---------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$double atof(const char *string);$
|
|
|
|
Return~
|
|
result of conversion
|
|
|
|
Description~
|
|
This function converts the initial portion of the string$string$to a$double$
|
|
representation. This function is similar to the$strtod()$function, except that
|
|
it need not detect overflow and underflow errors.
|
|
The atof function is provided mostly for compatibility with existing code;
|
|
using$strtod()$is more robust.
|
|
|
|
|
|
|
|
atol() Function *crv-atol*
|
|
---------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$long int atol(const char *string);$
|
|
|
|
Return~
|
|
result of conversion
|
|
|
|
Description~
|
|
This function converts the string$string$to an$long int$value.
|
|
This function is similar to the$strtol()$function with a base argument of 10,
|
|
except that it need not detect overflow errors. The$atol()$function is
|
|
provided mostly for compatibility with existing code; using$strtol()$is more
|
|
robust.
|
|
|
|
|
|
|
|
atoi() Function *crv-atoi*
|
|
---------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$int atoi(const char *string);$
|
|
|
|
Return~
|
|
result of conversion
|
|
|
|
Description~
|
|
This function converts the string$string$to an$int$value.
|
|
The$atoi()$function is considered obsolete; use$strtol()$instead.
|
|
|
|
|
|
|
|
atoll() Function *crv-atoll*
|
|
----------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$long long int atoll(const char *string);$
|
|
|
|
Return~
|
|
result of conversion
|
|
|
|
Description~
|
|
This function converts the string$string$to an$long long int$value.
|
|
The$atoll()$function was introduced in ISO C99. It is obsolete (despite having
|
|
just been added); use$strtoll()$instead.
|
|
|
|
|
|
|
|
|
|
strtol() Function *crv-strtol*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$long int strtol(const char *restrict string, char **restrict tailptr,$
|
|
$int base);$
|
|
|
|
Return~
|
|
no error: value of conversion
|
|
no conversion: 0 is returned
|
|
out of range: result is$LONG_MAX$or$LONG_MIN$(according to sign),
|
|
$ errno$is set to$ERANGE$
|
|
|
|
Description~
|
|
The$strtol()$("string-to-long") function converts the initial part of string to
|
|
a signed integer, which is returned as a value of type$long int$.
|
|
|
|
This function attempts to decompose$string$as follows:
|
|
|
|
- A (possibly empty) sequence of whitespace characters. Which characters are
|
|
whitespace is determined by the$isspace()$function. These are discarded.
|
|
- An optional plus or minus sign (+ or -).
|
|
- A nonempty sequence of digits in the radix specified by$base$.
|
|
If$base$is zero, decimal radix is assumed unless the series of digits
|
|
begins with 0 (specifying octal radix), or 0x or 0X (specifying
|
|
hexadecimal radix); in other words, the same syntax used for integer
|
|
constants in C.
|
|
Otherwise$base$must have a value between 2 and 36. If$base$is 16, the
|
|
digits may optionally be preceded by 0x or 0X. If$base$has no legal value
|
|
the value returned is 0l and the global variable$errno$is set to$EINVAL$.
|
|
- Any remaining characters in the string. If$tailptr$is not a null pointer,
|
|
$strtol()$stores a pointer to this tail in$*tailptr$.
|
|
|
|
If the string is empty, contains only whitespace, or does not contain an
|
|
initial substring that has the expected syntax for an integer in the specified
|
|
$base$, no conversion is performed. In this case,$strtol()$returns a value of
|
|
zero and the value stored in$*tailptr$is the value of$string$.
|
|
|
|
In a locale other than the standard "C" locale, this function may recognize
|
|
additional implementation-dependent syntax.
|
|
|
|
Checking for errors by examining the return value of$strtol()$should not be
|
|
done, because the string might be a valid representation of 0l,$LONG_MAX$,
|
|
or$LONG_MIN$. Instead, check whether$tailptr$points to what is expected after
|
|
the number (e.g. '\0' if the string should end after the number). $errno$needs
|
|
also to be cleared before the call and checked afterwards, in case there was
|
|
overflow.
|
|
|
|
|
|
|
|
strtoll() Function *crv-strtoll*
|
|
------------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$long long int strtoll(const char *restrict string, char **restrict tailptr,$
|
|
$int base);$
|
|
|
|
Return~
|
|
no error: value of conversion
|
|
no conversion: 0 is returned
|
|
out of range: result is$LONG_LONG_MAX$or$LONG_LONG_MIN$(according to sign),
|
|
$errno$is set to$ERANGE$
|
|
|
|
Description~
|
|
This function is like$strtol()$except that it returns a$long long int$value,
|
|
and accepts numbers with a correspondingly larger range.
|
|
|
|
|
|
|
|
stroul() Function *crv-stroul*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$unsigned long int strtoul(const char *retrict string,$
|
|
$char **restrict tailptr, int base);$
|
|
|
|
Return~
|
|
no error: value of conversion
|
|
no conversion: 0 is returned
|
|
out of range: result is$ULONG_MAX$,$errno$is set to$ERANGE$
|
|
|
|
Description~
|
|
The$strtoul()$("string-to-unsigned-long") function is like$strtol()$except it
|
|
converts to an$unsigned long int$value. The syntax is the same as described
|
|
for$strtol$.
|
|
|
|
|
|
|
|
strtoull() Function *crv-strtoull*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$unsigned long long int strtoull(const char *restrict string,$
|
|
$char **restrict tailptr, int base);$
|
|
|
|
Return~
|
|
no error: value of conversion
|
|
no conversion: 0 is returned
|
|
out of range: result is$ULONG_LONG_MAX$,$errno$is set to$ERANGE$
|
|
|
|
Description~
|
|
This function is like$strtol()$except that it returns an
|
|
$unsigned long long int$value, and accepts numbers with a correspondingly
|
|
larger range.
|
|
|
|
|
|
|
|
|
|
strtod() Function *crv-strtod*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$double strtod(const char *restrict string, char **restrict tailptr);$
|
|
|
|
Return~
|
|
no error: value of conversion
|
|
no conversion: 0 is returned
|
|
out of range: result is $-HUGE_VAL$or$+HUGH_VAL$(according to sign),
|
|
$errno$is set to$ERANGE$
|
|
|
|
Description~
|
|
The$strtod()$("string-to-double") function converts the initial part of string
|
|
to a floating-point number, which is returned as a value of type$double$.
|
|
|
|
This function attempts to decompose$string$as follows:
|
|
|
|
- A (possibly empty) sequence of whitespace characters. Which characters are
|
|
whitespace is determined by the$isspace()$function. These are discarded.
|
|
- An optional plus or minus sign (+ or -).
|
|
- A floating point number in decimal or hexadecimal format. The decimal
|
|
format is:
|
|
o A nonempty sequence of digits optionally containing a decimal-point
|
|
character - normally, but it depends on the locale.
|
|
o An optional exponent part, consisting of a character e or E, an
|
|
optional sign, and a sequence of digits.
|
|
|
|
The hexadecimal format is as follows:
|
|
o A 0x or 0X followed by a nonempty sequence of hexadecimal digits
|
|
optionally containing a decimal-point character - normally, but it
|
|
depends on the locale.
|
|
o An optional binary-exponent part, consisting of a character p or P,
|
|
an optional sign, and a sequence of digits.
|
|
|
|
- Any remaining characters in the string. If$tailptr$is not a null pointer,
|
|
a pointer to this tail of the string is stored in$*tailptr$.
|
|
|
|
If the string is empty, contains only whitespace, or does not contain an
|
|
initial substring that has the expected syntax for a floating-point number, no
|
|
conversion is performed. In this case,$strtod()$returns a value of zero
|
|
and the value returned in$*tailptr$is the value of$string$.
|
|
|
|
In a locale other than the standard "C", this function may recognize
|
|
additional locale-dependent syntax.
|
|
|
|
If the string has valid syntax for a floating-point number but the value
|
|
is outside the range of a$double$,$strtod()$will signal overflow or
|
|
underflow as described in II.12.1 Error Conditions (|crv-libMHErr|).
|
|
|
|
$strtod()$recognizes four special input strings. The strings "inf"
|
|
and "infinity" are converted to ∞, or to the largest representable
|
|
value if the floating-point format doesn't support infinities. You can
|
|
prepend a "+" or "-" to specify the sign. Case is ignored when scanning
|
|
these strings.
|
|
|
|
The strings "nan" and "nan(chars...)" are converted to NaN. Again, case is
|
|
ignored. If chars... are provided, they are used in some unspecified fashion
|
|
to select a particular representation of NaN (there can be several).
|
|
|
|
Since zero is a valid result as well as the value returned on error, you
|
|
should check for errors in the same way as for$strtol()$, by examining
|
|
$errno$and$tailptr$.
|
|
|
|
|
|
|
|
strtof() Function *crv-strtof*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$float strtof(const char *string, char **tailptr);$
|
|
|
|
Return~
|
|
no error: value of conversion
|
|
no conversion: 0 is returned
|
|
out of range: result is $-HUGE_VALF$or$+HUGH_VALF$(according to sign),
|
|
$errno$is set to$ERANGE$
|
|
|
|
Description~
|
|
This function is analogous to$strtod()$, but return$float$values respectively;
|
|
it reports errors in the same way.
|
|
|
|
|
|
|
|
strtold() Function *crv-strtold*
|
|
------------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$long double strtold(const char *string, char **tailptr);$
|
|
|
|
Return~
|
|
no error: value of conversion
|
|
no conversion: 0 is returned
|
|
out of range: result is $-HUGE_VALL$or$+HUGH_VALL$(according to sign),
|
|
$errno$is set to$ERANGE$
|
|
|
|
Description~
|
|
This function is analogous to$strtod()$, but return$long double$values
|
|
respectively; it reports errors in the same way.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.20.4 Pseudo-Random *crv-libSLHrand*
|
|
|
|
This section describes the random number functions.
|
|
|
|
Quicklink:
|
|
$rand()$ Func |crv-rand|
|
|
$srand()$ Func |crv-srand|
|
|
|
|
|
|
|
|
rand() Function *crv-rand*
|
|
---------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$int rand(void);$
|
|
|
|
Return~
|
|
pseudo-random number
|
|
|
|
Description~
|
|
This function returns the next pseudo-random number in the series. The value
|
|
ranges from 0 to$RAND_MAX$.
|
|
|
|
|
|
|
|
srand() Function *crv-srand*
|
|
----------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$void srand(unsigned int seed);$
|
|
|
|
Return~
|
|
none
|
|
|
|
Description~
|
|
This function establishes$seed$as the seed for a new series of pseudo-random
|
|
numbers.
|
|
If$rand()$is called before a seed has been established with$srand()$, it uses
|
|
the value 1 as a default seed.
|
|
|
|
To produce a different pseudo-random series each time program starts, do
|
|
$srand (time (0))$.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.20.5 Memory Management *crv-libSLHmem*
|
|
|
|
Quicklink:
|
|
$calloc()$ Func |crv-calloc|
|
|
$free()$ Func |crv-free|
|
|
$malloc()$ Func |crv-malloc|
|
|
$realloc()$Func |crv-realloc|
|
|
|
|
|
|
calloc() Function *crv-calloc*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$void *calloc(size_t count, size_t eltsize);$
|
|
|
|
Return~
|
|
pointer to allocated space or null pointer, if failed
|
|
|
|
Description~
|
|
This function allocates a block long enough to contain a vector of$count$
|
|
elements, each of size$eltsize$. Its contents are cleared to zero before
|
|
$calloc()$returns.
|
|
|
|
|
|
|
|
free() Function *crv-free*
|
|
----------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$void free(void *ptr);$
|
|
|
|
Return~
|
|
none
|
|
|
|
Description~
|
|
This function deallocates the block of memory pointed at by$ptr$that was
|
|
allocated by$calloc()$,$malloc()$or$realloc()$.
|
|
It is allowed for$ptr$to be a null pointer.
|
|
|
|
|
|
|
|
malloc() Function *crv-malloc*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$void *malloc(size_t size);$
|
|
|
|
Return~
|
|
pointer to allocated space or null pointer, if failed
|
|
|
|
Description~
|
|
This function returns a pointer to a newly allocated block$size$bytes long.
|
|
The contents of the block is undefined.
|
|
|
|
|
|
|
|
realloc() Function *crv-realloc*
|
|
------------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$void *realloc(void *ptr, size_t newsize);$
|
|
|
|
Return~
|
|
pointer to new block or null pointer, if failed
|
|
|
|
Description~
|
|
This function changes the size of the block whose address is$ptr$to be
|
|
$newsize$.
|
|
Since the space after the end of the block may be in use,$realloc()$may find
|
|
it necessary to copy the block to a new address where more free space is
|
|
available. If the block needs to be moved,$realloc()$copies the old contents.
|
|
|
|
If a null pointer is passed for$ptr$,$realloc()$behaves just like
|
|
$malloc(newsize)$.
|
|
If memory for the new block cannot be allocated the old block is not
|
|
deallocated and its value is unchanged.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.20.6 Communication *crv-libSLHcom*
|
|
|
|
Quicklink:
|
|
$_Exit()$ Func |crv-_Exit|
|
|
$abort()$ Func |crv-abort|
|
|
$atexit()$ Func |crv-atexit|
|
|
$exit()$ Func |crv-exit|
|
|
$getenv()$ Func |crv-getenv|
|
|
$system()$ Func |crv-system|
|
|
|
|
|
|
|
|
abort() Function *crv-abort*
|
|
----------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$void abort(void);$
|
|
|
|
Return~
|
|
this function does not return to its caller
|
|
|
|
Description~
|
|
This function causes abnormal program termination. This does not execute
|
|
cleanup functions registered with$atexit()$. This function actually terminates
|
|
the process by raising a SIGABRT signal.
|
|
|
|
|
|
|
|
atexit() Function *crv-atexit*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$int atexit(void (*function) (void));$
|
|
|
|
Return~
|
|
0: successful
|
|
else: failed to register function
|
|
|
|
Description~
|
|
This function registers the function$function$to be called at normal program
|
|
termination. The$function$is called with no arguments.
|
|
|
|
|
|
|
|
exit() Function *crv-exit*
|
|
---------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$void exit(int status);$
|
|
|
|
Return~
|
|
this function does not return to its caller
|
|
|
|
Description~
|
|
This function tells the system that the program is done, which causes it to
|
|
terminate the process. The value of$status$is returned to the environment.
|
|
|
|
Normal termination causes the following actions:
|
|
- Functions that were registered with the$atexit()$function are called in
|
|
the reverse order of their registration. This mechanism allows the
|
|
application to specify its own "cleanup" actions to be performed at
|
|
program termination.
|
|
- All open streams are closed, writing out any buffered output data.
|
|
In addition, temporary files opened with the$tmpfile()$function are
|
|
removed.
|
|
- Control is returned to the host environment. If$status$is zero or
|
|
$EXIT_SUCCESS$, then this signifies a successful termination. If$status$
|
|
is$EXIT_FAILURE$, then this signifies an unsuccessful termination.
|
|
Other values are implementation-defined.
|
|
|
|
|
|
|
|
_Exit() Function *crv-_Exit*
|
|
----------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$void _Exit(int status);$
|
|
|
|
Return~
|
|
this function does not return to its caller
|
|
|
|
Description~
|
|
This function is the primitive for causing a process to terminate with status
|
|
$status$. Calling this function does not execute cleanup functions registered
|
|
with$atexit()$.
|
|
|
|
Termination causes the following actions:
|
|
- All open streams are closed, writing out any buffered output data.
|
|
In addition, temporary files opened with the$tmpfile()$function are
|
|
removed.
|
|
- Control is returned to the host environment. If$status$is zero or
|
|
$EXIT_SUCCESS$, then this signifies a successful termination. If$status$
|
|
is$EXIT_FAILURE$, then this signifies an unsuccessful termination.
|
|
Other values are implementation-defined.
|
|
|
|
|
|
|
|
getenv() Function *crv-getenv*
|
|
------------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$char * getenv(const char *name);$
|
|
|
|
Return~
|
|
null pointer: environment variable not found
|
|
else: pointer to string representing the value of the environment
|
|
variable
|
|
Description~
|
|
This function returns a string that is the value of the environment variable
|
|
$name$. This string must not be modified.
|
|
|
|
|
|
|
|
system() Function *crv-system*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$int system(const char *command);$
|
|
|
|
Return~
|
|
If the$command$argument is a null pointer, a return value of zero indicates
|
|
that no command processor is available.
|
|
If the$command$argument is not a null pointer and the$system()$function does
|
|
return, it returns an implementation-defined value.
|
|
|
|
Description~
|
|
This function executes$command$as a shell command (shell = command processor).
|
|
If$command$is a null pointer, the$system()$function determines whether the
|
|
host environment has a command processor.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.20.7 Searching and Sorting *crv-libSLHsearch*
|
|
|
|
Quicklink:
|
|
$bsearch()$ Func |crv-bsearch|
|
|
$qsort()$ Func |crv-qsort|
|
|
|
|
|
|
bsearch() Function *crv-bsearch*
|
|
------------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$void *bsearch(const void *key, const void *array, size_t count,$
|
|
$size_t size, int (* compare)(const void *, const void *));$
|
|
|
|
Return~
|
|
The return value is a pointer to the matching array element, or a null pointer
|
|
if no match is found. If the array contains more than one element that
|
|
matches, the one that is returned is unspecified.
|
|
|
|
Description~
|
|
This function ("binary-search") searches the sorted array$array$for an object
|
|
that is equivalent to$key$. The array contains$count$elements, each of which
|
|
is of size$size$bytes.
|
|
|
|
The$compare$function is used to perform the comparison. This function is
|
|
called with two pointer arguments and should return an integer less than,
|
|
equal to, or greater than zero corresponding to whether its first argument
|
|
is considered less than, equal to, or greater than its second argument. The
|
|
elements of the$array$must already be sorted in ascending order according to
|
|
this comparison function.
|
|
|
|
|
|
|
|
qsort() Function *crv-qsort*
|
|
----------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$void qsort(void *array, size_t count, size_t size,$
|
|
$int (* compare)(const void *, const void *));$
|
|
|
|
Return~
|
|
none
|
|
|
|
Description~
|
|
This function sorts the array$array$. The array contains$count$elements, each
|
|
of which is of size$size$.
|
|
|
|
The$compare$function is used to perform the comparison on the array elements.
|
|
This function is called with two pointer arguments and should return an
|
|
integer less than, equal to, or greater than zero corresponding to whether its
|
|
first argument is considered less than, equal to, or greater than its second
|
|
argument.
|
|
|
|
If two objects compare as equal, their order after sorting is unpredictable.
|
|
That is to say, the sorting is not stable. This can make a difference when
|
|
the comparison considers only part of the elements. Two elements with the
|
|
same sort key may differ in other respects.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.20.8 Integer Arithmetic *crv-libSLHintarith*
|
|
|
|
Quicklink:
|
|
$abs()$ Func |crv-abs|
|
|
$labs()$ Func |crv-labs|
|
|
$llabs()$ Func |crv-llabs|
|
|
$div()$ Func |crv-div|
|
|
$ldiv()$ Func |crv-ldiv|
|
|
$lldiv()$ Func |crv-lldiv|
|
|
|
|
|
|
|
|
abs() Function *crv-abs*
|
|
--------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$int abs(int number);$
|
|
|
|
Return~
|
|
absolute value
|
|
|
|
Description~
|
|
Evaluates the absolute value of$number$.
|
|
|
|
|
|
|
|
labs() Function *crv-labs*
|
|
---------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$long int labs(long int number);$
|
|
|
|
Return~
|
|
absolute value
|
|
|
|
Description~
|
|
Evaluates the absolute value of$number$.
|
|
|
|
|
|
|
|
llabs() Function *crv-llabs*
|
|
----------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$long long int labs(long long int number);$
|
|
|
|
Return~
|
|
absolute value
|
|
|
|
Description~
|
|
Evaluates the absolute value of$number$.
|
|
|
|
|
|
|
|
div() Function *crv-div*
|
|
--------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$div_t div(int numerator, int denominator);$
|
|
|
|
Return~
|
|
return the result in a structure of type$div_t$
|
|
If the result cannot be represented (as in a division by zero), the
|
|
behavior is undefined.
|
|
|
|
Description~
|
|
This function computes the quotient and remainder from the division of
|
|
$numerator$by$denominator$.
|
|
|
|
|
|
|
|
ldiv() Function *crv-ldiv*
|
|
---------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$ldiv_t ldiv(long int numerator, long int denominator);$
|
|
|
|
Return~
|
|
return the result in a structure of type$ldiv_t$
|
|
If the result cannot be represented (as in a division by zero), the
|
|
behavior is undefined.
|
|
|
|
Description~
|
|
This function computes the quotient and remainder from the division of
|
|
$numerator$by$denominator$.
|
|
|
|
|
|
|
|
lldiv() Function *crv-lldiv*
|
|
----------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$lldiv_t lldiv(long long int numerator, long long int denominator);$
|
|
|
|
Return~
|
|
return the result in a structure of type$lldiv_t$
|
|
If the result cannot be represented (as in a division by zero), the
|
|
behavior is undefined.
|
|
|
|
Description~
|
|
This function computes the quotient and remainder from the division of
|
|
$numerator$by$denominator$.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.20.9 Multibyte/Wide Character *crv-libSLHmulchar*
|
|
|
|
Quicklink:
|
|
$mblen()$ Func |crv-mblen|
|
|
$mbtowc()$ Func |crv-mbtowc|
|
|
$wctomb()$ Func |crv-wctomb|
|
|
|
|
|
|
|
|
mblen() Function *crv-mblen*
|
|
----------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$int mblen(const char *string, size_t size);$
|
|
|
|
Return~
|
|
see description
|
|
|
|
Description~
|
|
The$mblen()$function with a non-null string argument returns the number of
|
|
bytes that make up the multibyte character beginning at$string$, never
|
|
examining more than$size$bytes.
|
|
|
|
The return value of$mblen()$distinguishes three possibilities: the first$size$
|
|
bytes at$string$start with valid multibyte characters, they start with an
|
|
invalid byte sequence or just part of a character, or$string$points to an
|
|
empty string (a null character).
|
|
|
|
For a valid multibyte character,$mblen()$returns the number of bytes in that
|
|
character (always at least 1 and never more than$size$). For an invalid byte
|
|
sequence,$mblen()$returns -1. For an empty string, it returns 0.
|
|
|
|
If the multibyte character code uses shift characters, then$mblen()$maintains
|
|
and updates a shift state as it scans. If$mblen()$is called with a null
|
|
pointer for$string$, that initializes the shift state to its standard initial
|
|
value. It also returns a nonzero value if the multibyte character code in use
|
|
actually has a shift state.
|
|
|
|
|
|
|
|
mbtowc() Function *crv-mbtowc*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$int mbtowc(wchar_t *restrict result, const char *restrict string,$
|
|
$size_t size);$
|
|
|
|
Return~
|
|
see description
|
|
|
|
Description~
|
|
The$mbtowc()$("multibyte to wide character") function when called with
|
|
non-null$string$converts the first multibyte character beginning at$string$to
|
|
its corresponding wide character code. It stores the result in$*result$.
|
|
$mbtowc()$never examines more than$size$bytes.
|
|
|
|
$mbtowc()$with non-null$string$distinguishes three possibilities: the first
|
|
size bytes at$string$start with valid multibyte characters, they start with
|
|
an invalid byte sequence or just part of a character, or string points to an
|
|
empty string (a null character).
|
|
|
|
For a valid multibyte character,$mbtowc()$converts it to a wide character and
|
|
stores that in$*result$, and returns the number of bytes in that character
|
|
(always at least 1 and never more than$size$).
|
|
|
|
For an invalid byte sequence,$mbtowc()$returns -1. For an empty string, it
|
|
returns 0, also storing '\0' in$*result$.
|
|
|
|
If the multibyte character code uses shift characters, then$mbtowc()$
|
|
maintains and updates a shift state as it scans. If$mbtowc()$is called with a
|
|
null pointer for$string$, that initializes the shift state to its standard
|
|
initial value. It also returns nonzero if the multibyte character code in use
|
|
actually has a shift state.
|
|
|
|
|
|
|
|
wctomb() Function *crv-wctomb*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$int wctomb(char *string, wchar_t wchar);$
|
|
|
|
Return~
|
|
see description
|
|
|
|
Description~
|
|
The$wctomb()$("wide character to multibyte") function converts the wide
|
|
character code$wchar$to its corresponding multibyte character sequence, and
|
|
stores the result in bytes starting at$string$. At most$MB_CUR_MAX$characters
|
|
are stored.
|
|
|
|
$wctomb()$with non-null string distinguishes three possibilities for$wchar$: a
|
|
valid wide character code (one that can be translated to a multibyte
|
|
character), an invalid code, and L'\0'.
|
|
|
|
Given a valid code,$wctomb()$converts it to a multibyte character, storing the
|
|
bytes starting at$string$. Then it returns the number of bytes in that
|
|
character (always at least 1 and never more than$MB_CUR_MAX$).
|
|
|
|
If$wchar$is an invalid wide character code,$wctomb()$returns -1. If$wchar$is
|
|
L'\0', it returns 0, also storing '\0' in$*string$.
|
|
|
|
If the multibyte character code uses shift characters, then$wctomb()$maintains
|
|
and updates a shift state as it scans. If$wctomb()$is called with a null
|
|
pointer for$string$, that initializes the shift state to its standard initial
|
|
value. It also returns nonzero if the multibyte character code in use
|
|
actually has a shift state.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.20.10 Multibyte/Wide String *crv-libSLHmulstrng*
|
|
|
|
Quicklink:
|
|
$mbstowcs()$ Func |crv-mbstowcs|
|
|
$wcstombs()$ Func |crv-wcstombs|
|
|
|
|
|
|
|
|
mbstowcs() Function *crv-mbstowcs*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$size_t mbstowcs(wchar_t *wstring, const char *string, size_t size);$
|
|
|
|
Return~
|
|
see description
|
|
|
|
Description~
|
|
The$mbstowcs()$("multibyte string to wide character string") function converts
|
|
the null-terminated string of multibyte characters$string$to an array of wide
|
|
character codes, storing not more than$size$wide characters into the array
|
|
beginning at$wstring$. The terminating null character counts towards the size,
|
|
so if$size$is less than the actual number of wide characters resulting from
|
|
$string$, no terminating null character is stored.
|
|
|
|
The conversion of characters from$string$begins in the initial shift state.
|
|
|
|
If an invalid multibyte character sequence is found, the$mbstowcs()$function
|
|
returns a value of -1. Otherwise, it returns the number of wide characters
|
|
stored in the array$wstring$. This number does not include the terminating
|
|
null character, which is present if the number is less than$size$.
|
|
|
|
|
|
|
|
wcstombs() Function *crv-wcstombs*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <stdlib.h>$
|
|
$size_t wcstombs(char *string, const wchar_t *wstring, size_t size);$
|
|
|
|
Return~
|
|
see description
|
|
|
|
Description~
|
|
The$wcstombs()$("wide character string to multibyte string") function converts
|
|
the null-terminated wide character array$wstring$into a string containing
|
|
multibyte characters, storing not more than$size$bytes starting at$string$,
|
|
followed by a terminating null character if there is room.
|
|
|
|
The conversion of characters begins in the initial shift state.
|
|
|
|
The terminating null character counts towards the size, so if$size$is less
|
|
than or equal to the number of bytes needed in$wstring$, no terminating null
|
|
character is stored.
|
|
|
|
If a code that does not correspond to a valid multibyte character is found,
|
|
the$wcstombs()$function returns a value of -1. Otherwise, the return value is
|
|
the number of bytes stored in the array$string$. This number does not include
|
|
the terminating null character, which is present if the number is less than
|
|
$size$.
|
|
|
|
|
|
|
|
==============================================================================
|
|
II.21 <string.h> String *crv-libStringH*
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.21.1 Types *crv-libSRHType*
|
|
|
|
size_t Type *crv-size_t3*
|
|
-----------
|
|
This is an unsigned integer type used to represent the sizes of objects.
|
|
Also declared in$<stddef.h>$, see |crv-size_t|.
|
|
Also declared in$<stdlib.h>$, see |crv-size_t2|.
|
|
Also declared in$<time.h>$, see |crv-size_t4|.
|
|
Also declared in$<stdio.h>$, see |crv-size_t5|.
|
|
Also declared in$<wchar.h>$, see |crv-size_t6|.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.21.2 Macros *crv-libSRHMac*
|
|
|
|
NULL Macro *crv-NULL3*
|
|
----------
|
|
Expands to an implementation-defined null pointer constant.
|
|
Also defined in$<stddef.h>$, see |crv-NULL|.
|
|
Also defined in$<stdlib.h>$, see |crv-NULL2|.
|
|
Also defined in$<time.h>$, see |crv-NULL4|.
|
|
Also defined in$<stdio.h>$, see |crv-NULL5|.
|
|
Also defined in$<wchar.h>$, see |crv-NULL6|.
|
|
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.21.3 Copying *crv-libSRHCopy*
|
|
|
|
The functions described in this section can be used to copy the contents of
|
|
strings and arrays.
|
|
|
|
Quicklink:
|
|
$memcpy()$ Func |crv-memcpy|
|
|
$memmove()$ Func |crv-memmove|
|
|
$strcpy()$ Func |crv-strcpy|
|
|
$strncpy()$ Func |crv-strncpy|
|
|
|
|
|
|
|
|
memcpy() Function *crv-memcpy*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <string.h>$
|
|
$void *memcpy(void *restrict to, const void *restrict from, size_t size);$
|
|
|
|
Return~
|
|
value of$to$
|
|
|
|
Description~
|
|
This function copies$size$bytes from the object beginning at$from$into the
|
|
object beginning at$to$. The behavior of this function is undefined if the two
|
|
arrays$to$and$from$overlap; $memmove()$can be used instead if overlapping is
|
|
possible.
|
|
|
|
|
|
|
|
memmove() Function *crv-memmove*
|
|
------------------
|
|
Synopsis~
|
|
$#include <string.h>$
|
|
$void *memmove(void *to, const void *from, size_t size);$
|
|
|
|
Return~
|
|
value of$to$
|
|
|
|
Description~
|
|
This function copies the$size$bytes at$from$into the$size$bytes at$to$, even
|
|
if those two blocks of space overlap. In the case of overlap,$memmove()$is
|
|
careful to copy the original values of the bytes in the block at$from$,
|
|
including those bytes which also belong to the block at$to$.
|
|
|
|
|
|
|
|
strcpy() Function *crv-strcpy*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <string.h>$
|
|
$char *strcpy(char *restrict to, const char *restrict from);$
|
|
|
|
Return~
|
|
value of$to$
|
|
|
|
Description~
|
|
This copies characters from the string$from$(up to and including the
|
|
terminating null character) into the string$to$. Like$memcpy()$, this function
|
|
has undefined results if the strings overlap.
|
|
|
|
|
|
|
|
strncpy() Function *crv-strncpy*
|
|
------------------
|
|
Synopsis~
|
|
$#include <string.h>$
|
|
$char *strncpy(char *restrict to, const char *restrict from, size_t size);$
|
|
|
|
Return~
|
|
value of$to$
|
|
|
|
Description~
|
|
This function is similar to$strcpy()$but always copies exactly$size$characters
|
|
into$to$.
|
|
|
|
If the length of$from$is more than$size$, then$strncpy()$copies just the first
|
|
size characters. In this case there is no null terminator written into$to$.
|
|
|
|
If the length of$from$is less than$size$, then$strncpy()$copies all of$from$,
|
|
followed by enough null characters to add up to$size$characters in all.
|
|
|
|
The behavior of$strncpy()$is undefined if the strings overlap.
|
|
|
|
NOTE: Using$strncpy()$as opposed to$strcpy()$is a way to avoid bugs relating
|
|
to writing past the end of the allocated space for$to$. However, it can also
|
|
make your program much slower in one common case: copying a string which is
|
|
probably small into a potentially large buffer. In this case, size may be
|
|
large, and when it is,$strncpy()$ will waste a considerable amount of time
|
|
copying null characters.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.21.4 Concatenation *crv-libSRHConcat*
|
|
|
|
Quicklink:
|
|
$strcat()$ Func |crv-strcat|
|
|
$strncat()$ Func |crv-strncat|
|
|
|
|
|
|
strcat() Function *crv-strcat*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <string.h>$
|
|
$char *strcat(char *restrict to, const char *restrict from);$
|
|
|
|
Return~
|
|
value of$to$
|
|
|
|
Description~
|
|
This function is similar to$strcpy()$, except that the characters from$from$
|
|
are concatenated or appended to the end of$to$, instead of overwriting it.
|
|
That is, the first character from$from$overwrites the null character marking
|
|
the end of$to$.
|
|
This function has undefined results if the strings overlap.
|
|
|
|
|
|
|
|
strncat() Function *crv-strncat*
|
|
------------------
|
|
Synopsis~
|
|
$#include <string.h>$
|
|
$char *strncat(char *restrict to, const char *restrict from, size_t size);$
|
|
|
|
Return~
|
|
value of$to$
|
|
|
|
Description~
|
|
This function is like$strcat()$except that not more than$size$characters from
|
|
$from$are appended to the end of$to$. A single null character is also always
|
|
appended to$to$, so the total allocated size of$to$must be at least
|
|
$size + 1$bytes longer than its initial length.
|
|
The behavior of this function is undefined if the strings overlap.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.21.5 Comparison *crv-libSRHCmp*
|
|
|
|
Quicklink:
|
|
$memcmp()$ Func |crv-memcmp|
|
|
$strcmp()$ Func |crv-strcmp|
|
|
$strcoll()$ Func |crv-strcoll|
|
|
$strncmp()$ Func |crv-strncmp|
|
|
$strxfrm()$ Func |crv-strxfrm|
|
|
|
|
|
|
|
|
memcmp() Function *crv-memcmp*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <string.h>$
|
|
$int memcmp(const void *a1, const void *a2, size_t size);$
|
|
|
|
Return~
|
|
The value returned is greater than, equal to, or less than zero, accordingly
|
|
as the object pointed to by$a1$is greater than, equal to, or less than the
|
|
object pointed to by$a2$.
|
|
|
|
Description~
|
|
This function compares the$size$bytes of memory beginning at$a1$against the
|
|
$size$bytes of memory beginning at$a2$.
|
|
|
|
|
|
|
|
strcmp() Function *crv-strcmp*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <string.h>$
|
|
$int strcmp(const char *s1, const char *s2);$
|
|
|
|
Return~
|
|
The value returned is greater than, equal to, or less than zero, accordingly
|
|
as the string pointed to by$s1$is greater than, equal to, or less than the
|
|
string pointed to by$s2$.
|
|
|
|
Description~
|
|
This function compares the string$s1$against$s2$.
|
|
|
|
|
|
|
|
strcoll() Function *crv-strcoll*
|
|
------------------
|
|
Synopsis~
|
|
$#include <string.h>$
|
|
$int strcoll(const char *s1, const char *s2);$
|
|
|
|
Return~
|
|
The value returned is greater than, equal to, or less than zero, accordingly
|
|
as the string pointed to by$s1$is greater than, equal to, or less than the
|
|
string pointed to by$s2$.
|
|
|
|
|
|
Description~
|
|
This function is similar to$strcmp()$but uses the collating sequence of the
|
|
current locale for collation (the$LC_COLLATE$locale).
|
|
|
|
|
|
|
|
strncmp() Function *crv-strncmp*
|
|
------------------
|
|
Synopsis~
|
|
$#include <string.h>$
|
|
$int strncmp(const char *s1, const char *s2, size_t size);$
|
|
|
|
Return~
|
|
The value returned is greater than, equal to, or less than zero, accordingly
|
|
as the string pointed to by$s1$is greater than, equal to, or less than the
|
|
string pointed to by$s2$.
|
|
|
|
Description~
|
|
This function is the similar to$strcmp()$, except that no more than$size$wide
|
|
characters are compared. In other words, if the two strings are the same in
|
|
their first$size$wide characters, the return value is zero.
|
|
|
|
|
|
|
|
strxfrm() Function *crv-strxfrm*
|
|
------------------
|
|
Synopsis~
|
|
$#include <string.h>$
|
|
$size_t strxfrm(char *restrict to, const char *restrict from, size_t size);$
|
|
|
|
Return~
|
|
The return value is the length of the entire transformed string.
|
|
This value is not affected by the value of$size$, but if it is greater or
|
|
equal than$size$, it means that the transformed string did not entirely fit
|
|
in the array$to$. In this case, only as much of the string as actually fits
|
|
was stored.
|
|
|
|
Description~
|
|
This function transforms the string$from$using the collation transformation
|
|
determined by the locale currently selected for collation, and stores the
|
|
transformed string in the array$to$. Up to$size$characters (including a
|
|
terminating null character) are stored.
|
|
|
|
If$size$is zero, no characters are stored in$to$. In this case,$strxfrm()$
|
|
simply returns the number of characters that would be the length of the
|
|
transformed string.
|
|
This is useful for determining what size the allocated array should be.
|
|
It does not matter what$to$is if$size$is zero;$to$may even be a null pointer.
|
|
|
|
The transformed string may be longer than the original string, and it may
|
|
also be shorter.
|
|
|
|
The behavior is undefined if the strings$to$and$from$overlap.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.21.6 Search *crv-libSRHSearch*
|
|
|
|
This section describes library functions which perform various kinds of
|
|
searching operations on strings and arrays.
|
|
|
|
Quicklink:
|
|
$memchr()$ Func |crv-memchr|
|
|
$strchr()$ Func |crv-strchr|
|
|
$strcspn()$ Func |crv-strcspn|
|
|
$strpbrk()$ Func |crv-strpbrk|
|
|
$strrchr()$ Func |crv-strrchr|
|
|
$strspn()$ Func |crv-strspn|
|
|
$strstr()$ Func |crv-strstr|
|
|
$strtok()$ Func |crv-strtok|
|
|
|
|
|
|
|
|
|
|
memchr() Function *crv-memchr*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <string.h>$
|
|
$void *memchr(const void *block, int c, size_t size);$
|
|
|
|
Return~
|
|
pointer to the located byte, or null pointer if no match was found
|
|
|
|
Description~
|
|
This function finds the first occurrence of the byte$c$(converted to an
|
|
$unsigned char$) in the initial$size$bytes of the object beginning at$block$.
|
|
|
|
|
|
|
|
strchr() Function *crv-strchr*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <string.h>$
|
|
$char *strchr(const char *string, int c);$
|
|
|
|
Return~
|
|
pointer to the located byte, or null pointer if no match was found
|
|
|
|
Description~
|
|
This function finds the first occurrence of the character$c$(converted to a
|
|
$char$) in the null-terminated string beginning at$string$.
|
|
|
|
|
|
|
|
strcspn() Function *crv-strcspn*
|
|
------------------
|
|
Synopsis~
|
|
$#include <string.h>$
|
|
$size_t strcspn(const char *string, const char *stopset);$
|
|
|
|
Return~
|
|
length of substring
|
|
|
|
Description~
|
|
The$strcspn()$("string complement span") function returns the length of the
|
|
initial substring of$string$that consists entirely of characters that are not
|
|
members of the set specified by the string$stopset$.
|
|
(In other words, it returns the offset of the first character in$string$that
|
|
is a member of the set$stopset$.)
|
|
|
|
|
|
|
|
strpbrk() Function *crv-strpbrk*
|
|
------------------
|
|
Synopsis~
|
|
$#include <string.h>$
|
|
$char *strpbrk(const char *string, const char *stopset);$
|
|
|
|
Return~
|
|
returns a pointer to the character, or null pointer if no such character
|
|
is found
|
|
|
|
Description~
|
|
The$strpbrk()$("string pointer break") function is related to$strcspn()$,
|
|
except that it returns a pointer to the first character in$string$that is a
|
|
member of the set$stopset$instead of the length of the initial substring.
|
|
|
|
|
|
|
|
strrchr() Function *crv-strrchr*
|
|
------------------
|
|
Synopsis~
|
|
$#include <string.h>$
|
|
$char *strrchr(const char *string, int c);$
|
|
|
|
Return~
|
|
pointer to the located byte, or null pointer if no match was found
|
|
|
|
Description~
|
|
The function$strrchr()$is like$strchr()$, except that it searches backwards
|
|
from the end of the string$string$(instead of forwards from the front).
|
|
|
|
|
|
|
|
strspn() Function *crv-strspn*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <string.h>$
|
|
$size_t strspn(const char *string, const char *skipset);$
|
|
|
|
Return~
|
|
length of substring
|
|
|
|
Description~
|
|
The$strspn()$("string span") function returns the length of the initial
|
|
substring of$string$that consists entirely of characters that are members of
|
|
the set specified by the string$skipset$. The order of the characters in
|
|
$skipset$is not important.
|
|
|
|
|
|
|
|
strstr() Function *crv-strstr*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <string.h>$
|
|
$char *strstr(const char *haystack, const char *needle);$
|
|
|
|
Return~
|
|
It returns a pointer into the string$haystack$that is the first character of
|
|
the substring, or a null pointer if no match was found. If$needle$is an empty
|
|
string, the function returns$haystack$.
|
|
|
|
Description~
|
|
This is like$strchr()$, except that it searches$haystack$for a substring
|
|
$needle$rather than just a single character.
|
|
|
|
|
|
|
|
strtok() Function *crv-strtok*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <string.h>$
|
|
$char *strtok(char *restrict newstring, const char *restrict delimiters);$
|
|
|
|
Return~
|
|
see description
|
|
|
|
Description~
|
|
A string can be split into tokens by making a series of calls to the function
|
|
$strtok()$.
|
|
|
|
The string to be split up is passed as the$newstring$argument on the first
|
|
call only. The$strtok()$function uses this to set up some internal state
|
|
information. Subsequent calls to get additional tokens from the same string
|
|
are indicated by passing a null pointer as the$newstring$argument. Calling
|
|
$strtok()$with another non-null$newstring$argument reinitializes the state
|
|
information. It is guaranteed that no other library function ever calls
|
|
$strtok()$behind your back (which would mess up this internal state
|
|
information).
|
|
|
|
The$delimiters$argument is a string that specifies a set of delimiters that
|
|
may surround the token being extracted. All the initial characters that are
|
|
members of this set are discarded. The first character that is not a member
|
|
of this set of delimiters marks the beginning of the next token. The end of
|
|
the token is found by looking for the next character that is a member of the
|
|
$delimiter$set. This character in the original string$newstring$is
|
|
overwritten by a null character, and the pointer to the beginning of the token
|
|
in$newstring$ is returned.
|
|
|
|
On the next call to$strtok()$, the searching begins at the next character
|
|
beyond the one that marked the end of the previous token.
|
|
Note that the set of delimiters$delimiters$do not have to be the same on every
|
|
call in a series of calls to$strtok()$.
|
|
|
|
If the end of the string$newstring$is reached, or if the remainder of$string$
|
|
consists only of delimiter characters,$strtok()$returns a null pointer.
|
|
|
|
Note that "character" is here used in the sense of byte. In a string using a
|
|
multibyte character encoding (abstract) character consisting of more than one
|
|
byte are not treated as an entity. Each byte is treated separately. The
|
|
function is not locale-dependent.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.21.7 Miscellaneous *crv-libSRHMisc*
|
|
|
|
Quicklink:
|
|
$memset()$ Func |crv-memset|
|
|
$strerror()$ Func |crv-strerror|
|
|
$strlen()$ Func |crv-strlen|
|
|
|
|
|
|
|
|
memset() Function *crv-memset*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <string.h>$
|
|
$void *memset(void *block, int c, size_t size);$
|
|
|
|
Return~
|
|
value of$block$
|
|
|
|
Description~
|
|
This function copies the value of$c$(converted to an$unsigned char$) into each
|
|
of the first$size$bytes of the object beginning at$block$.
|
|
|
|
|
|
|
|
strerror() Function *crv-strerror*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <string.h>$
|
|
$char *strerror(int errnum);$
|
|
|
|
Return~
|
|
The return value is a pointer to error message, which string should not be
|
|
modified. Also, if subsequent calls to$strerror()$are done, the string might
|
|
be overwritten. But it's guaranteed that no library function ever calls
|
|
$strerror()$.
|
|
|
|
Description~
|
|
This function maps the error code specified by the$errnum$argument to a
|
|
descriptive error message string.
|
|
The value$errnum$normally comes from the variable$errno$.
|
|
|
|
|
|
|
|
strlen() Function *crv-strlen*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <string.h>$
|
|
$size_t strlen(const char *s);$
|
|
|
|
Return~
|
|
length of string
|
|
|
|
Description~
|
|
The$strlen()$function returns the length of the null-terminated string$s$in bytes.
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
II.22 <tgmath.h> Type-Generic *crv-libTgmathH*
|
|
|
|
This header file includes$<math.h>$and$<complex.h>$and defines several
|
|
type-generic macros.
|
|
|
|
A type-generic macro expands to a function according to the type of the
|
|
macro's parameter(s).
|
|
E.g. there is a type-generic macro$fabs(parameter)$.This macro expands to:
|
|
-$fabs()$ if$parameter$is of type$double$
|
|
-$fabsf()$ if$parameter$is of type$float$
|
|
-$fabsl()$ if$parameter$is of type$long double$
|
|
-$cabs()$ if$parameter$is of type$double complex$
|
|
-$cabsf()$ if$parameter$is of type$float complex$
|
|
-$cabsl()$ if$parameter$is of type$long double complex$
|
|
|
|
For each function declared in$<math.h>$and$<complex.h>$which has no f ($float$)
|
|
or l ($long double$) suffix, and which has one or more parameters of type
|
|
$double$a type-generic macro is defined (except for$mdof()$).
|
|
|
|
For each function declared in$<math.h>$which has no suffix and for which there
|
|
is a corresponding function in$<complex.h>$with prefix c, a type-generic macro
|
|
is defined for both functions that has the name of the function declared
|
|
in$<math.h>$.
|
|
|
|
The type-generic macros determine the real type as follows:
|
|
- if any parameter is of type$long double$, the type determined is
|
|
$long double$
|
|
- otherwise, if any parameter is of type$double$or is of integer type, the
|
|
determined type is$double$
|
|
- otherwise, the type determined is$float$
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
II.23 <time.h> Date and Time *crv-libTimeH*
|
|
|
|
This header defines macros and declares types and functions for manipulating
|
|
time.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.23.1 Types *crv-libTHType*
|
|
|
|
Quicklink:
|
|
$size_t$ Type |crv-size_t4|
|
|
$clock_t$ Type |crv-clock_t|
|
|
$time_t$ Type |crv-time_t|
|
|
$tm$ Type |crv-tm|
|
|
|
|
|
|
|
|
size_t Type *crv-size_t4*
|
|
-----------
|
|
This is an unsigned integer type used to represent the sizes of objects.
|
|
Also declared in$<stddef.h>$, see |crv-size_t|.
|
|
Also declared in$<stdlib.h>$, see |crv-size_t2|.
|
|
Also declared in$<string.h>$, see |crv-size_t3|.
|
|
Also declared in$<stdio.h>$, see |crv-size_t5|.
|
|
Also declared in$<wchar.h>$, see |crv-size_t6|.
|
|
|
|
|
|
|
|
clock_t Type *crv-clock_t*
|
|
------------
|
|
This is the type of the value returned by the$clock()$function. Values of
|
|
type$clock_t$are numbers of clock ticks.
|
|
|
|
|
|
|
|
time_t Type *crv-time_t*
|
|
-----------
|
|
This is the data type used to represent simple time. Sometimes, it also
|
|
represents an elapsed time. When interpreted as a calendar time value, it
|
|
represents the number of seconds elapsed since 00:00:00 on January 1, 1970,
|
|
Coordinated Universal Time. (This calendar time is sometimes referred to as
|
|
the epoch.).
|
|
|
|
NOTE: A simple time has no concept of local time zone. Calendar Time T
|
|
is the same instant in time regardless of where on the globe the computer is.
|
|
|
|
|
|
|
|
struct tm Type *crv-tm*
|
|
--------------
|
|
This is the data type used to represent a broken-down time. The structure
|
|
contains at least the following members, which can appear in any order.
|
|
|
|
$int tm_sec$
|
|
This is the number of full seconds since the top of the minute (normally
|
|
in the range 0 through 59, but the actual upper limit is 60, to allow for
|
|
leap seconds if leap second support is available).
|
|
|
|
$int tm_min$
|
|
This is the number of full minutes since the top of the hour (in the range
|
|
0 through 59).
|
|
|
|
$int tm_hour$
|
|
This is the number of full hours past midnight (in the range 0 through 23).
|
|
|
|
$int tm_mday$
|
|
This is the ordinal day of the month (in the range 1 through 31).
|
|
|
|
$int tm_mon$
|
|
This is the number of full calendar months since the beginning of the year
|
|
(in the range 0 through 11).
|
|
|
|
$int tm_year$
|
|
This is the number of full calendar years since 1900.
|
|
|
|
$int tm_wday$
|
|
This is the number of full days since Sunday (in the range 0 through 6).
|
|
|
|
$int tm_yday$
|
|
This is the number of full days since the beginning of the year (in the
|
|
range 0 through 365).
|
|
|
|
$int tm_isdst$
|
|
This is a flag that indicates whether Daylight Saving Time is (or was, or
|
|
will be) in effect at the time described. The value is positive if
|
|
Daylight Saving Time is in effect, zero if it is not, and negative if the
|
|
information is not available.
|
|
|
|
Also declared in$<wchar.h>$, see |crv-tm2|.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.23.2 Macros *crv-libTHMac*
|
|
|
|
Quicklink:
|
|
$CLOCKS_PER_SEC$ Macro |crv-CLOCKS_PER_SEC|
|
|
$NULL$ Macro |crv-NULL4|
|
|
|
|
|
|
|
|
NULL Macro *crv-NULL4*
|
|
----------
|
|
Expands to an implementation-defined null pointer constant.
|
|
Also defined in$<stddef.h>$, see |crv-NULL|.
|
|
Also defined in$<stdlib.h>$, see |crv-NULL2|.
|
|
Also defined in$<string.h>$, see |crv-NULL3|.
|
|
Also defined in$<stdio.h>$, see |crv-NULL5|.
|
|
Also defined in$<wchar.h>$, see |crv-NULL6|.
|
|
|
|
|
|
|
|
CLOCKS_PER_SEC Macro *crv-CLOCKS_PER_SEC*
|
|
--------------------
|
|
The value of this macro is the number of clock ticks per second measured by
|
|
the$clock()$function.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.23.3 Time Manipulation *crv-libTHMani*
|
|
|
|
Quicklink:
|
|
$clock()$ Func |crv-clock|
|
|
$difftime()$ Func |crv-difftime|
|
|
$mktime()$ Func |crv-mktime|
|
|
$time()$ Func |crv-time|
|
|
|
|
|
|
|
|
clock() Function *crv-clock*
|
|
----------------
|
|
Synopsis~
|
|
$#include <time.h>$
|
|
$clock_t clock(void);$
|
|
|
|
Return~
|
|
CPU time ot (clock_t)(-1) if an error occurred
|
|
|
|
Description~
|
|
This function returns the calling process' current CPU time. If the CPU time
|
|
is not available or cannot be represented, clock returns the value
|
|
(clock_t)(-1).
|
|
Time in seconds can be determined by dividing the result of$clock()$by
|
|
$CLOCKS_PER_SECOND$.
|
|
|
|
|
|
|
|
difftime() Function *crv-difftime*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <time.h>$
|
|
$double difftime(time_t time1, time_t time0);$
|
|
|
|
Return~
|
|
seconds elapsed
|
|
|
|
Description~
|
|
This function returns the number of seconds of elapsed time between calendar
|
|
time$time1$and calendar time$time0$, as a value of type$double$. The
|
|
difference ignores leap seconds unless leap second support is enabled.
|
|
|
|
|
|
|
|
mktime() Function *crv-mktime*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <time.h>$
|
|
$time_t mktime(struct tm *brokentime);$
|
|
|
|
Return~
|
|
Simple time, or if the specified broken-down time cannot be represented as a
|
|
simple time,$mktime()$returns a value of (time_t)(-1) and does not modify the
|
|
contents of$brokentime$.
|
|
|
|
Description~
|
|
The$mktime()$function is used to convert a broken-down time structure to a
|
|
simple time representation. It also "normalizes" the contents of the
|
|
broken-down time structure, by filling in the day of week and day of year
|
|
based on the other date and time components.
|
|
|
|
The$mktime()$function ignores the specified contents of the$tm_wday$and
|
|
$tm_yday$members of the broken-down time structure. It uses the values of the
|
|
other components to determine the calendar time; it's permissible for these
|
|
components to have unnormalized values outside their normal ranges. The last
|
|
thing that$mktime()$does is adjust the components of the brokentime structure
|
|
(including the$tm_wday$and$tm_yday$).
|
|
|
|
|
|
|
|
time() Function *crv-time*
|
|
---------------
|
|
Synopsis~
|
|
$#include <time.h>$
|
|
$time_t time(time_t *result);$
|
|
|
|
Return~
|
|
current calenar time or if the current calendar time is not available,
|
|
the value (time_t)(-1)
|
|
|
|
Description~
|
|
The$time()$function returns the current calendar time as a value of type
|
|
$time_t$. If the argument$result$is not a null pointer, the calendar time
|
|
value is also stored in$*result$.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.23.4 Time Conversion *crv-libTHConv*
|
|
|
|
Quicklink:
|
|
$asctime()$ Func |crv-asctime|
|
|
$ctime()$ Func |crv-ctime|
|
|
$gmtime()$ Func |crv-gmtime|
|
|
$localtime()$ Func |crv-localtime|
|
|
$strftime()$ Func |crv-strftime|
|
|
|
|
|
|
|
|
asctime() Function *crv-asctime*
|
|
------------------
|
|
Synopsis~
|
|
$#include <time.h>$
|
|
$char *asctime(const struct tm *brokentime);$
|
|
|
|
Return~
|
|
The return value points to a statically allocated string, which might be
|
|
overwritten by subsequent calls to$asctime()$or$ctime$. But no other library
|
|
function overwrites the contents of this string.
|
|
|
|
Description~
|
|
This function converts the broken-down time value that$brokentime$points to
|
|
into a string in a standard format:
|
|
"Tue May 21 13:46:22 1991\n"
|
|
|
|
The abbreviations for the days of week are: Sun, Mon, Tue, Wed, Thu, Fri, and
|
|
Sat.
|
|
|
|
The abbreviations for the months are: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug,
|
|
Sep, Oct, Nov, and Dec.
|
|
|
|
|
|
|
|
ctime() Function *crv-ctime*
|
|
----------------
|
|
Synopsis~
|
|
$#include <time.h>$
|
|
$char *ctime(const time_t *time);$
|
|
|
|
Return~
|
|
The return value points to a statically allocated string, which might be
|
|
overwritten by subsequent calls to$asctime()$or$ctime$. But no other library
|
|
function overwrites the contents of this string.
|
|
|
|
Description~
|
|
The$ctime()$function is similar to$asctime()$, except that calendar time
|
|
is specified as a$time_t$simple time value rather than in broken-down local
|
|
time format. It is equivalent to:
|
|
$asctime (localtime (time))$
|
|
|
|
|
|
|
|
gmtime() Function *crv-gmtime*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <time.h>$
|
|
$struct tm *gmtime(const time_t *time);$
|
|
|
|
Return~
|
|
returns pointer to the broken-down time, or a null pointer if the specified
|
|
time cannot be converted to UTC
|
|
|
|
Description~
|
|
This function is similar to$localtime()$, except that the broken-down time is
|
|
expressed as Coordinated Universal Time (UTC) (formerly called Greenwich Mean
|
|
Time (GMT)) rather than relative to a local time zone.
|
|
|
|
|
|
|
|
localtime() Function *crv-localtime*
|
|
--------------------
|
|
Synopsis~
|
|
$#include <time.h>$
|
|
$struct tm *localtime (const time_t *time);$
|
|
|
|
Return~
|
|
returns pointer to the broken-down time, or a null pointer if the specified
|
|
time cannot be converted to local time
|
|
|
|
Description~
|
|
The$localtime()$function converts the simple time pointed to by$time$to
|
|
broken-down time representation, expressed relative to the user's specified
|
|
time zone.
|
|
|
|
|
|
|
|
strftime() Function *crv-strftime*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <time.h>$
|
|
$size_t strftime(char *s, size_t size, const char *format,$
|
|
$const struct tm *brokentime;$
|
|
|
|
Return~
|
|
number of characters placed in$s$, not including the terminating null
|
|
character
|
|
if this number is greater than$size$, zero is returned
|
|
|
|
Description~
|
|
This function is similar to the$sprintf()$function, but the conversion
|
|
specifications that can appear in the format$format$are specialized for
|
|
printing components of the date and time$brokentime$according to the locale
|
|
currently specified for time conversion.
|
|
|
|
Ordinary characters appearing in the format are copied to the output
|
|
string$s$; this can include multibyte character sequences. Conversion
|
|
specifiers are introduced by a$%$character, followed by an optional
|
|
modifier. The modifier extensions are:
|
|
|
|
- E Use the locale's alternate representation for date and time. This
|
|
modifier applies to the$%c, %C, %x, %X, %y, %Y$format specifiers.
|
|
- O Use the locale's alternate numeric symbols for numbers. This modifier
|
|
applies only to numeric format specifiers.
|
|
|
|
|
|
If the format supports the modifier but no alternate representation is
|
|
available, it is ignored.
|
|
|
|
The conversion specifier ends with a format specifier taken from the following
|
|
list. The whole % sequence is replaced in the output string as follows:
|
|
|
|
$%a$ The abbreviated weekday name according to the current locale.
|
|
$%A$ The full weekday name according to the current locale.
|
|
$%b$ The abbreviated month name according to the current locale.
|
|
$%B$ The full month name according to the current locale.
|
|
$%c$ The preferred calendar time representation for the current locale.
|
|
$%C$ The century of the year. This is equivalent to the greatest integer
|
|
not greater than the year divided by 100.
|
|
$%d$ The day of the month as a decimal number (range 01 through 31).
|
|
$%D$ The date using the format$%m/%d/%y$.
|
|
$%e$ The day of the month like with %d, but padded with blank (range 1
|
|
through 31).
|
|
$%F$ The date using the format$%Y-%m-%d$.
|
|
$%g$ The year corresponding to the ISO week number, but without the century
|
|
(range 00 through 99). This has the same format and value as$%y$,
|
|
except that if the ISO week number (see$%V$) belongs to the previous
|
|
or next year, that year is used instead.
|
|
$%G$ The year corresponding to the ISO week number. This has the same format
|
|
and value as$%Y$, except that if the ISO week number (see %V) belongs
|
|
to the previous or next year, that year is used instead.
|
|
$%h$ The abbreviated month name according to the current locale. The action
|
|
is the same as for$%b$.
|
|
$%H$ The hour as a decimal number, using a 24-hour clock (range 00 through
|
|
23).
|
|
$%I$ The hour as a decimal number, using a 12-hour clock (range 01 through
|
|
12).
|
|
$%j$ The day of the year as a decimal number (range 001 through 366).
|
|
$%k$ The hour as a decimal number, using a 24-hour clock like$%H$, but padded
|
|
with blank (range 0 through 23).
|
|
$%l$ The hour as a decimal number, using a 12-hour clock like$%I$, but padded
|
|
with blank (range 1 through 12).
|
|
$%m$ The month as a decimal number (range 01 through 12).
|
|
$%M$ The minute as a decimal number (range 00 through 59).
|
|
$%n$ A single \n (newline) character.
|
|
$%p$ Either AM or PM, according to the given time value; or the corresponding
|
|
strings for the current locale. Noon is treated as PM and midnight as AM.
|
|
$%r$ The complete calendar time using the AM/PM format of the current locale.
|
|
$%R$ The hour and minute in decimal numbers using the format$%H:%M$.
|
|
$%S$ The seconds as a decimal number (range 00 through 60).
|
|
$%t$ A single \t (tabulator) character.
|
|
$%T$ The time of day using decimal numbers using the format$%H:%M:%S$.
|
|
$%u$ The day of the week as a decimal number (range 1 through 7), Monday
|
|
being 1.
|
|
$%U$ The week number of the current year as a decimal number (range 00 through
|
|
53), starting with the first Sunday as the first day of the first week.
|
|
Days preceding the first Sunday in the year are considered to be in week
|
|
00.
|
|
$%V$ The ISO 8601:1988 week number as a decimal number (range 01 through 53).
|
|
ISO weeks start with Monday and end with Sunday. Week 01 of a year is the
|
|
first week which has the majority of its days in that year; this is
|
|
equivalent to the week containing the year's first Thursday, and it is
|
|
also equivalent to the week containing January 4. Week 01 of a year can
|
|
contain days from the previous year. The week before week 01 of a year
|
|
is the last week (52 or 53) of the previous year even if it contains days
|
|
from the new year.
|
|
$%w$ The day of the week as a decimal number (range 0 through 6), Sunday
|
|
being 0.
|
|
$%W$ The week number of the current year as a decimal number (range 00 through
|
|
53), starting with the first Monday as the first day of the first week.
|
|
All days preceding the first Monday in the year are considered to be in
|
|
week 00.
|
|
$%x$ The preferred date representation for the current locale.
|
|
$%X$ The preferred time of day representation for the current locale.
|
|
$%y$ The year without a century as a decimal number (range 00 through 99).
|
|
This is equivalent to the year modulo 100.
|
|
$%Y$ The year as a decimal number, using the Gregorian calendar. Years before
|
|
the year 1 are numbered 0, -1, and so on.
|
|
$%z$ RFC 822/ISO 8601:1988 style numeric time zone (e.g., -0600 or +0100), or
|
|
nothing if no time zone is determinable.
|
|
A full RFC 822 timestamp is generated by the format
|
|
$"%a, %d %b %Y %H:%M:%S %z"$ (or the equivalent$"%a, %d %b %Y %T %z"$).
|
|
$%Z$ The time zone abbreviation (empty if the time zone can't be determined).
|
|
$%%$ A literal % character.
|
|
|
|
|
|
The$size$parameter can be used to specify the maximum number of characters to
|
|
be stored in the array$s$, including the terminating null character. If the
|
|
formatted time requires more than$size$characters,$strftime()$returns zero
|
|
and the contents of the array$s$are undefined. Otherwise the return value
|
|
indicates the number of characters placed in the array$s$, not including
|
|
the terminating null character.
|
|
|
|
Warning: This convention for the return value which is prescribed in ISO C
|
|
can lead to problems in some situations. For certain format strings and
|
|
certain locales the output really can be the empty string and this cannot
|
|
be discovered by testing the return value only. E.g., in most locales the
|
|
AM/PM time format is not supported (most of the world uses the 24 hour
|
|
time representation). In such locales$"%p"$will return the empty string,
|
|
i.e., the return value is zero. To detect situations like this something
|
|
similar to the following code should be used:
|
|
>
|
|
buf[0] = '\1';
|
|
len = strftime (buf, bufsize, format, tp);
|
|
if (len == 0 && buf[0] != '\0')
|
|
{
|
|
/* Something went wrong in the strftime call. */
|
|
...
|
|
}
|
|
|
|
|
|
If$s$is a null pointer,$strftime()$does not actually write anything, but
|
|
instead returns the number of characters it would have written.
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
II.24 <wchar.h> Wide Utilities *crv-libWcharH*
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.24.1 Types *crv-libWCHType*
|
|
|
|
Quicklink:
|
|
$mbstate_t$ Type |crv-mbstate_t|
|
|
$tm$ Type |crv-tm2|
|
|
$size_t$ Type |crv-size_t6|
|
|
$wchar_t$ Type |crv-wchar_t3|
|
|
$wint_t$ Type |crv-wint_t2|
|
|
|
|
|
|
|
|
mbstate_t Type *crv-mbstate_t*
|
|
--------------
|
|
A variable of type$mbstate_t$can contain all the information about the shift
|
|
state needed from one call to a conversion function to another.
|
|
|
|
|
|
struct tm Type *crv-tm2*
|
|
--------------
|
|
Also declared in$<time.h>$, for description see |crv-tm|.
|
|
|
|
|
|
size_t Type *crv-size_t6*
|
|
-----------
|
|
This is an unsigned integer type used to represent the sizes of objects.
|
|
Also declared in$<stddef.h>$, see |crv-size_t|.
|
|
Also declared in$<stdlib.h>$, see |crv-size_t2|.
|
|
Also declared in$<string.h>$, see |crv-size_t3|.
|
|
Also declared in$<time.h>$, see |crv-size_t4|.
|
|
Also declared in$<stdio.h>$, see |crv-size_t5|.
|
|
|
|
|
|
wchar_t Type *crv-wchar_t3*
|
|
------------
|
|
This data type is used as the base type for wide character strings.
|
|
It's range of values can represent distinct codes for all members of the
|
|
largest extended character set specified among the supported locales.
|
|
Also declared in$<stddef.h>$, see |crv-wchar_t|.
|
|
Also declared in$<stdlib.h>$, see |crv-wchar_t2|.
|
|
|
|
|
|
wint_t Type *crv-wint_t2*
|
|
-----------
|
|
This is a data type used for parameters and variables that contain a single
|
|
wide character.
|
|
Also declared in$<wctype.h>$, see |crv-wint_t|.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.24.2 Macros *crv-libWCHMac*
|
|
|
|
Quicklink:
|
|
$NULL$ Macro |crv-NULL6|
|
|
$WCHAR_MIN$ Macro |crv-WCHAR_MIN2|
|
|
$WCHAR_MAX$ Macro |crv-WCHAR_MAX2|
|
|
$WEOF$ Macro |crv-WEOF2|
|
|
|
|
|
|
NULL Macro *crv-NULL6*
|
|
----------
|
|
Expands to an implementation-defined null pointer constant.
|
|
Also defined in$<stddef.h>$, see |crv-NULL|.
|
|
Also defined in$<stdlib.h>$, see |crv-NULL2|.
|
|
Also defined in$<string.h>$, see |crv-NULL3|.
|
|
Also defined in$<time.h>$, see |crv-NULL4|.
|
|
Also defined in$<stdio.h>$, see |crv-NULL5|.
|
|
|
|
|
|
WCHAR_MIN Macro *crv-WCHAR_MIN2*
|
|
WCHAR_MAX Macro *crv-WCHAR_MAX2*
|
|
---------------
|
|
Minimum and maximum value representable by an object of type$wchar_t$.
|
|
Also defined in$<wctype.h>$, see |crv-libWCHAR_MIN|, |crv-libWCHAR_MAX|.
|
|
|
|
|
|
WEOF Macro *crv-WEOF2*
|
|
----------
|
|
This macro expands to an expression of type$wint_t$that is returned by a
|
|
number of wide stream functions to indicate an end-of-file condition, or some
|
|
other error situation.
|
|
Also declared in$<wctype.t>$, see |crv-libWEOF|.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.24.3 Formatted Input/Output *crv-libWCHIO*
|
|
|
|
Quicklink:
|
|
$fwprintf()$ Func |crv-fwprintf|
|
|
$swprintf()$ Func |crv-swprintf|
|
|
$wprintf()$ Func |crv-wprintf|
|
|
$wscanf()$ Func |crv-wscanf|
|
|
$fwscanf()$ Func |crv-fwscanf|
|
|
$swscanf()$ Func |crv-swscanf|
|
|
$vfwprintf()$ Func |crv-vfwprintf|
|
|
$vswprintf()$ Func |crv-vswprintf|
|
|
$vwprintf()$ Func |crv-vwprintf|
|
|
$vfwscanf()$ Func |crv-vfwscanf|
|
|
$vswscanf()$ Func |crv-vswscanf|
|
|
$vwscanf()$ Func |crv-vwscanf|
|
|
|
|
|
|
|
|
wprintf() Function *crv-wprintf*
|
|
------------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$int wprintf(const wchar_t *format, ...);$
|
|
|
|
Return~
|
|
<0: output error occurred
|
|
>= 0: number of transmitted characters
|
|
|
|
Description~
|
|
This function prints the optional arguments under the control of the wide
|
|
format string$format$to the standard output stream$stdout$.
|
|
For format string see |crv-libSIOHIOFout|.
|
|
|
|
|
|
|
|
fwprintf() Function *crv-fwprintf*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$#include <wchar.h>$
|
|
$int fwprintf(FILE *stream, const wchar_t *format, ...);$
|
|
|
|
Return~
|
|
<0: output error occurred
|
|
>= 0: number of transmitted characters
|
|
|
|
Description~
|
|
This function is just like$wprintf()$, except that the output is written to
|
|
the stream$stream$instead of standard output stream$stdout$.
|
|
|
|
|
|
|
|
swprintf() Function *crv-swprintf*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$int swprintf(wchar_t *s, size_t size, const wchar_t *format, ...);$
|
|
|
|
Return~
|
|
The return value is the number of characters generated for the given input,
|
|
excluding the trailing null. If not all output fits into the provided
|
|
buffer or an error occurred a negative value is returned.
|
|
|
|
Description~
|
|
This is like$wprintf()$, except that the output is stored in the wide
|
|
character array$s$instead of written to a stream. A null wide character is
|
|
written to mark the end of the string. The$size$argument specifies the maximum
|
|
number of characters to produce. The trailing null character is counted
|
|
towards this limit.
|
|
|
|
|
|
|
|
vwprintf() Function *crv-vwprintf*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <stdarg.h>$
|
|
$#include <wchar.h>$
|
|
$int vwprintf(const wchar_t *format, va_list ap);$
|
|
|
|
Return~
|
|
|
|
Description~
|
|
This function is similar to$wprintf()$except that, instead of taking a
|
|
variable number of arguments directly, it takes an argument list pointer$ap$.
|
|
|
|
|
|
|
|
vfwprintf() Function *crv-vfwprintf*
|
|
--------------------
|
|
Synopsis~
|
|
$#include <stdarg.h>$
|
|
$#include <stdio.h>$
|
|
$#include <wchar.h>$
|
|
$int vfwprintf(FILE *stream, const wchar_t *format, va_list ap);$
|
|
|
|
Return~
|
|
|
|
Description~
|
|
This is the equivalent of$fwprintf()$with the variable argument list specified
|
|
directly as for$vwprintf()$.
|
|
|
|
|
|
|
|
vswprintf() Function *crv-vswprintf*
|
|
--------------------
|
|
Synopsis~
|
|
$#include <stdarg.h>$
|
|
$#include <stdio.h>$
|
|
$#include <wchar.h>$
|
|
$int vswprintf(wchar_t *s, size_t size, const wchar_t *format, va_list ap);$
|
|
|
|
Return~
|
|
|
|
Description~
|
|
This is the equivalent of$swprintf()$with the variable argument list specified
|
|
directly as for$vwprintf()$.
|
|
|
|
|
|
|
|
wscanf() Function *crv-wscanf*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$int wscanf(const wchar_t *format, ...);$
|
|
|
|
Return~
|
|
The return value is normally the number of successful assignments. If an
|
|
end-of-file condition is detected before any matches are performed, including
|
|
matches against whitespace and literal characters in the template, then$WEOF$
|
|
is returned.
|
|
|
|
Description~
|
|
The$wscanf()$function reads formatted input from the stream$stdin$under the
|
|
control of the format string$format$. The optional arguments are pointers to
|
|
the places which receive the resulting values.
|
|
For format string see |crv-libSIOHIOFin|.
|
|
|
|
|
|
|
|
fwscanf() Function *crv-fwscanf*
|
|
------------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$#include <wchar.h>$
|
|
$int fwscanf(FILE *stream, const wchar_t *format, ...);$
|
|
|
|
Return~
|
|
|
|
Description~
|
|
This function is just like$wscanf()$, except that the input is read from the
|
|
stream$stream$instead of$stdin$.
|
|
|
|
|
|
|
|
swscanf() Function *crv-swscanf*
|
|
------------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$int swscanf (const wchar_t *ws, const char *format, ...);$
|
|
|
|
Return~
|
|
|
|
Description~
|
|
This is like$wscanf()$, except that the characters are taken from the
|
|
null-terminated string$ws$instead of from a$stream$. Reaching the end of the
|
|
string is treated as an end-of-file condition.
|
|
|
|
The behavior of this function is undefined if copying takes place between
|
|
objects that overlap.
|
|
|
|
|
|
|
|
vwscanf() Function *crv-vwscanf*
|
|
------------------
|
|
Synopsis~
|
|
$#include <stdarg.h>$
|
|
$#include <wchar.h>$
|
|
$int vwscanf(const wchar_t *format, va_list ap);$
|
|
|
|
Return~
|
|
|
|
Description~
|
|
This function is similar to$wscanf()$, but instead of taking a variable number
|
|
of arguments directly, it takes an argument list pointer ap of type$va_list$.
|
|
|
|
|
|
|
|
vfwscanf() Function *crv-vfwscanf*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <stdarg.h>$
|
|
$#include <stdio.h>$
|
|
$#include <wchar.h>$
|
|
$int vfwscanf(FILE *stream, const wchar_t *format, va_list ap);$
|
|
|
|
Return~
|
|
|
|
Description~
|
|
This is the equivalent of$fwscanf()$with the variable argument list specified
|
|
directly as for$vwscanf()$.
|
|
|
|
|
|
|
|
vswscanf() Function *crv-vswscanf*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <stdarg.h>$
|
|
$#include <wchar.h>$
|
|
$int vswscanf(const wchar_t *s, const wchar_t *format, va_list ap);$
|
|
|
|
Return~
|
|
|
|
Description~
|
|
This is the equivalent of$swscanf()$with the variable argument list specified
|
|
directly as for$vwscanf()$.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.24.4 Character Input/Output *crv-libWCHCIO*
|
|
|
|
Quicklink:
|
|
$fgetwc()$ Func |crv-fgetwc|
|
|
$fgetws()$ Func |crv-fgetws|
|
|
$getwc()$ Macro |crv-getwc|
|
|
$getwchar()$ Macro |crv-getwchar|
|
|
$ungetwc()$ Func |crv-ungetwc|
|
|
$fputwc()$ Func |crv-fputwc|
|
|
$fputws()$ Func |crv-fputws|
|
|
$putwc()$ Macro |crv-putwc|
|
|
$putwchar()$ Macro |crv-putwchar|
|
|
$fwide()$ Func |crv-fwide|
|
|
|
|
|
|
|
|
fgetwc() Function *crv-fgetwc*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$#include <wchar.h>$
|
|
$wint_t fgetwc(FILE *stream);$
|
|
|
|
Return~
|
|
wide character read from stream, or$WEOF$if an error or an end-of-file
|
|
condition occurred
|
|
|
|
Description~
|
|
This function reads the next wide character from the stream$stream$and returns
|
|
its value.
|
|
|
|
|
|
|
|
fgetws() Function *crv-fgetws*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$#include <wchar.h>$
|
|
$wchar_t *fgetws(wchar_t *ws, int count, FILE *stream);$
|
|
|
|
Return~
|
|
If the system is already at end of file when$fgetws()$is called, then the
|
|
contents of the array$ws$are unchanged and a null pointer is returned. A null
|
|
pointer is also returned if a read error occurs. Otherwise, the return value
|
|
is the pointer$ws$.
|
|
|
|
Description~
|
|
This function reads wide characters from the stream$stream$up to and including
|
|
a newline character and stores them in the string$ws$, adding a null wide
|
|
character to mark the end of the string.$count$wide characters worth of space
|
|
in$ws$must be supplied, but the number of characters read is at most
|
|
$count - 1$. The extra character space is used to hold the null wide character
|
|
at the end of the string.
|
|
|
|
|
|
|
|
getwc() Macro *crv-getwc*
|
|
-------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$#include <wchar.h>$
|
|
$wint_t getwc(FILE *stream);$
|
|
|
|
Return~
|
|
wide character read from stream, or$WEOF$if an error or an end-of-file
|
|
condition occurred
|
|
|
|
Description~
|
|
This is just like$fgetwc()$, except that it is permissible for it to be
|
|
implemented as a macro that evaluates the$stream$argument more than once.
|
|
$getwc()$can be highly optimized, so it is usually the best function to use
|
|
to read a single wide character.
|
|
|
|
|
|
|
|
getwchar() Macro *crv-getwchar*
|
|
----------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$wint_t getwchar(void);$
|
|
|
|
Return~
|
|
wide character read from stream, or$WEOF$if an error or an end-of-file
|
|
condition occurred
|
|
|
|
Description~
|
|
This function is equivalent to$getwc()$with$stdin$as the value of the stream
|
|
argument.
|
|
|
|
|
|
|
|
ungetwc() Function *crv-ungetwc*
|
|
------------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$#include <wchar.h>$
|
|
$wint_t ungetwc(wint_t wc, FILE *stream);$
|
|
|
|
Return~
|
|
|
|
Description~
|
|
The$ungetwc()$function behaves just like$ungetc()$just that it pushes back a
|
|
wide character.
|
|
|
|
|
|
|
|
fputwc() Function *crv-fputwc*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$#include <wchar.h>$
|
|
$wint_t fputwc(wchar_t wc, FILE *stream);$
|
|
|
|
Return~
|
|
$WEOF$is returned if a write error occurs; otherwise the character$wc$is
|
|
returned
|
|
|
|
Description~
|
|
This function writes the wide character$wc$to the stream$stream$.
|
|
|
|
|
|
|
|
fputws() Function *crv-fputws*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$#include <wchar.h>$
|
|
$int fputws(const wchar_t *ws, FILE *stream);$
|
|
|
|
Return~
|
|
$WEOF$is returned if a write error occurs, otherwise a non-negative value
|
|
|
|
Description~
|
|
The function$fputws()$writes the wide character string$ws$to the stream
|
|
$stream$. The terminating null character is not written. This function does
|
|
not add a newline character, either. It outputs only the characters in the
|
|
string.
|
|
|
|
|
|
|
|
putwc() Macro *crv-putwc*
|
|
-------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$#include <wchar.h>$
|
|
$wint_t putwc(wchar_t wc, FILE *stream);$
|
|
|
|
Return~
|
|
$WEOF$is returned if a write error occurs; otherwise the character$wc$is
|
|
returned
|
|
|
|
Description~
|
|
This is just like$fputwc()$, except that it can be implement as a macro,
|
|
making it faster. One consequence is that it may evaluate the$stream$argument
|
|
more than once, which is an exception to the general rule for macros.$putwc()$
|
|
is usually the best function to use for writing a single wide character.
|
|
|
|
|
|
|
|
putwchar() Macro *crv-putwchar*
|
|
----------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$wint_t putwchar(wchar_t wc);$
|
|
|
|
Return~
|
|
$WEOF$is returned if a write error occurs; otherwise the character$wc$is
|
|
returned
|
|
|
|
Description~
|
|
The$putwchar()$function is equivalent to$putwc()$with$stdout$as the value
|
|
of the stream argument.
|
|
|
|
|
|
|
|
fwide() Function *crv-fwide*
|
|
----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$#include <wchar.h>$
|
|
$int fwide(FILE *stream, int mode);$
|
|
|
|
Return~
|
|
The$fwide()$function returns a negative value, zero, or a positive value if
|
|
the stream is narrow, not at all, or wide oriented respectively.
|
|
|
|
Description~
|
|
The$fwide()$function can be used to set and query the state of the orientation
|
|
of the stream$stream$. If the$mode$parameter has a positive value the streams
|
|
get wide oriented, for negative values narrow oriented. It is not possible
|
|
to overwrite previous orientations with$fwide()$. I.e., if the stream$stream$
|
|
was already oriented before the call nothing is done.
|
|
|
|
If$mode$is zero the current orientation state is queried and nothing is
|
|
changed.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.24.5 String Utilities *crv-libWCHStrng*
|
|
|
|
|
|
II.24.5.1 Numeric Conversions *crv-libWCHNum*
|
|
------------------------------
|
|
|
|
Quicklink:
|
|
$wcstod()$ Func |crv-wcstod|
|
|
$wcstof()$ Func |crv-wcstof|
|
|
$wcstold()$ Func |crv-wcstold|
|
|
$wcstol()$ Func |crv-wcstol|
|
|
$wcstoll()$ Func |crv-wcstoll|
|
|
$wcstoul()$ Func |crv-wcstoul|
|
|
$wcstoull()$ Func |crv-wcstoull|
|
|
|
|
|
|
|
|
wcstod() Function *crv-wcstod*
|
|
wcstof() Function *crv-wcstof*
|
|
wcstold() Function *crv-wcstold*
|
|
------------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$double wcstod(const wchar_t *restrict string, wchar_t **restrict tailptr);$
|
|
$float wcstof(const wchar_t *string, wchar_t **tailptr);$
|
|
$long double wcstold(const wchar_t *string, wchar_t **tailptr);$
|
|
|
|
Description~
|
|
The$wcstod()$,$wcstof()$, and$wcstol()$functions are equivalent in nearly all
|
|
aspect to the$strtod()$,$strtof()$, and$strtold()$functions but it handles
|
|
wide character string.
|
|
|
|
|
|
|
|
wcstol() Function *crv-wcstol*
|
|
wcstoll() Function *crv-wcstoll*
|
|
wcstoul() Function *crv-wcstoul*
|
|
wcstoull() Function *crv-wcstoull*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$long int wcstol(const wchar_t *restrict string,$
|
|
$wchar_t **restrict tailptr, int base);$
|
|
$long long int wcstoll(const wchar_t *restrict string,$
|
|
$wchar_t **restrict tailptr, int base);$
|
|
$unsigned long int wcstoul(const wchar_t *restrict string,$
|
|
$wchar_t **restrict tailptr, int base);$
|
|
$unsigned long long int wcstoull(const wchar_t *restrict string,$
|
|
$wchar_t **restrict tailptr, int base);$
|
|
|
|
Description~
|
|
The$wcstol()$,$wcstoll()$,$wcstoul()$,$wcstoull()$functions are equivalent in
|
|
nearly all aspectes to$strtol()$,$strstoll()$,$strtoul()$,$strtoull()$
|
|
functions but handels wide character string.
|
|
|
|
|
|
|
|
|
|
II.24.5.2 Copying *crv-libWCHCopy*
|
|
------------------
|
|
|
|
Quicklink:
|
|
$wcscpy()$ Func |crv-wcscpy|
|
|
$wcsncpy()$ Func |crv-wcsncpy|
|
|
$wmemcpy()$ Func |crv-wmemcpy|
|
|
$wmemmove()$ Func |crv-wmemmove|
|
|
|
|
|
|
wcscpy() Function *crv-wcscpy*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$wchar_t *wcscpy(wchar_t *restrict wto, const wchar_t *restrict wfrom);$
|
|
|
|
Return~
|
|
value is the value of$wto$
|
|
|
|
Description~
|
|
This copies wide characters from the string$wfrom$(up to and including the
|
|
terminating null wide character) into the string$wto$. Like$wmemcpy()$, this
|
|
function has undefined results if the strings overlap.
|
|
|
|
|
|
|
|
wcsncpy() Function *crv-wcsncpy*
|
|
------------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$wchar_t *wcsncpy(wchar_t *restrict wto, const wchar_t *restrict wfrom,$
|
|
$size_t size);$
|
|
|
|
Return~
|
|
value is the value of$wto$
|
|
|
|
Description~
|
|
This function is similar to$wcscpy()$but always copies exactly$size$wide
|
|
characters into$wto$.
|
|
|
|
If the length of$wfrom$is more than$size$, then$wcsncpy()$copies just the
|
|
first$size$wide characters. Note that in this case there is no null
|
|
terminator written into$wto$.
|
|
|
|
If the length of$wfrom$is less than$size$, then$wcsncpy()$copies all of
|
|
$wfrom$, followed by enough null wide characters to add up to$size$wide
|
|
characters in all.
|
|
|
|
The behavior of$wcsncpy()$is undefined if the strings overlap.
|
|
|
|
|
|
|
|
wmemcpy() Function *crv-wmemcpy*
|
|
------------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$wchar_t *wmemcpy(wchar_t *restrict wto, const wchar_t *restruct wfrom,$
|
|
$size_t size);$
|
|
|
|
Return~
|
|
value is the value of$wto$
|
|
|
|
Description~
|
|
The$wmemcpy()$function copies$size$wide characters from the object beginning
|
|
at$wfrom$into the object beginning at$wto$. The behavior of this function is
|
|
undefined if the two arrays$wto$and$wfrom$overlap; use$wmemmove()$instead if
|
|
overlapping is possible.
|
|
|
|
|
|
|
|
wmemmove() Function *crv-wmemmove*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$wchar_t *wmemmove(wchar *wto, const wchar_t *wfrom, size_t size);$
|
|
|
|
Return~
|
|
value is the value of$wto$
|
|
|
|
Description~
|
|
This function copies the$size$wide characters at$wfrom$into the$size$wide
|
|
characters at$wto$, even if those two blocks of space overlap. In the case of
|
|
overlap,$memmove()$is careful to copy the original values of the wide
|
|
characters in the block at$wfrom$, including those wide characters which also
|
|
belong to the block at$wto$.
|
|
|
|
|
|
|
|
|
|
II.24.5.3 Concatenation *crv-libWCHConcat*
|
|
------------------------
|
|
|
|
Quicklink:
|
|
$wcscat()$ Func |crv-wcscat|
|
|
$wcsncat()$ Func |crv-wcsncat|
|
|
|
|
|
|
wcscat() Function *crv-wcscat*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$wchar_t *wcscat(wchar_t *restrict wto, const wchar_t *restrict wfrom);$
|
|
|
|
Return~
|
|
value is the value of$wto$
|
|
|
|
Description~
|
|
The$wcscat()$function is similar to$wcscpy()$, except that the characters
|
|
fromw$from$are concatenated or appended to the end of$wto$, instead of
|
|
overwriting it. That is, the first character from$wfrom$overwrites the null
|
|
character marking the end of$wto$.
|
|
|
|
|
|
|
|
wcsncat() Function *crv-wcsncat*
|
|
------------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$wchar_t *wcsncat(wchar_t *restrict wto, const wchar_t *restrict wfrom,$
|
|
$size_t size);$
|
|
|
|
Return~
|
|
value is the value of$wto$
|
|
|
|
Description~
|
|
This function is like$wcscat()$except that not more than$size$characters
|
|
from$from$are appended to the end of$wto$. A single null character is also
|
|
always appended to$wto$, so the total allocated size of$wto$ must be at least
|
|
$size + 1$bytes longer than its initial length.
|
|
|
|
|
|
|
|
|
|
II.24.5.4 Comparison *crv-libWCHCmp*
|
|
---------------------
|
|
|
|
Quicklink:
|
|
$wcscmp()$ Func |crv-wcscmp|
|
|
$wcscoll()$ Func |crv-wcscoll|
|
|
$wcsncmp()$ Func |crv-wcsncmp|
|
|
$wcsxfrm()$ Func |crv-wcsxfrm|
|
|
$wmemcmp()$ Func |crv-wmemcmp|
|
|
|
|
|
|
|
|
wcscmp() Function *crv-wcscmp*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$int wcscmp(const wchar_t *ws1, const wchar_t *ws2);$
|
|
|
|
Return~
|
|
The value returned is greater than, equal to, or less than zero, accordingly
|
|
as the string pointed to by$ws1$is greater than, equal to, or less than the
|
|
string pointed to by$ws2$.
|
|
|
|
A consequence of the ordering used by$wcscmp()$is that if$ws1$is an initial
|
|
substring of$ws2$, then$ws1$is considered to be "less than"$ws2$.
|
|
|
|
Description~
|
|
The$wcscmp()$function compares the wide character string$ws1$against$ws2$.
|
|
|
|
|
|
|
|
wcscoll() Function *crv-wcscoll*
|
|
------------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$int wcscoll(const wchar_t *ws1, const wchar_t *ws2);$
|
|
|
|
Return~
|
|
The value returned is greater than, equal to, or less than zero, accordingly
|
|
as the string pointed to by$ws1$is greater than, equal to, or less than the
|
|
string pointed to by$ws2$.
|
|
|
|
Description~
|
|
The$wcscoll()$function is similar to$wcscmp()$but uses the collating sequence
|
|
of the current locale for collation (the$LC_COLLATE$locale).
|
|
|
|
|
|
|
|
wcsncmp() Function *crv-wcsncmp*
|
|
------------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t size);$
|
|
|
|
Return~
|
|
The value returned is greater than, equal to, or less than zero, accordingly
|
|
as the string pointed to by$ws1$is greater than, equal to, or less than the
|
|
string pointed to by$ws2$.
|
|
|
|
Description~
|
|
This function is the similar to$wcscmp()$, except that no more than$size$wide
|
|
characters are compared. In other words, if the two strings are the same in
|
|
their first$size$wide characters, the return value is zero.
|
|
|
|
|
|
|
|
wcsxfrm() Function *crv-wcsxfrm*
|
|
------------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$size_t wcsxfrm(wchar_t *restrict wto, const wchar_t *wfrom, size_t size);$
|
|
|
|
Description~
|
|
This function is the similar to$strxfrm()$but handles wide characters.
|
|
See |crv-libstrxfrm| for further information on$strxfrm()$.
|
|
|
|
|
|
|
|
wmemcmp() Function *crv-wmemcmp*
|
|
------------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$int wmemcmp(const wchar_t *a1, const wchar_t *a2, size_t size);$
|
|
|
|
Return~
|
|
The value returned is greater than, equal to, or less than zero, accordingly
|
|
as the string pointed to by$a1$is greater than, equal to, or less than the
|
|
string pointed to by$a2$.
|
|
|
|
Description~
|
|
The function$wmemcmp()$compares the$size$wide characters beginning at$a1$
|
|
against the$size$wide characters beginning at$a2$.
|
|
|
|
|
|
|
|
|
|
II.24.5.5 Search *crv-libWCHSearch*
|
|
-----------------
|
|
|
|
Quicklink:
|
|
$wcschr()$ Func |crv-wcschr|
|
|
$wcscspn()$ Func |crv-wcscspn|
|
|
$wcspbrk()$ Func |crv-wcspbrk|
|
|
$wcsrchr()$ Func |crv-wcsrchr|
|
|
$wcsspn()$ Func |crv-wcsspn|
|
|
$wcsstr()$ Func |crv-wcsstr|
|
|
$wcstok()$ Func |crv-wcstok|
|
|
$wmemchr()$ Func |crv-wmemchr|
|
|
|
|
|
|
|
|
wcschr() Function *crv-wcschr*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$wchar_t * wcschr(const wchar_t *wstring, int wc);$
|
|
|
|
Description~
|
|
This function is the similar to$strchr()$but handles wide character.
|
|
|
|
|
|
|
|
wcscspn() Function *crv-wcscspn*
|
|
------------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$size_t wcscspn(const wchar_t *wstring, const wchar_t *stopset);$
|
|
|
|
Description~
|
|
This function is the similar to$strspn()$but handles wide character.
|
|
|
|
|
|
|
|
wcspbrk() Function *crv-wcspbrk*
|
|
------------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$wchar_t *wcspbrk (const wchar_t *wstring, const wchar_t *stopset);$
|
|
|
|
Description~
|
|
This function is the similar to$strpbrk()$but handles wide character.
|
|
|
|
|
|
|
|
wcsrchr() Function *crv-wcsrchr*
|
|
------------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$wchar_t *wcsrchr (const wchar_t *wstring, wchar_t c);$
|
|
|
|
Description~
|
|
This function is the similar to$strrchr()$but handles wide character.
|
|
|
|
|
|
|
|
wcsspn() Function *crv-wcsspn*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$size_t wcsspn(const wchar_t *wstring, const wchar_t *skipset);$
|
|
|
|
Description~
|
|
This function is the similar to$strspn()$but handles wide character.
|
|
|
|
|
|
|
|
wcsstr() Function *crv-wcsstr*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$wchar_t *wcsstr(const wchar_t *haystack, const wchar_t *needle);$
|
|
|
|
Description~
|
|
This function is the similar to$strstr()$but handles wide character.
|
|
|
|
|
|
|
|
wcstok() Function *crv-wcstok*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$wchar_t *wcstok(wchar_t *newstring, const char *delimiters);$
|
|
|
|
Description~
|
|
This function is the similar to$strtok()$but handles wide character.
|
|
|
|
|
|
|
|
wmemchr() Function *crv-wmemchr*
|
|
------------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$wchar_t *wmemchr(const wchar_t *block, wchar_t wc, size_t size);$
|
|
|
|
Description~
|
|
This function is the similar to$memchr()$but handles wide character.
|
|
|
|
|
|
|
|
|
|
II.24.5.6 Miscellaneous *crv-libWCHMisc*
|
|
------------------------
|
|
|
|
Quicklink:
|
|
$wmemset()$ Func |crv-wmemset|
|
|
$wcslen()$ Func |crv-wcslen|
|
|
|
|
|
|
|
|
wcslen() Function *crv-wcslen*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$size_t wcslen(const wchar_t *ws);$
|
|
|
|
Description~
|
|
This function is the similar to$strlen()$but handles wide character.
|
|
|
|
|
|
|
|
wmemset() Function *crv-wmemset*
|
|
------------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$wchar_t *wmemset(wchar_t *block, wchar_t wc, size_t size);$
|
|
|
|
Description~
|
|
This function is the similar to$memset()$but handles wide character.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.24.6 Time Conversions *crv-libWCHTimeConv*
|
|
|
|
Quicklink:
|
|
$wcsftime()$ Func |crv-wcsftime|
|
|
|
|
|
|
|
|
wcsftime() Function *crv-wcsftime*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <time.h>$
|
|
$#include <wchar.h>$
|
|
$size_t wcsftime(wchar_t *s, size_t size, const wchar_t *template,$
|
|
$const struct tm *brokentime);$
|
|
|
|
Description~
|
|
This function is the similar to$strftime()$but handles wide character.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.24.7 Character Conversions *crv-libWCHCharConv*
|
|
|
|
Quicklink:
|
|
$btowc()$ Func |crv-btowc|
|
|
$wctob()$ Func |crv-wctob|
|
|
$mbsinit()$ Func |crv-mbsinit|
|
|
$mbrlen()$ Fucn |crv-mbrlen|
|
|
$mbrtowc()$ Func |crv-mbrtowc|
|
|
$wcrtomb()$ Func |crv-wcrtomb|
|
|
$mbsrtowc()$ Func |crv-mbsrtowc|
|
|
$wcsrtombs()$ Func |crv-wcsrtombs|
|
|
|
|
|
|
|
|
btowc() Function *crv-btowc*
|
|
----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$#include <wchar.h>$
|
|
$wint_t btowc(int c);$
|
|
|
|
Return~
|
|
If ($unsigned char$)$c$is no valid single byte multibyte character or if$c$
|
|
is$EOF$, the function returns$WEOF$. Otherwise the wide character
|
|
representation of$c$is returned.
|
|
|
|
Description~
|
|
The$btowc()$function ("byte to wide character") converts a valid single byte
|
|
character$c$in the initial shift state into the wide character equivalent
|
|
using the conversion rules from the currently selected locale of the$LC_CTYPE$
|
|
category.
|
|
|
|
|
|
|
|
wctob() Function *crv-wctob*
|
|
----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$#include <wchar.h>$
|
|
$int wctob(wint_t c);$
|
|
|
|
Return~
|
|
If the multibyte representation for this character in the initial state is
|
|
exactly one byte long, the return value of this function is this character.
|
|
Otherwise the return value is$EOF$.
|
|
|
|
Description~
|
|
The$wctob()$function ("wide character to byte") takes as the parameter a valid
|
|
wide character.
|
|
|
|
|
|
|
|
mbsinit() Function *crv-mbsinit*
|
|
------------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$int mbsinit(const mbstate_t *ps);$
|
|
|
|
Return~
|
|
If$ps$is a null pointer or the object is in the initial state the return value
|
|
is nonzero. Otherwise it is zero.
|
|
|
|
Description~
|
|
The$mbsinit()$function determines whether the state object pointed to by$ps$is
|
|
in the initial state.
|
|
|
|
|
|
|
|
mbrlen() Fucntion *crv-mbrlen*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$size_t mbrlen(const char *restrict s, size_t n, mbstate_t *ps);$
|
|
|
|
Return~
|
|
see description
|
|
|
|
Description~
|
|
The$mbrlen()$function ("multibyte restartable length") computes the number of
|
|
at most$n$bytes starting at$s$, which form the next valid and complete
|
|
multibyte character.
|
|
|
|
If the next multibyte character corresponds to the NUL wide character, the
|
|
return value is 0. If the next$n$bytes form a valid multibyte character, the
|
|
number of bytes belonging to this multibyte character byte sequence is
|
|
returned.
|
|
|
|
If the the first$n$bytes possibly form a valid multibyte character but the
|
|
character is incomplete, the return value is$(size_t) - 2$. Otherwise the
|
|
multibyte character sequence is invalid and the return value
|
|
is$(size_t) - 1$.
|
|
|
|
The multibyte sequence is interpreted in the state represented by the object
|
|
pointed to by$ps$. If$ps$ is a null pointer, a state object local
|
|
to$mbrlen()$is used.
|
|
|
|
|
|
|
|
mbrtowc() Function *crv-mbrtowc*
|
|
------------------
|
|
Synopsis~
|
|
$#include <wchar.h>$
|
|
$size_t mbrtowc(wchar_t *restrict pwc, const char *restrict s,$
|
|
$size_t n, mbstate_t *restrict ps);$
|
|
|
|
Return~
|
|
see description
|
|
|
|
Description~
|
|
The$mbrtowc()$function ("multibyte restartable to wide character") converts
|
|
the next multibyte character in the string pointed to by$s$into a wide
|
|
character and stores it in the wide character string pointed to by$pwc$. The
|
|
conversion is performed according to the locale currently selected for
|
|
the$LC_CTYPE$category. If the conversion for the character set used in the
|
|
locale requires a state, the multibyte string is interpreted in the state
|
|
represented by the object pointed to by$ps$. If$ps$is a null pointer, a
|
|
static, internal state variable used only by the$mbrtowc()$function is used.
|
|
|
|
If the next multibyte character corresponds to the NUL wide character, the
|
|
return value of the function is 0 and the state object is afterwards in the
|
|
initial state. If the next$n$or fewer bytes form a correct multibyte
|
|
character, the return value is the number of bytes starting from$s$that form
|
|
the multibyte character. The conversion state is updated according to the
|
|
bytes consumed in the conversion. In both cases the wide character (either
|
|
the L'\0' or the one found in the conversion) is stored in the string
|
|
pointed to by$pwc$if$pwc$is not null.
|
|
|
|
If the first$n$bytes of the multibyte string possibly form a valid multibyte
|
|
character but there are more than$n$bytes needed to complete it, the return
|
|
value of the function is$(size_t) - 2$and no value is stored. Please note
|
|
that this can happen even if$n$has a value greater than or equal
|
|
to$MB_CUR_MAX$since the input might contain redundant shift sequences.
|
|
|
|
If the first$n$bytes of the multibyte string cannot possibly form a valid
|
|
multibyte character, no value is stored, the global variable$errno$is set to
|
|
the value$EILSEQ$, and the function returns$(size_t) - 1$. The conversion
|
|
state is afterwards undefined.
|
|
|
|
|
|
|
|
wcrtomb() Function *crv-wcrtomb*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$#include <wchar.h>$
|
|
$size_t wcrtomb(char *restrict s, wchar_t wc, mbstate_t *restrict ps);$
|
|
|
|
Return~
|
|
see description
|
|
|
|
Description~
|
|
The$wcrtomb()$function ("wide character restartable to multibyte") converts a
|
|
single wide character into a multibyte string corresponding to that wide
|
|
character.
|
|
|
|
If$s$is a null pointer, the function resets the state stored in the objects
|
|
pointed to by$ps$(or the internal$mbstate_t$object) to the initial state. This
|
|
can also be achieved by a call like this:
|
|
|
|
$wcrtombs(temp_buf, L'\0', ps)$
|
|
|
|
since, if$s$is a null pointer,$wcrtomb()$performs as if it writes into an
|
|
internal buffer, which is guaranteed to be large enough.
|
|
|
|
If$wc$is the NUL wide character,$wcrtomb()$emits, if necessary, a shift
|
|
sequence to get the state$ps$into the initial state followed by a single
|
|
$NULL$byte, which is stored in the string$s$.
|
|
|
|
Otherwise a byte sequence (possibly including shift sequences) is written into
|
|
the string$s$. This only happens if$wc$is a valid wide character. If$wc$is no
|
|
valid wide character, nothing is stored in the strings$s$,$errno$is set
|
|
to$EILSEQ$, the conversion state in$ps$is undefined and the return value
|
|
is$(size_t) - 1$.
|
|
|
|
If no error occurred the function returns the number of bytes stored in the
|
|
string$s$. This includes all bytes representing shift sequences.
|
|
|
|
|
|
|
|
mbsrtowc() Function *crv-mbsrtowc*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$#include <wchar.h>$
|
|
$size_t mbsrtowcs(wchar_t *restrict dst, const char **restrict src,$
|
|
$size_t len, mbstate_t *restrict ps);$
|
|
|
|
Return~
|
|
see description
|
|
|
|
Description~
|
|
The$mbsrtowcs()$function ("multibyte string restartable to wide character
|
|
string") converts an NUL-terminated multibyte character string at$*src$into an
|
|
equivalent wide character string, including the NUL wide character at the end.
|
|
The conversion is started using the state information from the object pointed
|
|
to by$ps$or from an internal object of$mbsrtowcs()$if$ps$is a null pointer.
|
|
Before returning, the state object is updated to match the state after the
|
|
last converted character. The state is the initial state if the terminating
|
|
NUL byte is reached and converted.
|
|
|
|
If$dst$is not a null pointer, the result is stored in the array pointed to
|
|
by$dst$; otherwise, the conversion result is not available since it is stored
|
|
in an internal buffer.
|
|
|
|
If$len$wide characters are stored in the array$dst$before reaching the end of
|
|
the input string, the conversion stops and$len$is returned. If$dst$is a null
|
|
pointer,$len$is never checked.
|
|
|
|
Another reason for a premature return from the function call is if the input
|
|
string contains an invalid multibyte sequence. In this case the global
|
|
variable$errno$is set to$EILSEQ$and the function returns$(size_t) - 1$.
|
|
|
|
In all other cases the function returns the number of wide characters
|
|
converted during this call. If$dst$is not null,$mbsrtowcs()$stores in the
|
|
pointer pointed to by$src$either a null pointer (if the NUL byte in the
|
|
input string was reached) or the address of the byte following the last
|
|
converted multibyte character.
|
|
|
|
|
|
|
|
wcsrtombs() Function *crv-wcsrtombs*
|
|
--------------------
|
|
Synopsis~
|
|
$#include <stdio.h>$
|
|
$#include <wchar.h>$
|
|
$size_t wcsrtombs(char *restrict dst, const wchar_t **restrict src,$
|
|
$size_t len, mbstate_t *restrict ps);$
|
|
|
|
Return~
|
|
see description
|
|
|
|
Description~
|
|
The$wcsrtombs()$function ("wide character string restartable to multibyte
|
|
string") converts the NUL-terminated wide character string at$*src$ into an
|
|
equivalent multibyte character string and stores the result in the array
|
|
pointed to by$dst$. The NUL wide character is also converted. The conversion
|
|
starts in the state described in the object pointed to by$ps$or by a state
|
|
object locally to$wcsrtombs()$in case$ps$is a null pointer. If$dst$is a
|
|
null pointer, the conversion is performed as usual but the result is not
|
|
available. If all characters of the input string were successfully converted
|
|
and if$dst$is not a null pointer, the pointer pointed to by$src$gets assigned
|
|
a null pointer.
|
|
|
|
If one of the wide characters in the input string has no valid multibyte
|
|
character equivalent, the conversion stops early, sets the global variable
|
|
$errno$to$EILSEQ$, and returns$(size_t) - 1$.
|
|
|
|
Another reason for a premature stop is if$dst$is not a null pointer and the
|
|
next converted character would require more than$len$bytes in total to the
|
|
array$dst$. In this case (and if$dest$is not a null pointer) the pointer
|
|
pointed to by$src$is assigned a value pointing to the wide character right
|
|
after the last one successfully converted.
|
|
|
|
Except in the case of an encoding error the return value of the$wcsrtombs()$
|
|
function is the number of bytes in all the multibyte character sequences
|
|
stored in$dst$. Before returning the state in the object pointed to by$ps$
|
|
(or the internal object in case$ps$is a null pointer) is updated to reflect
|
|
the state after the last conversion. The state is the initial shift state
|
|
in case the terminating NUL wide character was converted.
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
II.25 <wctype.h> Wide Character *crv-libWctypeH*
|
|
|
|
In this section wide character classification and mapping utilities are
|
|
described.
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.25.1 Types *crv-libWTHType*
|
|
|
|
Quicklink:
|
|
$wctrans_t$ Type |crv-wctrans_t|
|
|
$wctype_t$ Type |crv-wctype_t|
|
|
$wint_t$ Type |crv-wint_t|
|
|
|
|
|
|
|
|
wint_t Type *crv-wint_t*
|
|
-----------
|
|
This is a data type used for parameters and variables that contain a single
|
|
wide character.
|
|
Also declared in$<wchar.h>$, see |crv-libwint_t2|.
|
|
|
|
|
|
|
|
wctrans_t Type *crv-wctrans_t*
|
|
--------------
|
|
This data type is defined as a scalar type which can hold a value representing
|
|
the locale-dependent character mapping. There is no way to construct such a
|
|
value apart from using the return value of the$wctrans()$function.
|
|
|
|
|
|
|
|
wctype_t Type *crv-wctype_t*
|
|
-------------
|
|
This type can hold a value which represents a character class. The only
|
|
defined way to generate such a value is by using the$wctype()$function.
|
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.25.2 Macros *crv-libWTHMac*
|
|
|
|
|
|
WEOF Macro *crv-WEOF*
|
|
----------
|
|
This macro expands to an expression of type$wint_t$that is returned by a
|
|
number of wide stream functions to indicate an end-of-file condition, or some
|
|
other error situation.
|
|
Also declared in$<wchar.t>$, see |crv-WEOF2|.
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.25.3 Classification *crv-libWTHClass*
|
|
|
|
|
|
II.25.3.1 Wide Character *crv-libWTHCwide*
|
|
-------------------------
|
|
|
|
Quicklink:
|
|
$iswalnum()$ Func |crv-iswalnum|
|
|
$iswalpha()$ Func |crv-iswalpha|
|
|
$iswblank()$ Func |crv-iswblank|
|
|
$iswcntrl()$ Func |crv-iswcntrl|
|
|
$iswdigit()$ Func |crv-iswdigit|
|
|
$iswgraph()$ Func |crv-iswgraph|
|
|
$iswlower()$ Func |crv-iswlower|
|
|
$iswprint()$ Func |crv-iswprint|
|
|
$iswpunct()$ Func |crv-iswpunct|
|
|
$iswspace()$ Func |crv-iswspace|
|
|
$iswupper()$ Func |crv-iswupper|
|
|
$iswxdigit()$ Func |crv-iswxdigit|
|
|
|
|
|
|
|
|
iswalnum() Function *crv-iswalnum*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <wctype.h>$
|
|
$int iswalnum(wint_t wc);$
|
|
|
|
Description~
|
|
This function returns a nonzero value if$wc$is an alphanumeric character (a
|
|
letter or number); in other words, if either$iswalpha()$or$iswdigit()$is true
|
|
of a character, then$iswalnum()$is also true.
|
|
|
|
|
|
|
|
iswalpha() Function *crv-iswalpha*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <wctype.h>$
|
|
$int iswalpha(wint_t wc);$
|
|
|
|
Description~
|
|
Returns true if$wc$is an alphabetic character (a letter). If$iswlower()$or
|
|
$iswupper()$is true of a character, then$iswalpha()$is also true.
|
|
|
|
|
|
|
|
iswblank() Function *crv-iswblank*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <wctype.h>$
|
|
$int iswblank(wint_t wc);$
|
|
|
|
Description~
|
|
Returns true if$wc$is a blank character; that is, a space or a tab.
|
|
|
|
|
|
|
|
iswcntrl() Function *crv-iswcntrl*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <wctype.h>$
|
|
$int iswcntrl(wint_t wc);$
|
|
|
|
Description~
|
|
Returns true if$wc$is a control character (that is, a character that is not a
|
|
printing character).
|
|
|
|
|
|
|
|
iswdigit() Function *crv-iswdigit*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <wctype.h>$
|
|
$int iswdigit(wint_t wc);$
|
|
|
|
Description~
|
|
Returns true if$wc$is a digit (e.g., 0 through 9). Please note that this
|
|
function does not only return a nonzero value for decimal digits, but for
|
|
all kinds of digits.
|
|
|
|
|
|
|
|
iswgraph() Function *crv-iswgraph*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <wctype.h>$
|
|
$int iswgraph(wint_t wc);$
|
|
|
|
Description~
|
|
Returns true if$wc$is a graphic character; that is, a character that has a
|
|
glyph associated with it. The whitespace characters are not considered
|
|
graphic.
|
|
In other words: returns true if$iswprint()$is true and if$iswspace()$is false.
|
|
|
|
|
|
|
|
iswlower() Function *crv-iswlower*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <wctype.h>$
|
|
$int iswlower(wint_t wc);$
|
|
|
|
Description~
|
|
Returns true if$wc$is a lower-case letter.
|
|
|
|
|
|
|
|
iswprint() Function *crv-iswprint*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <wctype.h>$
|
|
$int iswprint(wint_t wc);$
|
|
|
|
Description~
|
|
Returns true if$wc$is a printing character. Printing characters include all
|
|
the graphic characters, plus the space (" ") character.
|
|
|
|
|
|
|
|
iswpunct() Function *crv-iswpunct*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <wctype.h>$
|
|
$int iswpunct(wint_t wc);$
|
|
|
|
Description~
|
|
Returns true if$wc$is a punctuation character. This means any printing
|
|
character that is not alphanumeric or a space character.
|
|
|
|
|
|
|
|
iswspace() Function *crv-iswspace*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <wctype.h>$
|
|
$int iswspace(wint_t wc);$
|
|
|
|
Description~
|
|
Returns true if$wc$is a whitespace character. In the standard "C" locale,
|
|
$iswspace()$returns true for only the standard whitespace characters:
|
|
|
|
$L' '$ space
|
|
$L'\f'$ formfeed
|
|
$L'\n'$ newline
|
|
$L'\r'$ carriage return
|
|
$L'\t'$ horizontal tab
|
|
$L'\v'$ vertical tab
|
|
|
|
|
|
|
|
iswupper() Function *crv-iswupper*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <wctype.h>$
|
|
$int iswupper(wint_t wc);$
|
|
|
|
Description~
|
|
Returns true if$wc$is an upper-case letter.
|
|
|
|
|
|
|
|
iswxdigit() Function *crv-iswxdigit*
|
|
--------------------
|
|
Synopsis~
|
|
$#include <wctype.h>$
|
|
$int iswxdigit(wint_t wc);$
|
|
|
|
Description~
|
|
Returns true if$wc$is a hexadecimal digit. Hexadecimal digits include the
|
|
normal decimal digits 0 through 9 and the letters A through F and a through f.
|
|
|
|
|
|
|
|
|
|
|
|
II.25.3.2 Extensible Wide Char *crv-libWTHCextens*
|
|
-------------------------------
|
|
|
|
Quicklink:
|
|
$iswctype()$ Func |crv-iswctype|
|
|
$wctype()$ Func |crv-wctype|
|
|
|
|
|
|
iswctype() Function *crv-iswctype*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <wctype.h>$
|
|
$int iswctype(wint_t wc, wctype_t desc);$
|
|
|
|
Description~
|
|
This function returns a nonzero value if$wc$is in the character class
|
|
specified by$desc$.$desc$must previously be returned by a successful call
|
|
to$wctype()$.
|
|
|
|
|
|
|
|
wctype() Function *crv-wctype*
|
|
-----------------
|
|
Synopsis~
|
|
$#include <wctype.h>$
|
|
$wctype_t wctype(const char *property);$
|
|
|
|
Description~
|
|
The$wctype()$returns a value representing a class of wide characters which is
|
|
identified by the string$property$. Beside some standard properties each
|
|
locale can define its own ones. In case no$property$with the given name is
|
|
known for the current locale selected for the$LC_CTYPE$category, the function
|
|
returns zero.
|
|
|
|
The properties known in every locale are:
|
|
$"alnum"$
|
|
$"alpha"$
|
|
$"cntrl"$
|
|
$"digit"$
|
|
$"graph"$
|
|
$"lower"$
|
|
$"print"$
|
|
$"punct"$
|
|
$"space"$
|
|
$"upper"$
|
|
$"xdigit"$
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
II.25.4 Mapping *crv-libWTHMap*
|
|
|
|
|
|
II.25.4.1 Wide Character *crv-libWTHMwide*
|
|
-------------------------
|
|
|
|
Quicklink:
|
|
$towlower()$ Func |crv-towlower|
|
|
$towupper()$ Func |crv-towupper|
|
|
|
|
|
|
|
|
towlower() Function *crv-towlower*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <wctype.h>$
|
|
$wint_t towlower(wint_t wc);$
|
|
|
|
Return~
|
|
lower-case letter
|
|
|
|
Description~
|
|
If$wc$is an upper-case letter,$towlower()$returns the corresponding lower-case
|
|
letter. Otherwise$wc$is returned unchanged.
|
|
|
|
|
|
|
|
towupper() Function *crv-towupper*
|
|
-------------------
|
|
Synopsis~
|
|
$#include <wctype.h>$
|
|
$wint_t towupper(wint_t wc);$
|
|
|
|
Return~
|
|
upper-case letter
|
|
|
|
Description~
|
|
If$wc$is a lower-case letter,$towupper()$returns the corresponding upper-case
|
|
letter. Otherwise$wc$is returned unchanged.
|
|
|
|
|
|
|
|
|
|
II.25.4.2 Extensible Wide Char *crv-libWTHMextens*
|
|
-------------------------------
|
|
|
|
Quicklink:
|
|
$towctrans()$ Func |crv-towctrans|
|
|
$wctrans()$ Func |crv-wctrans|
|
|
|
|
|
|
|
|
towctrans() Function *crv-towctrans*
|
|
--------------------
|
|
Synopsis~
|
|
$#include <wctype.h>$
|
|
$wint_t towctrans(wint_t wc, wctrans_t desc);$
|
|
|
|
Return~
|
|
mapped value of$wc$
|
|
|
|
Description~
|
|
This function maps the input character$wc$according to the rules of the
|
|
mapping for which$desc$is a descriptor, and returns the value it finds.$desc$
|
|
must be obtained by a successful call to$wctrans()$.
|
|
|
|
|
|
|
|
wctrans() Function *crv-wctrans*
|
|
------------------
|
|
Synopsis~
|
|
$#include <wctype.h>$
|
|
$wctrans_t wctrans(const char *property);$
|
|
|
|
Return~
|
|
0: mapping unknown
|
|
else: mapping known
|
|
|
|
Description~
|
|
This function has to be used to find out whether a named mapping is defined in
|
|
the current locale selected for the$LC_CTYPE$category. If the returned value
|
|
is non-zero, it can be used afterwards in calls to$towctrans()$. If the return
|
|
value is zero no such mapping is known in the current locale.
|
|
|
|
Beside locale-specific mappings there are two mappings which are guaranteed
|
|
to be available in every locale:
|
|
$"tolower"$
|
|
$"toupper"$
|
|
|
|
|
|
|
|
|
|
==============================================================================
|
|
Appendix A GLOSSARY *crv-glossary*
|
|
|
|
|
|
*crv-gloAlignment*
|
|
Alignment Requirement that objects of a particular type be located on
|
|
storage boundaries with addresses that are particular
|
|
multiples of a byte address.
|
|
|
|
*crv-gloArgument*
|
|
Argument An argument is an expression in a comma-separated list bounded
|
|
by parentheses in a function call or macro invocation.
|
|
|
|
*crv-gloArray*
|
|
Array Set of elements that have the same data type.
|
|
|
|
*crv-gloBinary*
|
|
Binary see Operator |crv-gloOperator|
|
|
|
|
*crv-gloBlock*
|
|
Block C statements enclosed within braces ({...})
|
|
|
|
*crv-gloCompState*
|
|
Compound A compound statement is a block (see |crv-gloBlock|)
|
|
Statement
|
|
*crv-gloDataType*
|
|
Data Type see Type |crv-gloType|
|
|
|
|
*crv-gloDeclaration*
|
|
Declaration A C construct that associates the attributes of a variable,
|
|
type or function with a name. A declaration does not need
|
|
memory, opposed to a definition (-> Definition).
|
|
|
|
Example:
|
|
>
|
|
struct MeasVar {
|
|
int nCntr;
|
|
int nNumOfCycles;
|
|
float fResult;
|
|
};
|
|
<
|
|
*crv-gloDefinition*
|
|
Definition A C construct that specifies the name, formal parameters, body
|
|
and return type of a function or that initializes and allocates
|
|
storage for a variable. A definition needs memory, opposed
|
|
to a declaration (-> Declaration).
|
|
|
|
Example:
|
|
>
|
|
struct MeasVar mv;
|
|
<
|
|
*crv-gloExpression*
|
|
Expression An expression is a sequence of operators and operands that
|
|
specifies computation of a value or that designates an object
|
|
or function.
|
|
See |crv-gloOperand|, |crv-gloOperator|
|
|
|
|
|
|
False / True see |crv-gloTrueFalse|
|
|
|
|
*crv-gloIdentifier*
|
|
Identifier An identifier is a name of a variable, function, macro...
|
|
Valid identifiers consists of uppercase and lowercase Latin
|
|
letters [a-z], [A-Z] and digits [0-9] and the underscore _.
|
|
They must start with a letter or underscore and must be
|
|
different to keywords.
|
|
|
|
*crv-gloLifetime*
|
|
Lifetime The lifetime of a variable is the portion of program execution
|
|
during which storage is guaranteed to be reserved for it.
|
|
Throughout its lifetime a variable exists, has a fix address
|
|
and retains its last assigned value.
|
|
|
|
*crv-gloLinkage*
|
|
Linkage Linkage is used to extend the scope of a variable or function
|
|
to the actual context. The keyword$extern$is used for that.
|
|
|
|
*crv-gloLvalue*
|
|
lvalue A lvalue is an epxression that describes the location of an
|
|
object. The location is the object's lvalue. The object's rvalue
|
|
is the value stored at the location described by the lvalue.
|
|
|
|
*crv-gloLvalueMod*
|
|
lvalue, A modifiable lvalue is an expression representing an object that
|
|
modifialbe can be changed.
|
|
A lvalue is a modifiable lvalue if:
|
|
- it has no array type
|
|
- it has no incomplete type
|
|
- it has no$const$type
|
|
- it has struct or union type and no$const$member
|
|
|
|
*crv-gloMacro*
|
|
Macro An identifier that is equated to a text or symbolic expression
|
|
to which it is to be expanded by the preprocessor.
|
|
|
|
*crv-gloObject*
|
|
Object An area of memory used by a variable, the contents represents
|
|
values.
|
|
|
|
*crv-gloOperand*
|
|
Operand Parameter of an operator.
|
|
Example:
|
|
$a = b * c$
|
|
|
|
$*$is the operator, $a$and$b$are the operands
|
|
$b * c$is an expression
|
|
|
|
*crv-gloOperator*
|
|
Operator An operator is used with operands to build an expression.
|
|
Example:
|
|
$a = b * c$
|
|
|
|
$*$is the operator, $a$and$b$are the operands
|
|
$b * c$is an expression
|
|
|
|
An operator with two operands is called binary *crv-gloOpBinary*
|
|
e.g. *, /, +, ...
|
|
An operator with one operand is called unary. *crv-gloOpUnary*
|
|
e.g. - (sign), ++, --, ....
|
|
|
|
*crv-gloParameter*
|
|
Parameter A parameter is the value that is passed to a function or macro.
|
|
In principle there are two ways parameters can be passed:
|
|
- By Value
|
|
This means that the function/macro works with a copy of
|
|
the parameter. Thus the value of the parameter can be
|
|
changed within the function/macro, but from caller's
|
|
view the parameter will keep its original value.
|
|
- By Reference
|
|
This means that the function/macro works with the
|
|
original parameter. Thus a caller of a function/macro
|
|
will "see" changes done to the parameter within
|
|
the function/macro.
|
|
C always uses pass by value. Use pointers to simulate a pass
|
|
by reference.
|
|
|
|
*crv-gloPointer*
|
|
Pointer A variable that contains the address of a C element (variable,
|
|
structure, function) or memory area.
|
|
|
|
*crv-gloPreprocessor*
|
|
Preprocessor A preprocessor is the first pass of a compiler. It does:
|
|
- read include files
|
|
- expand macros
|
|
- replace defines by their contents
|
|
- pass control directives to the compiler
|
|
|
|
*crv-gloPromote*
|
|
Promote Promoting is a type cast from a "lower" type to a "higher"
|
|
type, e.g. from int to long.
|
|
|
|
*crv-gloPrototype*
|
|
Prototype A function prototype is a declaration of a function that declares
|
|
the types of its parameters.
|
|
|
|
*crv-gloRvalue*
|
|
rvalue A rvalue is the value of an expression.
|
|
See also lvalue |crv-gloLvalue|.
|
|
|
|
*crv-gloScope*
|
|
Scope Scope is the visibility of a C element (variable, function)
|
|
within a program. The scope are the sections of a program where
|
|
an element can be referenced by name. The scope of an element
|
|
may be limited to file, function or block.
|
|
The scope of an element is determined from where it is defined.
|
|
If it is defined outside of a block, it has file scope.
|
|
If it is defined within a function prototype, it has function
|
|
scope.
|
|
If it is defined within a block, it has block scope.
|
|
|
|
*crv-gloSemantics*
|
|
Semantics The relationships between symbols and their meanings.
|
|
|
|
*crv-gloSideEffect*
|
|
Side-Effect During evaluation of an expression the value of a variable is
|
|
changed. Example:
|
|
>
|
|
b = (a = 2) * (a *= 3)
|
|
<
|
|
NOTE: To keep a program maintainable and readable don't use
|
|
side-effects.
|
|
|
|
*crv-gloSignExtension*
|
|
Sign- Sign-extension is the filling of the left most bits with the
|
|
Extension state of the sign-bit when shifting right or when promoting.
|
|
|
|
*crv-gloStatement*
|
|
Statement A statement is an expression followed by a semicolon.
|
|
see |crv-gloExpression|
|
|
|
|
*crv-gloStructure*
|
|
Structure A set of elements that have possibly different data types. A
|
|
structure groups them together.
|
|
|
|
*crv-gloSyntax*
|
|
Syntax A syntax describes the structure and order of the elements
|
|
of a language statement. In other words: it specifies how words
|
|
and symbols are put together to form a program.
|
|
|
|
Example for Syntax versus Semantics:
|
|
The syntax rules of a human language could be:
|
|
- each word must be build with the characters a-z or A-Z
|
|
- words are separated by at least one space (" ").
|
|
- words must start either with an upper or lower character,
|
|
the following characters must be lower ones
|
|
- a sentence consists of words
|
|
- the first word of a sentence must start with an upper
|
|
character, the others with a lower one
|
|
- a sentence ends with a point (.)
|
|
|
|
Following these rules, this would be a valid sentence:
|
|
"The weather is fine today."
|
|
|
|
But this one would also be a syntactically correct
|
|
sentence:
|
|
"Thkds sdfasd ksdf dsf dfklsflsd."
|
|
|
|
The semantics of a language connects words with meanings.
|
|
Thus the second sentence is a semantically incorrect sentence.
|
|
|
|
So a language is defined by its semantics AND syntax.
|
|
The syntax defines how to form words and the semantics gives
|
|
words a meaning.
|
|
|
|
*crv-gloToken*
|
|
Token Tokens are the minimal lexical elements of a programming
|
|
language. A token can be a keyword, an identifier, a constant,
|
|
a string literal, an operator or a punctuator.
|
|
|
|
*crv-gloTrueFalse*
|
|
True / False In standard C an expression is FALSE if its value is 0, else
|
|
it is TRUE. The value of a logical TRUE is implementation
|
|
specific.
|
|
So never do something like
|
|
$if (IsWindowOpen() == TRUE)$
|
|
instead of this do
|
|
$if (IsWindowOpen())$
|
|
or
|
|
$if (IsWindowOpen() != FALSE)$
|
|
|
|
*crv-gloType*
|
|
Type The meaning of a value stored in an object or returned by a
|
|
function is determined by its type.
|
|
|
|
*crv-gloTypeIncomplete*
|
|
Type, An incomplete type describes an object but lacks information to
|
|
incomplete determine its size.
|
|
E.g. an array type of unknown size is an incomplete type.
|
|
|
|
*crv-gloTypeCast*
|
|
Type Cast A type cast is an operation in which an operand of one type is
|
|
converted to another type. In C the cast operator
|
|
is$(type-name)$.
|
|
Example:
|
|
>
|
|
int main(void)
|
|
{
|
|
int nVar = 42;
|
|
float fVar;
|
|
|
|
fVar = (float)nVar;
|
|
}
|
|
<
|
|
*crv-gloUnary*
|
|
Unary see Operator |crv-gloOperator|
|
|
|
|
*crv-gloVariable*
|
|
Variable Is the symbolic representation of a memory area.
|
|
|
|
*crv-gloWhiteSpace*
|
|
White-Space A space, tab, carriage return, new line, vertical tab, or
|
|
formfeed character.
|
|
|
|
|
|
|
|
==============================================================================
|
|
Appendix B BIBLIOGRAPHY *crv-bibliography*
|
|
|
|
[1] "Erfolgreich programmieren mit C", 1. Auflage, 1985
|
|
J. Anton Illik
|
|
SYBEX Verlag GmbH, Duesseldorf (Germany)
|
|
|
|
[2] "Softwareentwicklung in C", 3. September 2001
|
|
Klaus Schmaranz
|
|
Springer Verlag
|
|
|
|
[3] "The GNU C Library Reference Manual", for Version 2.2.x of the GNU C
|
|
Library, Edition 0.10, last updated 2001-07-06
|
|
Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002
|
|
Free Software Foundation, Inc.
|
|
|
|
[4] ISO/IEC 9899:1999(E)
|
|
International Standard
|
|
Programming languages - C
|
|
Published by American National Standards Institute
|
|
|
|
|
|
|
|
==============================================================================
|
|
For Appendix C COPYRIGHT & LICENSES go to |crvdoc-copyright|
|
|
|
|
|
|
==============================================================================
|
|
For Appendix D AUTHOR go to |crvdoc-author|
|
|
|
|
|
|
==============================================================================
|
|
For Appendix E CREDITS go to |crvdoc-credits|
|
|
|
|
|
|
==============================================================================
|
|
For Appendix F HISTORY go to |crvdoc-history|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
vim:tw=78:ts=4:ft=help:norl:
|