Rewrite of C9x Subclause 7.4 <inttypes.h> September 26, 1997 Document No. WG14/N761 (J11/97-125) Douglas A. Gwyn US Army Research Laboratory Adelphi, MD ABSTRACT This is a proposed replacement for the current C9x (Draft 10) subclause 7.4; it supersedes Doc. No. WG14/N737 (J11/97-100), which was distributed in the post-London mailing. (Actually, that mailing contained the wrong version; in the SC22WG14 mailing list, I asked that it be replaced by the version in ftp:://ftp.arl.mil/arch/n737.ps.) Since my original proposal, I have received much useful feedback, which has been taken into account. In the course of this work, I noticed several apparent problems with the specification. In fixing these problems, there is a delicate balance between the force of logical necessity and invention. Vertical bars in the margin indicate innovations that I have identified as potentially controversial, or wording that could be affected by other pending proposals; I have isolated these so that if any of them is modified or rejected by the Committee, it can be quickly and accurately edited in the TROFF source file that will be provided to the Document Editor as a ``plug-in'' replacement for the old subclause 7.4. 7.4 Integer types <lt;lt;lt;inttypes.h> The header <inttypes.h> declares sets of typedef names for integer types having specified widths and defines corresponding sets of macros. Typedef names are declared in the following categories: - integer types having certain exact widths; - integer types having at least certain specified widths; - fastest integer types having at least certain specified widths; Library 149 Document No. WG14/N761 (J11/97-125)Rewrite of <inttypes.h>September 26, 1997 - fastest integer types with unspecified width; - integer types large enough to hold pointers to objects; - integer types having greatest width. (Some of these typedef names may denote the same type.) Corresponding macros specify limits of the declared integer types, construct suitable character constants, and provide conversion specifiers for use with the formatted input/output functions. There are also four function-like macros for converting numeric character strings to greatest-width integers. For each typedef name described herein that can be declared | as a type existing in the implementation, <inttypes.h> shall | declare that typedef name, and it shall define the | associated macros. Conversely, for each typedef name | described herein that cannot be declared as a type existing in the implementation, <inttypes.h> shall not declare that typedef name, nor shall it define the associated macros. Throughout this subclause, the width of an integer type is | defined as the number of significant bits, including sign if | any, in the representation of that type. | Recommended practice Some of these typedef names may denote implementation- defined extended integer types. 7.4.1 Typedef names for integer types When typedef names differing only in the absence or presence of the initial u are declared, they shall denote corresponding signed and unsigned types as described in subclause 6.1.2.5. 7.4.1.1 Exact-width integer types Each of the following names designates an integer type that has exactly the specified width. These names have the general form of intn_t or uintn_t where n is the required width. For example, uint8_t denotes an unsigned integer type that is exactly 8 bits wide. The following designate exact-width signed integer types: int8_t int16_t int32_t int64_t 150 Library September 26, 1997Rewrite of <inttypes.h>Document No. WG14/N761 (J11/97-125) The following designate exact-width unsigned integer types: uint8_t uint16_t uint32_t uint64_t (Any of these types might not exist.) 7.4.1.2 Minimum-width integer types Each of the following names designates an integer type that has at least the specified width. These names have the general form of int_leastn_t or uint_leastn_t where n is the minimum required width. For example, int_least32_t denotes a signed integer type that is at least 32 bits wide. The following designate minimum-width signed integer types: int_least8_t int_least16_t int_least32_t int_least64_t The following designate minimum-width unsigned integer types: uint_least8_t uint_least16_t uint_least32_t uint_least64_t (These types must exist.) Recommended practice | Each of these names should denote one of the smallest types | satisfying the requirements. | 7.4.1.3 Fastest minimum-width integer types Each of the following names designates an integer type that is usually fastest to operate with among all integer types that have at least the specified width. These names have the general form of int_fastn_t or uint_fastn_t where n is the minimum required width. For example, int_fast16_t denotes the fastest signed integer type that is at least 16 bits wide. The following designate fastest minimum-width signed integer types: int_fast8_t int_fast16_t int_fast32_t int_fast64_t The following designate fastest minimum-width unsigned integer types: uint_fast8_t uint_fast16_t uint_fast32_t uint_fast64_t (These types must exist.) | Library 151 Document No. WG14/N761 (J11/97-125)Rewrite of <inttypes.h>September 26, 1997 Recommended practice | It is acknowledged that singling out one type as ``usually | fastest'' can be problematic. If the implementation has no | clear grounds for choosing one type over another, it may | pick any integer type satisfying the signedness and width | requirements. | 7.4.1.4 Fastest integer types The following name designates a signed integer type that is usually fastest among all signed integer types having widths of at least 16 bits: intfast_t It denotes the same type as int_fast16_t. | The following name designates an unsigned integer type that is usually fastest among all unsigned integer types having widths of at least 16 bits: uintfast_t It denotes the same type as uint_fast16_t. | (These types must exist.) | 7.4.1.5 Integer types capable of holding object pointers The following name designates a signed integer type with the property that any valid pointer to void can be converted to this type, then converted back to pointer to void, and the result will compare equal to the original pointer: intptr_t The following name designates an unsigned integer type with the property that any valid pointer to void can be converted to this type, then converted back to pointer to void, and the result will compare equal to the original pointer: uintptr_t (Support for such conversions is a common extension; | however, either or both of these types might not exist.) | 7.4.1.6 Greatest-width integer types The following name designates a signed integer type capable of holding any value that can be represented by any signed integer type: intmax_t The following name designates an unsigned integer type capable of holding any value that can be represented by any unsigned integer type: 152 Library September 26, 1997Rewrite of <inttypes.h>Document No. WG14/N761 (J11/97-125) uintmax_t (These types must exist.) | 7.4.2 Limits of integer types The following object-like macros specify the minimum and maximum limits of the integer types declared in <inttypes.h>. Each macro name corresponds to a similar typedef name in subclause 7.4.1. Each instance of any defined macro shall be replaced by a constant expression suitable for use in #if preprocessing directives, and this expression shall have the same type as would an expression that is an object of the corresponding type converted according to the integer promotions. Its implementation-defined value shall be equal to or greater in magnitude (absolute value) than the corresponding value given below, with the same sign. 7.4.2.1 Limits of exact-width integer types - minimum values of exact-width signed integer types INT8_MIN -127 INT16_MIN -32767 INT32_MIN -2147483647 INT64_MIN -9223372036854775807 (The value must be either -2n-1 or 1-2n-1.) - maximum values of exact-width signed integer types INT8_MAX +127 INT16_MAX +32767 INT32_MAX +2147483647 INT64_MAX +9223372036854775807 (The value must be 2n-1-1.) - maximum values of exact-width unsigned integer types UINT8_MAX 255 UINT16_MAX 65535 UINT32_MAX 4294967295 UINT64_MAX 18446744073709551615 (The value must be 2n-1.) 7.4.2.2 Limits of minimum-width integer types - minimum values of minimum-width signed integer types INT_LEAST8_MIN -127 INT_LEAST16_MIN -32767 INT_LEAST32_MIN -2147483647 INT_LEAST64_MIN -9223372036854775807 Library 153 Document No. WG14/N761 (J11/97-125)Rewrite of <inttypes.h>September 26, 1997 - maximum values of minimum-width signed integer types INT_LEAST8_MAX +127 INT_LEAST16_MAX +32767 INT_LEAST32_MAX +2147483647 INT_LEAST64_MAX +9223372036854775807 - maximum values of minimum-width unsigned integer types UINT_LEAST8_MAX 255 UINT_LEAST16_MAX 65535 UINT_LEAST32_MAX 4294967295 UINT_LEAST64_MAX 18446744073709551615 7.4.2.3 Limits of fastest minimum-width integer types - minimum values of fastest minimum-width signed integer types INT_FAST8_MIN -127 INT_FAST16_MIN -32767 INT_FAST32_MIN -2147483647 INT_FAST64_MIN -9223372036854775807 - maximum values of fastest minimum-width signed integer types INT_FAST8_MAX +127 INT_FAST16_MAX +32767 INT_FAST32_MAX +2147483647 INT_FAST64_MAX +9223372036854775807 - maximum values of fastest minimum-width unsigned integer types UINT_FAST8_MAX 255 UINT_FAST16_MAX 65535 UINT_FAST32_MAX 4294967295 UINT_FAST64_MAX 18446744073709551615 7.4.2.4 Limits of fastest integer types - minimum value of fastest signed integer type INTFAST_MIN -32767 - maximum value of fastest signed integer type INTFAST_MAX +32767 - maximum value of fastest unsigned integer type UINTFAST_MAX 65535 154 Library September 26, 1997Rewrite of <inttypes.h>Document No. WG14/N761 (J11/97-125) 7.4.2.5 Limits of integer types capable of holding object pointers - minimum value of pointer-holding signed integer type INTPTR_MIN -32767 - maximum value of pointer-holding signed integer type INTPTR_MAX +32767 - maximum value of pointer-holding unsigned integer type UINTPTR_MAX 65535 7.4.2.6 Limits of greatest-width integer types - minimum value of greatest-width signed integer type INTMAX_MIN -9223372036854775807 - maximum value of greatest-width signed integer type INTMAX_MAX +9223372036854775807 - maximum value of greatest-width unsigned integer type UINTMAX_MAX 18446744073709551615 7.4.3 Macros for integer constants The following function-like macros expand to integer constants suitable for initializing objects that have integer types declared in <inttypes.h>. Each macro name corresponds to a similar typedef name in subclause 7.4.1.2 or 7.4.1.6. The argument in any instance of these macros shall be a decimal, octal, or hexadecimal constant (as defined in subclause 6.1.3.2) with a value that does not exceed the limits for the corresponding type. 7.4.3.1 Macros for minimum-width integer constants Each of the following macros expands to an integer constant having the value specified by its argument and a type with at least the specified width. These names have the general form of INTn_C or UINTn_C where n is the minimum required width. For example, UINT64_C(0x123) might expand to the integer constant 0x123ULL. The following expand to integer constants that have signed integer types: INT8_C(value) INT16_C(value) INT32_C(value) INT64_C(value) Library 155 Document No. WG14/N761 (J11/97-125)Rewrite of <inttypes.h>September 26, 1997 The following expand to integer constants that have unsigned integer types: UINT8_C(value) UINT16_C(value) UINT32_C(value) UINT64_C(value) 7.4.3.2 Macros for greatest-width integer constants The following macro expands to an integer constant having the value specified by its argument and a signed integer type having width at least as great as any other signed integer type: INTMAX_C(value) The following macro expands to an integer constant having the value specified by its argument and an unsigned integer type having width at least as great as any other unsigned integer type: UINTMAX_C(value) 7.4.4 Macros for format specifiers Each of the following object-like macros expands to a string literal containing a conversion specifier, possibly modified by a prefix such as h, l, or ll, suitable for use within the format argument of a formatted input/output function when converting the corresponding integer type. These names have the general form of PRI (character string literals for the fprintf family), SCN (character string literals for the fscanf family),122 WPRI (wide string literals for the | fwprintf family), or WSCN (wide string literals for the | fwscanf family), followed by the conversion specifier, followed by a name corresponding to a similar typedef name in subclause 7.4.1. For example, PRIdFAST32 can be used in a format string to print an integer of type int_fast32_t. The fprintf macros for signed integers are: PRId8 PRId16 PRId32 PRId64 PRIdLEAST8 PRIdLEAST16 PRIdLEAST32 PRIdLEAST64 PRIdFAST8 PRIdFAST16 PRIdFAST32 PRIdFAST64 PRIdFAST PRIdMAX PRIdPTR PRIi8 PRIi16 PRIi32 PRIi64 __________ 122. Separate macros are given for fprintf and fscanf functions because, typically, different format specifiers are required for fprintf and fscanf even when the type is the same. 156 Library September 26, 1997Rewrite of <inttypes.h>Document No. WG14/N761 (J11/97-125) PRIiLEAST8 PRIiLEAST16 PRIiLEAST32 PRIiLEAST64 PRIiFAST8 PRIiFAST16 PRIiFAST32 PRIiFAST64 PRIiFAST PRIiMAX PRIiPTR The fprintf macros for unsigned integers are: PRIo8 PRIo16 PRIo32 PRIo64 PRIoLEAST8 PRIoLEAST16 PRIoLEAST32 PRIoLEAST64 PRIoFAST8 PRIoFAST16 PRIoFAST32 PRIoFAST64 PRIoFAST PRIoMAX PRIoPTR PRIu8 PRIu16 PRIu32 PRIu64 PRIuLEAST8 PRIuLEAST16 PRIuLEAST32 PRIuLEAST64 PRIuFAST8 PRIuFAST16 PRIuFAST32 PRIuFAST64 PRIuFAST PRIuMAX PRIuPTR PRIx8 PRIx16 PRIx32 PRIx64 PRIxLEAST8 PRIxLEAST16 PRIxLEAST32 PRIxLEAST64 PRIxFAST8 PRIxFAST16 PRIxFAST32 PRIxFAST64 PRIxFAST PRIxMAX PRIxPTR PRIX8 PRIX16 PRIX32 PRIX64 PRIXLEAST8 PRIXLEAST16 PRIXLEAST32 PRIXLEAST64 PRIXFAST8 PRIXFAST16 PRIXFAST32 PRIXFAST64 PRIXFAST PRIXMAX PRIXPTR The fscanf macros for signed integers are: SCNd8 SCNd16 SCNd32 SCNd64 SCNdLEAST8 SCNdLEAST16 SCNdLEAST32 SCNdLEAST64 | SCNdFAST8 SCNdFAST16 SCNdFAST32 SCNdFAST64 | SCNdFAST SCNdMAX SCNdPTR SCNi8 SCNi16 SCNi32 SCNi64 SCNiLEAST8 SCNiLEAST16 SCNiLEAST32 SCNiLEAST64 | SCNiFAST8 SCNiFAST16 SCNiFAST32 SCNiFAST64 | SCNiFAST SCNiMAX SCNiPTR The fscanf macros for unsigned integers are: SCNo8 SCNo16 SCNo32 SCNo64 SCNoLEAST8 SCNoLEAST16 SCNoLEAST32 SCNoLEAST64 | SCNoFAST8 SCNoFAST16 SCNoFAST32 SCNoFAST64 | SCNoFAST SCNoMAX SCNoPTR SCNu8 SCNu16 SCNu32 SCNu64 SCNuLEAST8 SCNuLEAST16 SCNuLEAST32 SCNuLEAST64 | SCNuFAST8 SCNuFAST16 SCNuFAST32 SCNuFAST64 | SCNuFAST SCNuMAX SCNuPTR SCNx8 SCNx16 SCNx32 SCNx64 SCNxLEAST8 SCNxLEAST16 SCNxLEAST32 SCNxLEAST64 | SCNxFAST8 SCNxFAST16 SCNxFAST32 SCNxFAST64 | SCNxFAST SCNxMAX SCNxPTR Library 157 Document No. WG14/N761 (J11/97-125)Rewrite of <inttypes.h>September 26, 1997 The fwprintf macros for signed integers are: | WPRId8 WPRId16 WPRId32 WPRId64 | WPRIdLEAST8 WPRIdLEAST16 WPRIdLEAST32 WPRIdLEAST64 | WPRIdFAST8 WPRIdFAST16 WPRIdFAST32 WPRIdFAST64 | WPRIdFAST WPRIdMAX WPRIdPTR | WPRIi8 WPRIi16 WPRIi32 WPRIi64 | WPRIiLEAST8 WPRIiLEAST16 WPRIiLEAST32 WPRIiLEAST64 | WPRIiFAST8 WPRIiFAST16 WPRIiFAST32 WPRIiFAST64 | WPRIiFAST WPRIiMAX WPRIiPTR | The fwprintf macros for unsigned integers are: | WPRIo8 WPRIo16 WPRIo32 WPRIo64 | WPRIoLEAST8 WPRIoLEAST16 WPRIoLEAST32 WPRIoLEAST64 | WPRIoFAST8 WPRIoFAST16 WPRIoFAST32 WPRIoFAST64 | WPRIoFAST WPRIoMAX WPRIoPTR | WPRIu8 WPRIu16 WPRIu32 WPRIu64 | WPRIuLEAST8 WPRIuLEAST16 WPRIuLEAST32 WPRIuLEAST64 | WPRIuFAST8 WPRIuFAST16 WPRIuFAST32 WPRIuFAST64 | WPRIuFAST WPRIuMAX WPRIuPTR | WPRIx8 WPRIx16 WPRIx32 WPRIx64 | WPRIxLEAST8 WPRIxLEAST16 WPRIxLEAST32 WPRIxLEAST64 | WPRIxFAST8 WPRIxFAST16 WPRIxFAST32 WPRIxFAST64 | WPRIxFAST WPRIxMAX WPRIxPTR | WPRIX8 WPRIX16 WPRIX32 WPRIX64 | WPRIXLEAST8 WPRIXLEAST16 WPRIXLEAST32 WPRIXLEAST64 | WPRIXFAST8 WPRIXFAST16 WPRIXFAST32 WPRIXFAST64 | WPRIXFAST WPRIXMAX WPRIXPTR | The fwscanf macros for signed integers are: | WSCNd8 WSCNd16 WSCNd32 WSCNd64 | WSCNdLEAST8 WSCNdLEAST16 WSCNdLEAST32 WSCNdLEAST64 | WSCNdFAST8 WSCNdFAST16 WSCNdFAST32 WSCNdFAST64 | WSCNdFAST WSCNdMAX WSCNdPTR | WSCNi8 WSCNi16 WSCNi32 WSCNi64 | WSCNiLEAST8 WSCNiLEAST16 WSCNiLEAST32 WSCNiLEAST64 | WSCNiFAST8 WSCNiFAST16 WSCNiFAST32 WSCNiFAST64 | WSCNiFAST WSCNiMAX WSCNiPTR | The fwscanf macros for unsigned integers are: | WSCNo8 WSCNo16 WSCNo32 WSCNo64 | WSCNoLEAST8 WSCNoLEAST16 WSCNoLEAST32 WSCNoLEAST64 | WSCNoFAST8 WSCNoFAST16 WSCNoFAST32 WSCNoFAST64 | WSCNoFAST WSCNoMAX WSCNoPTR | WSCNu8 WSCNu16 WSCNu32 WSCNu64 | WSCNuLEAST8 WSCNuLEAST16 WSCNuLEAST32 WSCNuLEAST64 | 158 Library September 26, 1997Rewrite of <inttypes.h>Document No. WG14/N761 (J11/97-125) WSCNuFAST8 WSCNuFAST16 WSCNuFAST32 WSCNuFAST64 | WSCNuFAST WSCNuMAX WSCNuPTR | WSCNx8 WSCNx16 WSCNx32 WSCNx64 | WSCNxLEAST8 WSCNxLEAST16 WSCNxLEAST32 WSCNxLEAST64 | WSCNxFAST8 WSCNxFAST16 WSCNxFAST32 WSCNxFAST64 | WSCNxFAST WSCNxMAX WSCNxPTR | Because the default argument promotions do not affect | pointer parameters, there might not exist suitable fscanf | (or fwscanf) format specifiers for some of the declared | types, particularly those with typedef names containing 8. | Consequently, as a special exception to the requirement that | the implementation define all macros associated with a | declared type, in such a case the problematic fscanf (or | fwscanf) macros may be left undefined. | Example #include <inttypes.h> #include <stdio.h> int main(void) { uintmax_t i = UINTMAX_MAX; // this type always exists| printf("The largest integer value is %020" PRIxMAX "\n", i); return 0; } 7.4.5 Conversion macros123 for greatest-width integer types 7.4.5.1 The strtoimax macro Synopsis #include <inttypes.h> intmax_t strtoimax(const char * restrict nptr, char ** restrict endptr, int base); __________ 123. strtoimax, strtoumax, wcstoimax, and wcstoumax are | specified as macros rather than functions, to allow them | to be implemented as synonyms for functions named in | subclauses 7.13.1 and 7.18.4.1. | Library 159 Document No. WG14/N761 (J11/97-125)Rewrite of <inttypes.h>September 26, 1997 Description The strtoimax macro is equivalent to strtol, except that the initial portion of the string is converted to intmax_t representation. Returns The strtoimax macro returns the converted value, if any. If no conversion could be performed zero is returned. If the correct value is outside the range of representable values, INTMAX_MAX or INTMAX_MIN is returned (according to the sign of the value), and the value of the macro ERANGE is stored in errno. 7.4.5.2 The strtoumax macro Synopsis #include <inttypes.h> uintmax_t strtoumax(const char * restrict nptr, char ** restrict endptr, int base); Description The strtoumax macro is equivalent to strtoul, except that the initial portion of the string is converted to uintmax_t representation. Returns The strtoumax macro returns the converted value, if any. If no conversion could be performed zero is returned. If the correct value is outside the range of representable values, UINTMAX_MAX is returned, and the value of the macro ERANGE is stored in errno. 7.4.5.3 The wcstoimax macro | Synopsis | #include <inttypes.h> | intmax_t wcstoimax(const wchar_t * restrict nptr, | wchar_t ** restrict endptr, int base);| Description | The wcstoimax macro is equivalent to wcstol, except that the | initial portion of the wide string is converted to intmax_t | representation. | 160 Library September 26, 1997Rewrite of <inttypes.h>Document No. WG14/N761 (J11/97-125) Returns | The wcstoimax macro returns the converted value, if any. If | no conversion could be performed zero is returned. If the | correct value is outside the range of representable values, | INTMAX_MAX or INTMAX_MIN is returned (according to the sign | of the value), and the value of the macro ERANGE is stored | in errno. | 7.4.5.4 The wcstoumax macro | Synopsis | #include <inttypes.h> | uintmax_t wcstoumax(const wchar_t * restrict nptr, | wchar_t ** restrict endptr, int base);| Description | The wcstoumax macro is equivalent to wcstoul, except that | the initial portion of the wide string is converted to | uintmax_t representation. | Returns | The wcstoumax macro returns the converted value, if any. If | no conversion could be performed zero is returned. If the | correct value is outside the range of representable values, | UINTMAX_MAX is returned, and the value of the macro ERANGE | is stored in errno. | Library 161