November 17, 1997 Doc. No. WG14/N788 Rewrite of C9x Subclause 7.4 <inttypes.h> Douglas A. Gwyn US Army Research Laboratory Adelphi, MD ABSTRACT This edition reflects committee decisions made at the Menlo Park meeting; it supersedes Doc. No. WG14/N737 (J11/97-100) in the post-London mailing, Doc. No. WG14/N761 (J11/97-125) in the pre-Menlo Park mailing, and the preliminary ``working draft'' of Doc. No. WG14/N788 (J11/97-152) circulated at the Menlo Park meeting. With this introductory material removed, it is a ``drop-in'' replacement for the previous C9x (Draft 11-pre3) subclause 7.4 (source file cl-704.mm). 7.4 Integer types <inttypes.h> The header <inttypes.h> defines sets of typedef names for integer types having specified widths, and defines corresponding sets of macros. It also defines macros that specify limits of integer types corresponding to typedef names defined in other standard headers, and declares four functions for converting numeric character strings to greatest-width integers. Typedef names are defined 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; - integer types wide 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 defined types, construct suitable character constants, and provide conversion specifiers for use with the formatted input/output functions. Library 172 Doc. No. WG14/N788 <inttypes.h> November 17, 1997 For each typedef name described herein that can be defined as a type existing in the implementation,149 <inttypes.h> shall define that typedef name, and it shall define the associated macros. Conversely, for each typedef name described herein that cannot be defined as a type existing in the implementation, <inttypes.h> shall not define that typedef name, nor shall it define the associated macros. 7.4.1 Typedef names for integer types When typedef names differing only in the absence or presence of the initial u are defined, 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 typedef names designates an integer type that has exactly the specified width. These typedef 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 has a width of exactly 8 bits. The following designate exact-width signed integer types: int8_t int16_t int32_t int64_t 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 typedef names designates an integer type that has at least the specified width, such that no integer type of lesser size has at least the specified width. These typedef 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 has a width of at least 32 bits. The following designate minimum-width signed integer types: int_least8_t int_least16_t int_least32_t int_least64_t __________ 149. Some of these typedef names may denote implementation- defined extended integer types. 173 Library November 17, 1997 <inttypes.h> Doc. No. WG14/N788 The following designate minimum-width unsigned integer types: uint_least8_t uint_least16_t uint_least32_t uint_least64_t (These types must exist.) 7.4.1.3 Fastest minimum-width integer types Each of the following typedef names designates an integer type that is usually fastest150 to operate with among all integer types that have at least the specified width. These typedef 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 has a width of at least 16 bits. 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.) 7.4.1.4 Integer types capable of holding object pointers The following typedef 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 typedef 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 __________ 150. The designated type is not guaranteed to be fastest for all purposes; if the implementation has no clear grounds for choosing one type over another, it will simply pick some integer type satisfying the signedness and width requirements. Library 174 Doc. No. WG14/N788 <inttypes.h> November 17, 1997 void, and the result will compare equal to the original pointer: uintptr_t (Either or both of these types might not exist.) 7.4.1.5 Greatest-width integer types The following typedef name designates a signed integer type capable of representing any value of any signed integer type: intmax_t The following typedef name designates an unsigned integer type capable of representing any value of any unsigned integer type: uintmax_t (These types must exist.) 7.4.2 Limits of specified-width integer types The following object-like macros151 specify the minimum and maximum limits of integer types corresponding to the typedef names defined 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 __________ 151. C++ implementations should define these macros only when the macro __STDC_INTTYPES_LIMITS is defined before <inttypes.h> is included. 175 Library November 17, 1997 <inttypes.h> Doc. No. WG14/N788 (The value must be either that given or exactly 1 less.) - maximum values of exact-width signed integer types INT8_MAX +127 INT16_MAX +32767 INT32_MAX +2147483647 INT64_MAX +9223372036854775807 (The value must be exactly that given.) - maximum values of exact-width unsigned integer types UINT8_MAX 255 UINT16_MAX 65535 UINT32_MAX 4294967295 UINT64_MAX 18446744073709551615 (The value must be exactly that given.) 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 - 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 Library 176 Doc. No. WG14/N788 <inttypes.h> November 17, 1997 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 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.5 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 macros152 expand to integer constants suitable for initializing objects that have integer types corresponding to typedef names defined in <inttypes.h>. Each macro name corresponds to a similar typedef name in subclause 7.4.1.2 or 7.4.1.5. 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 __________ 152. C++ implementations should define these macros only when the macro __STDC_INTTYPES_CONSTANTS is defined before <inttypes.h> is included. 177 Library November 17, 1997 <inttypes.h> Doc. No. WG14/N788 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 macro 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) 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 the type intmax_t: INTMAX_C(value) The following macro expands to an integer constant having the value specified by its argument and the type uintmax_t: UINTMAX_C(value) 7.4.4 Macros for format specifiers Each of the following object-like macros153 expands to a string literal containing a conversion specifier, possibly modified by a prefix such as hh, h, l, or ll, suitable for use within the format argument of a formatted input/output function when converting the corresponding integer type. These macro names have the general form of PRI (character string literals for the fprintf family) or SCN (character string literals for the fscanf family),154 followed by the __________ 153. C++ implementations should define these macros only when the macro __STDC_INTTYPES_PRINT_SCAN is defined before <inttypes.h> is included. 154. Separate macros are given for use with fprintf and fscanf functions because, typically, different format Library 178 Doc. No. WG14/N788 <inttypes.h> November 17, 1997 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 the value of 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 PRIdMAX PRIdPTR PRIi8 PRIi16 PRIi32 PRIi64 PRIiLEAST8 PRIiLEAST16 PRIiLEAST32 PRIiLEAST64 PRIiFAST8 PRIiFAST16 PRIiFAST32 PRIiFAST64 PRIiMAX PRIiPTR The fprintf macros for unsigned integers are: PRIo8 PRIo16 PRIo32 PRIo64 PRIoLEAST8 PRIoLEAST16 PRIoLEAST32 PRIoLEAST64 PRIoFAST8 PRIoFAST16 PRIoFAST32 PRIoFAST64 PRIoMAX PRIoPTR PRIu8 PRIu16 PRIu32 PRIu64 PRIuLEAST8 PRIuLEAST16 PRIuLEAST32 PRIuLEAST64 PRIuFAST8 PRIuFAST16 PRIuFAST32 PRIuFAST64 PRIuMAX PRIuPTR PRIx8 PRIx16 PRIx32 PRIx64 PRIxLEAST8 PRIxLEAST16 PRIxLEAST32 PRIxLEAST64 PRIxFAST8 PRIxFAST16 PRIxFAST32 PRIxFAST64 PRIxMAX PRIxPTR PRIX8 PRIX16 PRIX32 PRIX64 PRIXLEAST8 PRIXLEAST16 PRIXLEAST32 PRIXLEAST64 PRIXFAST8 PRIXFAST16 PRIXFAST32 PRIXFAST64 PRIXMAX PRIXPTR The fscanf macros for signed integers are: SCNd8 SCNd16 SCNd32 SCNd64 SCNdLEAST8 SCNdLEAST16 SCNdLEAST32 SCNdLEAST64 SCNdFAST8 SCNdFAST16 SCNdFAST32 SCNdFAST64 SCNdMAX SCNdPTR SCNi8 SCNi16 SCNi32 SCNi64 ____________________________________________________________ specifiers are required for fprintf and fscanf even when the type is the same. 179 Library November 17, 1997 <inttypes.h> Doc. No. WG14/N788 SCNiLEAST8 SCNiLEAST16 SCNiLEAST32 SCNiLEAST64 SCNiFAST8 SCNiFAST16 SCNiFAST32 SCNiFAST64 SCNiMAX SCNiPTR The fscanf macros for unsigned integers are: SCNo8 SCNo16 SCNo32 SCNo64 SCNoLEAST8 SCNoLEAST16 SCNoLEAST32 SCNoLEAST64 SCNoFAST8 SCNoFAST16 SCNoFAST32 SCNoFAST64 SCNoMAX SCNoPTR SCNu8 SCNu16 SCNu32 SCNu64 SCNuLEAST8 SCNuLEAST16 SCNuLEAST32 SCNuLEAST64 SCNuFAST8 SCNuFAST16 SCNuFAST32 SCNuFAST64 SCNuMAX SCNuPTR SCNx8 SCNx16 SCNx32 SCNx64 SCNxLEAST8 SCNxLEAST16 SCNxLEAST32 SCNxLEAST64 SCNxFAST8 SCNxFAST16 SCNxFAST32 SCNxFAST64 SCNxMAX SCNxPTR Because the default argument promotions do not affect pointer parameters, there might not exist suitable fscanf format specifiers for some of the typedef names defined in this header. Consequently, as a special exception to the requirement that the implementation shall define all macros associated with each typedef name defined in this header, in such a case the problematic fscanf macros may be left undefined. Example #include <inttypes.h> #include <wchar.h> int main(void) { uintmax_t i = UINTMAX_MAX; // this type always exists wprintf(L"The largest integer value is %020" PRIxMAX "\n", i); return 0; } 7.4.5 Limits of other integer types The following object-like macros151 specify the minimum and maximum limits of integer types corresponding to typedef names defined in other standard headers. Each instance of these macros 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 Library 180 Doc. No. WG14/N788 <inttypes.h> November 17, 1997 magnitude (absolute value) than the corresponding value given below, with the same sign. - limits of ptrdiff_t PTRDIFF_MIN -65535 PTRDIFF_MAX +65535 - limits of sig_atomic_t SIG_ATOMIC_MIN see below SIG_ATOMIC_MAX see below - limit of size_t SIZE_MAX 65535 - limits of wchar_t WCHAR_MIN see below WCHAR_MAX see below - limits of wint_t WINT_MIN see below WINT_MAX see below If sig_atomic_t is defined as a signed integer type, the value of SIG_ATOMIC_MIN shall be no greater than -127 and the value of SIG_ATOMIC_MAX shall be no less than 127; otherwise, sig_atomic_t is defined as an unsigned integer type, and the value of SIG_ATOMIC_MIN shall be 0 and the value of SIG_ATOMIC_MAX shall be no less than 255. If wchar_t is defined as a signed integer type, the value of WCHAR_MIN shall be no greater than -127 and the value of WCHAR_MAX shall be no less than 127; otherwise, wchar_t is defined as an unsigned integer type, and the value of WCHAR_MIN shall be 0 and the value of WCHAR_MAX shall be no less than 255. If wint_t is defined as a signed integer type, the value of WINT_MIN shall be no greater than -32767 and the value of WINT_MAX shall be no less than 32767; otherwise, wint_t is defined as an unsigned integer type, and the value of WINT_MIN shall be 0 and the value of WINT_MAX shall be no less than 65535. 7.4.6 Conversion functions for greatest-width integer types 7.4.6.1 The strtoimax function 181 Library November 17, 1997 <inttypes.h> Doc. No. WG14/N788 Synopsis #include <inttypes.h> intmax_t strtoimax(const char * restrict nptr, char ** restrict endptr, int base); Description The strtoimax function is equivalent to strtol, except that the initial portion of the string is converted to intmax_t representation. Returns The strtoimax function 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.6.2 The strtoumax function Synopsis #include <inttypes.h> uintmax_t strtoumax(const char * restrict nptr, char ** restrict endptr, int base); Description The strtoumax function is equivalent to strtoul, except that the initial portion of the string is converted to uintmax_t representation. Returns The strtoumax function 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.6.3 The wcstoimax function Synopsis #include <stddef.h> // for wchar_t #include <inttypes.h> intmax_t wcstoimax(const wchar_t * restrict nptr, wchar_t ** restrict endptr, int base); Library 182 Doc. No. WG14/N788 <inttypes.h> November 17, 1997 Description The wcstoimax function is equivalent to wcstol, except that the initial portion of the wide string is converted to intmax_t representation. Returns The wcstoimax function 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.6.4 The wcstoumax function Synopsis #include <stddef.h> // for wchar_t #include <inttypes.h> uintmax_t wcstoumax(const wchar_t * restrict nptr, wchar_t ** restrict endptr, int base); Description The wcstoumax function is equivalent to wcstoul, except that the initial portion of the wide string is converted to uintmax_t representation. Returns The wcstoumax function 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. 183 Library