JTC1/SC22/WG14
N788
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