starting with the first digit or the decimal-point character (whichever occurs first) is interpreted as a
floating constant according to the rules of <IP_ADDRESS>, except that the decimal-point character is used
in place of a period, and that if neither an exponent part nor a decimal-point character appears in
a decimal floating-point number, or if a binary exponent part does not appear in a hexadecimal
floating-point number, an exponent part of the appropriate type with value zero is assumed to
follow the last digit in the string. If the subject sequence begins with a minus sign, the sequence is
interpreted as negated.[356]
A character sequence INF or INFINITY is interpreted as an infinity, if representable in the return type,
else like a floating constant that is too large for the range of the return type. A character sequence
NAN or NAN(n-char-sequenceopt ) is interpreted as a quiet NaN, if supported in the return type, else like
a subject sequence part that does not have the expected form; the meaning of the n-char sequence
is implementation-defined.[357] A pointer to the final string is stored in the object pointed to by
endptr, provided that endptr is not a null pointer.
Footnote 356) It is unspecified whether a minus-signed sequence is converted to a negative number directly or by negating the value
resulting from converting the corresponding unsigned sequence (see F.5); the two methods could yield different results if
rounding is toward positive or negative infinity. In either case, the functions honor the sign of zero if floating-point arithmetic
supports signed zeros.
Footnote 357) An implementation can use the n-char sequence to determine extra information to be represented in the NaN’s significand.
5 If the subject sequence has the hexadecimal form and FLT_RADIX is a power of 2, the value resulting
from the conversion is correctly rounded.
6 In other than the "C" locale, additional locale-specific subject sequence forms may be accepted.
7 If the subject sequence is empty or does not have the expected form, no conversion is performed; the
value of nptr is stored in the object pointed to by endptr, provided that endptr is not a null pointer.
Recommended practice
8 If the subject sequence has the hexadecimal form, FLT_RADIX is not a power of 2, and the result is
not exactly representable, the result should be one of the two numbers in the appropriate internal
format that are adjacent to the hexadecimal floating source value, with the extra stipulation that the
error should have a correct sign for the current rounding direction.
9 If the subject sequence has the decimal form and at most M significant digits, where M is the
maximum value of the T_DECIMAL_DIG macros (defined in <float.h>), the result should be correctly
rounded. If the subject sequence D has the decimal form and more than M significant digits, consider
the two bounding, adjacent decimal strings L and U, both having M significant digits, such that the
values of L, D, and U satisfy L ≤ D ≤ U. The result should be one of the (equal or adjacent) values
that would be obtained by correctly rounding L and U according to the current rounding direction,
with the extra stipulation that the error with respect to D should have a correct sign for the current
rounding direction.[358]
Returns
Footnote 358) M is sufficiently large that L and U will usually correctly round to the same internal floating value, but if not will correctly
round to adjacent values.
10 The functions return the converted value, if any. If no conversion could be performed, zero is
returned.
If the correct value overflows and default rounding is in effect (7.12.1), plus or minus HUGE_VAL,
HUGE_VALF, or HUGE_VALL is returned (according to the return type and sign of the value); if the
integer expression math_errhandling & MATH_ERRNO is nonzero, the integer expression errno
acquires the value of ERANGE; if the integer expression math_errhandling & MATH_ERREXCEPT is
nonzero, the "overflow" floating-point exception is raised.
If the result underflows (7.12.1), the functions return a value whose magnitude is no greater
than the smallest normalized positive number in the return type; if the integer expression
math_errhandling & MATH_ERRNO is nonzero, whether errno acquires the value ERANGE is
implementation-defined; if the integer expression math_errhandling & MATH_ERREXCEPT is
nonzero, whether the "underflow" floating-point exception is raised is implementation-defined.
<IP_ADDRESS> [The strtodN functions]
1 Synopsis
#include <stdlib.h>
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 strtod32(const char * restrict nptr, char ** restrict endptr);
_Decimal64 strtod64(const char * restrict nptr,char ** restrict endptr);
_Decimal128 strtod128(const char * restrict nptr,char ** restrict endptr);
#endif
Description
2 The strtodN functions convert the initial portion of the string pointed to by nptr to decimal floating
type representation. First, they decompose the input string into three parts: an initial, possibly
empty, sequence of white-space characters; a subject sequence resembling a floating constant or
representing an infinity or NaN; and a final string of one or more unrecognized characters, including
the terminating null character of the input string. Then, they attempt to convert the subject sequence
to a floating-point number, and return the result.
3 The expected form of the subject sequence is an optional plus or minus sign, then one of the
following:
— a nonempty sequence of decimal digits optionally containing a decimal-point character, then
an optional exponent part as defined in <IP_ADDRESS>, excluding any digit separators (<IP_ADDRESS>)
— INF or INFINITY, ignoring case
— NAN or NAN(d-char-sequenceopt ), ignoring case in the NAN part, where: d-char-sequence:
digit
nondigit
d-char-sequence digit
d-char-sequence nondigit
The subject sequence is defined as the longest initial subsequence of the input string, starting with
the first non-white-space character, that is of the expected form. The subject sequence contains no
characters if the input string is not of the expected form.
4 If the subject sequence has the expected form for a floating-point number, the sequence of characters
starting with the first digit or the decimal-point character (whichever occurs first) is interpreted as a
floating constant according to the rules of <IP_ADDRESS>, including correct rounding and determination of
the coefficient c and the quantum exponent q, with the following exceptions:
— It is not a hexadecimal floating number.
— The decimal-point character is used in place of a period.
— If neither an exponent part nor a decimal-point character appears in a decimal floating-point
number, an exponent part of the appropriate type with value zero is assumed to follow the
last digit in the string.
If the subject sequence begins with a minus sign, the sequence is interpreted as negated (before
rounding) and the sign s is set to −1, else s is set to 1. A character sequence INF or INFINITY is
interpreted as an infinity. A character sequence NAN or NAN(d-char-sequenceopt ), is interpreted as a
quiet NaN; the meaning of the d-char sequence is implementation-defined.[359] A pointer to the final
string is stored in the object pointed to by endptr, provided that endptr is not a null pointer.
Footnote 359) An implementation may use the d-char sequence to determine extra information to be represented in the NaN’s
significand.
5 In other than the "C" locale, additional locale-specific subject sequence forms may be accepted.
6 If the subject sequence is empty or does not have the expected form, no conversion is performed; the
value of nptr is stored in the object pointed to by endptr, provided that endptr is not a null pointer.
Returns
7 The strtodN functions return the correctly rounded converted value, if any. If no conversion could
be performed, the value of the triple (+1, 0, 0) is returned. If the correct value overflows:
— the value of the macro ERANGE is stored in errno if the integer expression
math_errhandling & MATH_ERRNO is nonzero;
— the "overflow" floating-point exception is raised if the integer expression
math_errhandling & MATH_ERREXCEPT is nonzero.
If the result underflows (7.12.1), whether errno acquires the value ERANGE if the integer expression
math_errhandling & MATH_ERRNO is nonzero is implementation-defined; if the integer expres-
sion math_errhandling & MATH_ERREXCEPT is nonzero, whether the "underflow" floating-point
exception is raised is implementation-defined.
8 EXAMPLE Following are subject sequences of the decimal form and the resulting triples (s, c, q) produced by strtod64.
Note that for _Decimal64 , the precision (maximum coefficient length) is 16 and the quantum exponent range is −398 ≤ q ≤ 369.
"0" (+1, 0, 0)
"0.00" (+1, 0, −2)
"123" (+1, 123, 0)
"-123" (−1, 123, 0)
"1.23E3" (+1, 123, 1)
"1.23E+3" (+1, 123, 1)
"12.3E+7" (+1, 123, 6)
"12.0" (+1, 120, −1)
"12.3" (+1, 123, −1)
"0.00123" (+1, 123, −5)
"-1.23E-12" (−1, 123, −14)
"1234.5E-4" (+1, 12345, −5)
"-0" (−1, 0, 0)
"-0.00" (−1, 0, −2)
"0E+7" (+1, 0, 7)
"-0E-7" (−1, 0, −7)
"12345678901234567890" (+1,<PHONE_NUMBER>123457, 4) or (+1,<PHONE_NUMBER>123456, 4) depending on rounding
mode
"1234E-400" (+1, 12, −398) or (+1, 13, −398) depending on rounding mode
"1234E-402" (+1, 0, −398) or (+1, 1, −398) depending on rounding mode
"1000." (+1, 1000, 0)
".0001" (+1, 1, −4)
"1000.e0" (+1, 1000, 0)
".0001e0" (+1, 1, −4)
"1000.0" (+1, 10000, −1)
"0.0001" (+1, 1, −4)
"1000.00" (+1, 100000, −2)
"00.0001" (+1, 1, −4)
"001000." (+1, 1000, 0)
"001000.0" (+1, 10000, −1)
"001000.00" (+1, 100000, −2)
"00.00" (+1, 0, −2)
"00." (+1, 0, 0)
".00" (+1, 0, −2)
"00.00e-5" (+1, 0, −7)
"00.e-5" (+1, 0, −5)
".00e-5" (+1, 0, −7)
"0x1.8p+4" (+1, 0, 0), and a pointer to "x1.8p+4" is stored in the object pointed to by endptr,
provided endptr is not a null pointer
"infinite" infinity, and a pointer to "inite" is stored in the object pointed to by endptr, provided
endptr is not a null pointer
<IP_ADDRESS> [The strtol, strtoll, strtoul, and strtoull functions]
1 Synopsis
#include <stdlib.h>
long int strtol(const char *restrict nptr, char **restrict endptr, int base);
long long int strtoll(const char *restrict nptr, char **restrict endptr, int base);
unsigned long int strtoul(const char *restrict nptr, char **restrict endptr, int base);
unsigned long long int strtoull(const char *restrict nptr, char **restrict endptr, int
base);
Description
2 The strtol, strtoll, strtoul, and strtoull functions convert the initial portion of
the string pointed to by nptr to long int, long long int, unsigned long int, and
unsigned long long int representation, respectively. First, they decompose the input
string into three parts: an initial, possibly empty, sequence of white-space characters, a subject
sequence resembling an integer represented in some radix determined by the value of base, and a
final string of one or more unrecognized characters, including the terminating null character of the
input string. Then, they attempt to convert the subject sequence to an integer, and return the result.
3 If the value of base is zero, the expected form of the subject sequence is that of an integer constant as
described in <IP_ADDRESS>, optionally preceded by a plus or minus sign, but not including an integer suffix
or any optional digit separators. If the value of base is between 2 and 36 (inclusive), the expected
form of the subject sequence is a sequence of letters and digits representing an integer with the radix
specified by base, optionally preceded by a plus or minus sign, but not including an integer suffix
or any optional digit separators. The letters from a (or A) through z (or Z) are ascribed the values 10
through 35; only letters and digits whose ascribed values are less than that of base are permitted. If
the value of base is 2, the characters 0b or 0B may optionally precede the sequence of letters and
digits, following the sign if present. If the value of base is 16, the characters 0x or 0X may optionally
precede the sequence of letters and digits, following the sign if present.
4 The subject sequence is defined as the longest initial subsequence of the input string, starting with
the first non-white-space character, that is of the expected form. The subject sequence contains no
characters if the input string is empty or consists entirely of white-space characters, or if the first
non-white-space character is other than a sign or a permissible letter or digit.
5 If the subject sequence has the expected form and the value of base is zero, the sequence of characters
starting with the first digit is interpreted as an integer constant according to the rules of <IP_ADDRESS>. If
the subject sequence has the expected form and the value of base is between 2 and 36, it is used as
the base for conversion, ascribing to each letter its value as given above. If the subject sequence
begins with a minus sign, the value resulting from the conversion is negated (in the return type). A
pointer to the final string is stored in the object pointed to by endptr, provided that endptr is not a
null pointer.
6 In other than the "C" locale, additional locale-specific subject sequence forms may be accepted.
7 If the subject sequence is empty or does not have the expected form, no conversion is performed; the
value of nptr is stored in the object pointed to by endptr, provided that endptr is not a null pointer.
Returns
8 The strtol, strtoll, strtoul, and strtoull functions return 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, LONG_MIN, LONG_MAX, LLONG_MIN, LLONG_MAX, ULONG_MAX, or ULLONG_MAX is
returned (according to the return type and sign of the value, if any), and the value of the macro
ERANGE is stored in errno.
7.24.2 [Pseudo-random sequence generation functions]
<IP_ADDRESS> [The rand function]
1 Synopsis
#include <stdlib.h>
int rand(void);
Description
2 The rand function computes a sequence of pseudo-random integers in the range 0 to RAND_MAX
inclusive.
3 The rand function is not required to avoid data races with other calls to pseudo-random sequence
generation functions. The implementation shall behave as if no library function calls the rand
function.
Recommended practice
4 There are no guarantees as to the quality of the random sequence produced and some implementa-
tions are known to produce sequences with distressingly non-random low-order bits. Applications
with particular requirements should use a generator that is known to be sufficient for their needs.
Returns
5 The rand function returns a pseudo-random integer.
Environmental limits
6 The value of the RAND_MAX macro shall be at least 32767.
<IP_ADDRESS> [The srand function]
1 Synopsis
#include <stdlib.h>
void srand(unsigned int seed);
Description
2 The srand function uses the argument as a seed for a new sequence of pseudo-random numbers
to be returned by subsequent calls to rand. If srand is then called with the same seed value, the
sequence of pseudo-random numbers shall be repeated. If rand is called before any calls to srand
have been made, the same sequence shall be generated as when srand is first called with a seed
value of 1.
3 The srand function is not required to avoid data races with other calls to pseudo-random sequence
generation functions. The implementation shall behave as if no library function calls the srand
function.
Returns
4 The srand function returns no value.
5 EXAMPLE The following functions define a portable implementation of rand and srand.
static unsigned long int next = 1;
int rand(void) // RAND_MAX assumed to be 32767
{
next = next *<PHONE_NUMBER> + 12345;
return (unsigned int)(next/65536) % 32768;
}
void srand(unsigned int seed)
{
next = seed;
}
7.24.3 [Memory management functions]
1 The order and contiguity of storage allocated by successive calls to the aligned_alloc, calloc,
malloc, and realloc functions is unspecified. The pointer returned if the allocation succeeds is
suitably aligned so that it may be assigned to a pointer to any type of object with a fundamental
alignment requirement and size less than or equal to the size requested. It may then be used to
access such an object or an array of such objects in the space allocated (until the space is explicitly
deallocated). The lifetime of an allocated object extends from the allocation until the deallocation.
Each such allocation shall yield a pointer to an object disjoint from any other object. The pointer
returned points to the start (lowest byte address) of the allocated space. If the space cannot be
allocated, a null pointer is returned. If the size of the space requested is zero, the behavior is
implementation-defined: either a null pointer is returned to indicate an error, or the behavior is as if
the size were some nonzero value, except that the returned pointer shall not be used to access an
object.
2 For purposes of determining the existence of a data race, memory allocation functions behave as
though they accessed only memory locations accessible through their arguments and not other
static duration storage. These functions may, however, visibly modify the storage that they allocate
or deallocate. Calls to these functions that allocate or deallocate a particular region of memory
shall occur in a single total order, and each such deallocation call shall synchronize with the next
allocation (if any) in this order.
<IP_ADDRESS> [The aligned_alloc function]
1 Synopsis
#include <stdlib.h>
void *aligned_alloc(size_t alignment, size_t size);
Description
2 The aligned_alloc function allocates space for an object whose alignment is specified by
alignment, whose size is specified by size, and whose representation is indeterminate. If the
value of alignment is not a valid alignment supported by the implementation the function shall fail
by returning a null pointer.
Returns
3 The aligned_alloc function returns either a null pointer or a pointer to the allocated space.
<IP_ADDRESS> [The calloc function]
1 Synopsis
#include <stdlib.h>
void *calloc(size_t nmemb, size_t size);
Description
2 The calloc function allocates space for an array of nmemb objects, each of whose size is size. The
space is initialized to all bits zero[360] .
Returns
Footnote 360) Note that this need not be the same as the representation of floating-point zero or a null pointer constant.
3 The calloc function returns either a pointer to the allocated space or a null pointer if the space
cannot be allocated or if the mathematical product nmemb * size is not representable as a value of
type size_t.
<IP_ADDRESS> [The free function]
1 Synopsis
#include <stdlib.h>
void free(void *ptr);
Description
2 The free function causes the space pointed to by ptr to be deallocated, that is, made available
for further allocation. If ptr is a null pointer, no action occurs. Otherwise, if the argument does
not match a pointer earlier returned by a memory management function, or if the space has been
deallocated by a call to free or realloc, the behavior is undefined.
Returns
3 The free function returns no value.
<IP_ADDRESS> [The free_sized function]
1 Synopsis
#include <stdlib.h>
void free_sized(void *ptr, size_t size);
Description
2 If ptr is a null pointer or the result obtained from a call to malloc, realloc, or calloc, where size
size is equal to the requested allocation size, this function is equivalent to free(ptr). Otherwise,
the behavior is undefined.
3 NOTE 1 A conforming implementation may ignore size and call free.
4 NOTE 2 The result of an aligned_alloc call may not be passed to free_sized.
Recommended practice
5 Implementations may provide extensions to query the usable size of an allocation, or to determine
the usable size of the allocation that would result if a request for some other size were to succeed.
Such implementations should allow passing the resulting usable size as the size parameter, and
provide functionality equivalent to free in such cases.
Returns
6 The free_sized function returns no value.
<IP_ADDRESS> [The free_aligned_sized function]
1 Synopsis
#include <stdlib.h>
void free_aligned_sized(void *ptr, size_t alignment, size_t size);
Description
2 If ptr is a null pointer or the result obtained from a call to aligned_alloc, where alignment is
equal to the requested allocation alignment and size is equal to the requested allocation size, this
function is equivalent to free(ptr). Otherwise, the behavior is undefined.
3 NOTE 1 A conforming implementation may ignore alignment and size and call free.
4 NOTE 2 The result of an malloc, calloc, or realloc call may not be passed to free_aligned_sized.
Recommended practice
5 Implementations may provide extensions to query the usable size of an allocation, or to determine
the usable size of the allocation that would result if a request for some other size were to succeed.
Such implementations should allow passing the resulting usable size as the size parameter, and
provide functionality equivalent to free in such cases.
Returns
6 The free_aligned_sized function returns no value.
<IP_ADDRESS> [The malloc function]
1 Synopsis
#include <stdlib.h>
void *malloc(size_t size);
Description
2 The malloc function allocates space for an object whose size is specified by size and whose
representation is indeterminate.
Returns
3 The malloc function returns either a null pointer or a pointer to the allocated space.
<IP_ADDRESS> [The realloc function]
1 Synopsis
#include <stdlib.h>
void *realloc(void *ptr, size_t size);
Description
2 The realloc function deallocates the old object pointed to by ptr and returns a pointer to a new
object that has the size specified by size. The contents of the new object shall be the same as that of
the old object prior to deallocation, up to the lesser of the new and old sizes. Any bytes in the new
object beyond the size of the old object have unspecified values.
3 If ptr is a null pointer, the realloc function behaves like the malloc function for the specified size.
Otherwise, if ptr does not match a pointer earlier returned by a memory management function, or
if the space has been deallocated by a call to the free or realloc function, or if the size is zero, the
behavior is undefined. If memory for the new object is not allocated, the old object is not deallocated
and its value is unchanged.
Returns
4 The realloc function returns a pointer to the new object (which may have the same value as a
pointer to the old object), or a null pointer if the new object has not been allocated.
7.24.4 [Communication with the environment]
<IP_ADDRESS> [The abort function]
1 Synopsis
#include <stdlib.h>
[[noreturn]] void abort(void);
Description
2 The abort function causes abnormal program termination to occur, unless the signal SIGABRT is
being caught and the signal handler does not return. Whether open streams with unwritten buffered
data are flushed, open streams are closed, or temporary files are removed is implementation-
defined. An implementation-defined form of the status unsuccessful termination is returned to the
host environment by means of the function call raise(SIGABRT).
Returns
3 The abort function does not return to its caller.
<IP_ADDRESS> [The atexit function]
1 Synopsis
#include <stdlib.h>
int atexit(void (*func)(void));
Description
2 The atexit function registers the function pointed to by func, to be called without arguments at
normal program termination.[361] It is unspecified whether a call to the atexit function that does
not happen before the exit function is called will succeed.
Environmental limits
Footnote 361) The atexit function registrations are distinct from the at_quick_exit registrations, so applications might need to call
both registration functions with the same argument.
3 The implementation shall support the registration of at least 32 functions.
Returns
4 The atexit function returns zero if the registration succeeds, nonzero if it fails.
Forward references: the at_quick_exit function (<IP_ADDRESS>), the exit function (<IP_ADDRESS>).
<IP_ADDRESS> [The at_quick_exit function]
1 Synopsis
#include <stdlib.h>
int at_quick_exit(void (*func)(void));
Description
2 The at_quick_exit function registers the function pointed to by func, to be called without argu-
ments should quick_exit be called.[362] It is unspecified whether a call to the at_quick_exit
function that does not happen before the quick_exit function is called will succeed.
Environmental limits
Footnote 362) The at_quick_exit function registrations are distinct from the atexit registrations, so applications might need to call
both registration functions with the same argument.
3 The implementation shall support the registration of at least 32 functions.
Returns
4 The at_quick_exit function returns zero if the registration succeeds, nonzero if it fails.
Forward references: the quick_exit function (<IP_ADDRESS>).
<IP_ADDRESS> [The exit function]
1 Synopsis
#include <stdlib.h>
[[noreturn]] void exit(int status);
Description
2 The exit function causes normal program termination to occur. No functions registered by the
at_quick_exit function are called. If a program calls the exit function more than once, or calls the
quick_exit function in addition to the exit function, the behavior is undefined.
3 First, all functions registered by the atexit function are called, in the reverse order of their registra-
tion,[363] except that a function is called after any previously registered functions that had already
been called at the time it was registered. If, during the call to any such function, a call to the longjmp
function is made that would terminate the call to the registered function, the behavior is undefined.
Footnote 363) Each function is called as many times as it was registered, and in the correct order with respect to other registered
functions.
4 Next, all open streams with unwritten buffered data are flushed, all open streams are closed, and all
files created by the tmpfile function are removed.
5 Finally, control is returned to the host environment. If the value of status is zero or EXIT_SUCCESS,
an implementation-defined form of the status successful termination is returned. If the value of
status is EXIT_FAILURE, an implementation-defined form of the status unsuccessful termination is
returned. Otherwise the status returned is implementation-defined.
Returns
6 The exit function cannot return to its caller.
<IP_ADDRESS> [The _Exit function]
1 Synopsis
#include <stdlib.h>
[[noreturn]] void _Exit(int status);
Description
2 The _Exit function causes normal program termination to occur and control to be returned to the
host environment. No functions registered by the atexit function, the at_quick_exit function,
or signal handlers registered by the signal function are called. The status returned to the host
environment is determined in the same way as for the exit function (<IP_ADDRESS>). Whether open
streams with unwritten buffered data are flushed, open streams are closed, or temporary files are
removed is implementation-defined.
Returns
3 The _Exit function cannot return to its caller.
<IP_ADDRESS> [The getenv function]
1 Synopsis
#include <stdlib.h>
char *getenv(const char *name);
Description
2 The getenv function searches an environment list, provided by the host environment, for a string that
matches the string pointed to by name. The set of environment names and the method for altering
the environment list are implementation-defined. The getenv function need not avoid data races
with other threads of execution that modify the environment list.[364]
Footnote 364) Many implementations provide non-standard functions that modify the environment list.
3 The implementation shall behave as if no library function calls the getenv function.
Returns
4 The getenv function returns a pointer to a string associated with the matched list member. The
string pointed to shall not be modified by the program, but may be overwritten by a subsequent call
to the getenv function. If the specified name cannot be found, a null pointer is returned.
<IP_ADDRESS> [The quick_exit function]
1 Synopsis
#include <stdlib.h>
[[noreturn]] void quick_exit(int status);
Description
2 The quick_exit function causes normal program termination to occur. No functions registered by
the atexit function or signal handlers registered by the signal function are called. If a program calls
the quick_exit function more than once, or calls the exit function in addition to the quick_exit
function, the behavior is undefined. If a signal is raised while the quick_exit function is executing,
the behavior is undefined.
3 The quick_exit function first calls all functions registered by the at_quick_exit function, in the
reverse order of their registration,[365] except that a function is called after any previously registered
functions that had already been called at the time it was registered. If, during the call to any such
function, a call to the longjmp function is made that would terminate the call to the registered
function, the behavior is undefined.
Footnote 365) Each function is called as many times as it was registered, and in the correct order with respect to other registered
functions.
4 Then control is returned to the host environment by means of the function call _Exit(status) .
Returns
5 The quick_exit function cannot return to its caller.
<IP_ADDRESS> [The system function]
1 Synopsis
#include <stdlib.h>
int system(const char *string);
Description
2 If string is a null pointer, the system function determines whether the host environment has a
command processor. If string is not a null pointer, the system function passes the string pointed to
by string to that command processor to be executed in a manner which the implementation shall
document; this might then cause the program calling system to behave in a non-conforming manner
or to terminate.
Returns
3 If the argument is a null pointer, the system function returns nonzero only if a command processor
is available. If the argument is not a null pointer, and the system function does return, it returns an
implementation-defined value.
7.24.5 [Searching and sorting utilities]
1 These utilities make use of a comparison function to search or sort arrays of unspecified type. Where
an argument declared as size_t nmemb specifies the length of the array for a function, nmemb can
have the value zero on a call to that function; the comparison function is not called, a search finds no
matching element, and sorting performs no rearrangement. Pointer arguments on such a call shall
still have valid values, as described in 7.1.4.
2 The implementation shall ensure that the second argument of the comparison function (when called
from bsearch), or both arguments (when called from qsort), are pointers to elements of the array.[366]
The first argument when called from bsearch shall equal key.
Footnote 366) That is, if the value passed is p, then the following expressions are always nonzero:
((char *)p - (char *)base) % size == 0
(char *)p >= (char *)base
(char *)p < (char *)base + nmemb * size
3 The comparison function shall not alter the contents of the array. The implementation may reorder
elements of the array between calls to the comparison function, but shall not alter the contents of
any individual element.
4 When the same objects (consisting of size bytes, irrespective of their current positions in the array)
are passed more than once to the comparison function, the results shall be consistent with one
another. That is, for qsort they shall define a total ordering on the array, and for bsearch the same
object shall always compare the same way with the key.
5 A sequence point occurs immediately before and immediately after each call to the comparison
function, and also between any call to the comparison function and any movement of the objects
passed as arguments to that call.
<IP_ADDRESS> [The bsearch generic function]
1 Synopsis
#include <stdlib.h>
void *bsearch(const void *key, const void *base, size_t nmemb, size_t size,
int (*compar)(const void *, const void *));
Description
2 The bsearch generic function searches an array of nmemb objects, the initial element of which is
pointed to by base, for an element that matches the object pointed to by key. The size of each
element of the array is specified by size.
3 The comparison function pointed to by compar is called with two arguments that point to the key
object and to an array element, in that order. The function shall return an integer less than, equal to,
or greater than zero if the key object is considered, respectively, to be less than, to match, or to be
greater than the array element. The array shall consist of: all the elements that compare less than, all
the elements that compare equal to, and all the elements that compare greater than the key object, in
that order.[367]
Returns
Footnote 367) In practice, the entire array is sorted according to the comparison function.
4 The bsearch generic function returns a pointer to a matching element of the array, or a null pointer
if no match is found. If two elements compare as equal, which element is matched is unspecified.
5 The bsearch function is generic in the qualification of the type pointed to by the argument to base.
If this argument is a pointer to a const-qualified object type, the returned pointer will be a pointer
to const-qualified void. Otherwise, the argument shall be a pointer to an unqualified object type or
a null pointer constant[368] , and the returned pointer will be a pointer to unqualified void.
The external declaration of bsearch has the concrete type:
void * (const void *, const void *, size_t, size_t, int (*) (const void *, const
void *))
, which supports all correct uses. If a macro definition of this generic function is suppressed in order
to access an actual function, the external declaration with this concrete type is visible[369] .
Footnote 368) If the argument is a null pointer and the call is executed, the behavior is undefined.
Footnote 369) This is an obsolescent feature.
<IP_ADDRESS> [The qsort function]
1 Synopsis
#include <stdlib.h>
void qsort(void *base, size_t nmemb, size_t size,
int (*compar)(const void *, const void *));
Description
2 The qsort function sorts an array of nmemb objects, the initial element of which is pointed to by
base. The size of each object is specified by size.
3 The contents of the array are sorted into ascending order according to a comparison function pointed
to by compar, which is called with two arguments that point to the objects being compared. The
function shall return an integer less than, equal to, or greater than zero if the first argument is
considered to be respectively less than, equal to, or greater than the second.
4 If two elements compare as equal, their order in the resulting sorted array is unspecified.
Returns
5 The qsort function returns no value.
7.24.6 [Integer arithmetic functions]
<IP_ADDRESS> [The abs, labs, and llabs functions]
1 Synopsis
#include <stdlib.h>
int abs(int j);
long int labs(long int j);
long long int llabs(long long int j);
Description
2 The abs, labs, and llabs functions compute the absolute value of an integer j. If the result cannot
be represented, the behavior is undefined[370] .
Returns
Footnote 370) The absolute value of the most negative number may not be representable.
3 The abs, labs, and llabs, functions return the absolute value.
<IP_ADDRESS> [The div, ldiv, and lldiv functions]
1 Synopsis
#include <stdlib.h>
div_t div(int numer, int denom);
ldiv_t ldiv(long int numer, long int denom);
lldiv_t lldiv(long long int numer, long long int denom);
Description
2 The div, ldiv, and lldiv, functions compute numer/denom and numer%denom in a single operation.
Returns
3 The div, ldiv, and lldiv functions return a structure of type div_t, ldiv_t, and lldiv_t, respec-
tively, comprising both the quotient and the remainder. The structures shall contain (in either order)
the members quot (the quotient) and rem (the remainder), each of which has the same type as
the arguments numer and denom. If either part of the result cannot be represented, the behavior is
undefined.
7.24.7 [Multibyte/wide character conversion functions]
1 The behavior of the multibyte character functions is affected by the LC_CTYPE category of the current
locale. For a state-dependent encoding, each of the mbtowc and wctomb functions is placed into its
initial conversion state prior to the first call to the function and can be returned to that state by a
call for which its character pointer argument, s, is a null pointer. Subsequent calls with s as other
than a null pointer cause the internal conversion state of the function to be altered as necessary. It is
implementation-defined whether internal conversion state has thread storage duration, and whether
a newly created thread has the same state as the current thread at the time of creation, or the initial
conversion state. A call with s as a null pointer causes these functions to return a nonzero value if
encodings have state dependency, and zero otherwise.
Changing the LC_CTYPE category causes the internal object describing the conversion state of the
mbtowc and wctomb functions to have an indeterminate representation.
<IP_ADDRESS> [The mblen function]
1 Synopsis
#include <stdlib.h>
int mblen(const char *s, size_t n);
Description
2 If s is not a null pointer, the mblen function determines the number of bytes contained in the
multibyte character pointed to by s. Except that the conversion state of the mbtowc function is not
affected, it is equivalent to
mbtowc((wchar_t *)0, (const char *)0, 0);
mbtowc((wchar_t *)0, s, n);
Returns
3 If s is a null pointer, the mblen function returns a nonzero or zero value, if multibyte character
encodings, respectively, do or do not have state-dependent encodings. If s is not a null pointer, the
mblen function either returns 0 (if s points to the null character), or returns the number of bytes
that are contained in the multibyte character (if the next n or fewer bytes form a valid multibyte
character), or returns-1 (if they do not form a valid multibyte character).
Forward references: the mbtowc function (<IP_ADDRESS>).
<IP_ADDRESS> [The mbtowc function]
1 Synopsis
#include <stdlib.h>
int mbtowc(wchar_t * restrict pwc, const char * restrict s, size_t n);
Description
2 If s is not a null pointer, the mbtowc function inspects at most n bytes beginning with the byte
pointed to by s to determine the number of bytes needed to complete the next multibyte character
(including any shift sequences). If the function determines that the next multibyte character is
complete and valid, it determines the value of the corresponding wide character and then, if pwc
is not a null pointer, stores that value in the object pointed to by pwc. If the corresponding wide
character is the null wide character, the function is left in the initial conversion state.
3 The implementation shall behave as if no library function calls the mbtowc function.
Returns
4 If s is a null pointer, the mbtowc function returns a nonzero or zero value, if multibyte character
encodings, respectively, do or do not have state-dependent encodings. If s is not a null pointer, the
mbtowc function either returns 0 (if s points to the null character), or returns the number of bytes
that are contained in the converted multibyte character (if the next n or fewer bytes form a valid
multibyte character), or returns-1 (if they do not form a valid multibyte character).
5 In no case will the value returned be greater than n or the value of the MB_CUR_MAX macro.
<IP_ADDRESS> [The wctomb function]
1 Synopsis
#include <stdlib.h>
int wctomb(char *s, wchar_t wc);
Description
2 The wctomb function determines the number of bytes needed to represent the multibyte character
corresponding to the wide character given by wc (including any shift sequences), and stores the
multibyte character representation in the array whose first element is pointed to by s (if s is not a
null pointer). At most MB_CUR_MAX characters are stored. If wc is a null wide character, a null byte is
stored, preceded by any shift sequence needed to restore the initial shift state, and the function is
left in the initial conversion state.
3 The implementation shall behave as if no library function calls the wctomb function.
Returns
4 If s is a null pointer, the wctomb function returns a nonzero or zero value, if multibyte character
encodings, respectively, do or do not have state-dependent encodings. If s is not a null pointer, the
wctomb function returns-1 if the value of wc does not correspond to a valid multibyte character, or
returns the number of bytes that are contained in the multibyte character corresponding to the value
of wc.
5 In no case will the value returned be greater than the value of the MB_CUR_MAX macro.
7.24.8 [Multibyte/wide string conversion functions]
1 The behavior of the multibyte string functions is affected by the LC_CTYPE category of the current
locale.
<IP_ADDRESS> [The mbstowcs function]
1 Synopsis
#include <stdlib.h>
size_t mbstowcs(wchar_t * restrict pwcs, const char * restrict s, size_t n);
Description
2 The mbstowcs function converts a sequence of multibyte characters that begins in the initial shift
state from the array pointed to by s into a sequence of corresponding wide characters and stores not
more than n wide characters into the array pointed to by pwcs. No multibyte characters that follow
a null character (which is converted into a null wide character) will be examined or converted. Each
multibyte character is converted as if by a call to the mbtowc function, except that the conversion
state of the mbtowc function is not affected.
3 No more than n elements will be modified in the array pointed to by pwcs. If copying takes place
between objects that overlap, the behavior is undefined.
Returns
4 If an invalid multibyte character is encountered, the mbstowcs function returns (size_t)(-1) .
Otherwise, the mbstowcs function returns the number of array elements modified, not including a
terminating null wide character, if any.[371]
Footnote 371) The array will not be null-terminated if the value returned is n.
<IP_ADDRESS> [The wcstombs function]
1 Synopsis
#include <stdlib.h>
size_t wcstombs(char * restrict s, const wchar_t * restrict pwcs, size_t n);
Description
2 The wcstombs function converts a sequence of wide characters from the array pointed to by pwcs
into a sequence of corresponding multibyte characters that begins in the initial shift state, and stores
these multibyte characters into the array pointed to by s, stopping if a multibyte character would
exceed the limit of n total bytes or if a null character is stored. Each wide character is converted
as if by a call to the wctomb function, except that the conversion state of the wctomb function is not
affected.
3 No more than n bytes will be modified in the array pointed to by s. If copying takes place between
objects that overlap, the behavior is undefined.
Returns
4 If a wide character is encountered that does not correspond to a valid multibyte character, the
wcstombs function returns (size_t)(-1) . Otherwise, the wcstombs function returns the number
of bytes modified, not including a terminating null character, if any.[371]
Footnote 371) The array will not be null-terminated if the value returned is n.
7.24.9 [Alignment of memory]
<IP_ADDRESS> [The memalignment function]
1 Synopsis
#include <stdlib.h>
size_t memalignment(const void * p);
Description
2 The memalignment function accepts a pointer to any object and returns the maximum alignment
satisfied by its address value. The alignment may be an extended alignment and may also be beyond
the range supported by the implementation for explicit use by alignas[372] . If so, it will satisfy all
alignments usable by the implementation. The value returned can be compared to the result of
alignof, and if it is greater or equal, the alignment requirement for the type operand is satisfied.
Returns
Footnote 372) The actual alignment of an object may be stricter than the alignment requested for an object by alignas or (implicitly) by
an allocation function, but will always satisfy it.
3 The alignment of the pointer p, which is a power of two. If p is a null pointer, an alignment of zero is
returned.
4 NOTE An alignment of zero indicates that the tested pointer cannot be used to access an object of any type.
7.25 [_Noreturn <stdnoreturn.h>]
1 The header <stdnoreturn.h> defines the macro
noreturn
which expands to _Noreturn .
2 The noreturn macro and the <stdnoreturn.h> header are obsolescent features.
7.26 [String handling <string.h>]
7.26.1 [String function conventions]
1 The header <string.h> declares one type and several functions, and defines one macro useful
for manipulating arrays of character type and other objects treated as arrays of character type.[373]
The type is size_t and the macro is NULL (both described in 7.21). Various methods are used for
determining the lengths of the arrays, but in all cases a char * or void * argument points to the
initial (lowest addressed) character of the array. If an array is accessed beyond the end of an object,
the behavior is undefined.
Footnote 373) See "future library directions" (7.33.17).
2 Where an argument declared as size_t n specifies the length of the array for a function, n can have
the value zero on a call to that function. Unless explicitly stated otherwise in the description of a
particular function in this subclause, pointer arguments on such a call shall still have valid values, as
described in 7.1.4. On such a call, a function that locates a character finds no occurrence, a function
that compares two character sequences returns zero, and a function that copies characters copies
zero characters.
3 For all functions in this subclause, each character shall be interpreted as if it had the type
unsigned char (and therefore every possible object representation is valid and has a different
value).
7.26.2 [Copying functions]
<IP_ADDRESS> [The memcpy function]
1 Synopsis
#include <string.h>
void *memcpy(void * restrict s1, const void * restrict s2, size_t n);
Description
2 The memcpy function copies n characters from the object pointed to by s2 into the object pointed to
by s1. If copying takes place between objects that overlap, the behavior is undefined.
Returns
3 The memcpy function returns the value of s1.
<IP_ADDRESS> [The memccpy function]
1 Synopsis
#include <string.h>
void *memccpy(void * restrict s1, const void * restrict s2, int c, size_t n);
Description
2 The memccpy function copies characters from the object pointed to by s2 into the object pointed to
by s1, stopping after the first occurrence of character c (converted to an unsigned char) is copied,
or after n characters are copied, whichever comes first. If copying takes place between objects that
overlap, the behavior is undefined.
Returns
3 The memccpy function returns a pointer to the character after the copy of c in s1, or a null pointer if
c was not found in the first n characters of s2.
<IP_ADDRESS> [The memmove function]
1 Synopsis
#include <string.h>
void *memmove(void *s1, const void *s2, size_t n);
Description
2 The memmove function copies n characters from the object pointed to by s2 into the object pointed to
by s1. Copying takes place as if the n characters from the object pointed to by s2 are first copied
into a temporary array of n characters that does not overlap the objects pointed to by s1 and s2, and
then the n characters from the temporary array are copied into the object pointed to by s1.
Returns
3 The memmove function returns the value of s1.
<IP_ADDRESS> [The strcpy function]
1 Synopsis
#include <string.h>
char *strcpy(char * restrict s1, const char * restrict s2);
Description
2 The strcpy function copies the string pointed to by s2 (including the terminating null character)
into the array pointed to by s1. If copying takes place between objects that overlap, the behavior is
undefined.
Returns
3 The strcpy function returns the value of s1.
<IP_ADDRESS> [The strncpy function]
1 Synopsis
#include <string.h>
char *strncpy(char * restrict s1, const char * restrict s2, size_t n);
Description
2 The strncpy function copies not more than n characters (characters that follow a null character are
not copied) from the array pointed to by s2 to the array pointed to by s1.[374] If copying takes place
between objects that overlap, the behavior is undefined.
Footnote 374) Thus, if there is no null character in the first n characters of the array pointed to by s2, the result will not be null-
terminated.
3 If the array pointed to by s2 is a string that is shorter than n characters, null characters are appended
to the copy in the array pointed to by s1, until n characters in all have been written.
Returns
4 The strncpy function returns the value of s1.
<IP_ADDRESS> [The strdup function]
1 Synopsis
#include <string.h>
char *strdup(const char *s);
Description
2 The strdup function creates a copy of the string pointed to by s in a space allocated as if by a call to
malloc.
Returns
3 The strdup function returns a pointer to the first character of the duplicate string. The returned
pointer can be passed to free. If no space can be allocated the strdup function returns a null pointer.
<IP_ADDRESS> [The strndup function]
1 Synopsis
#include <string.h>
char *strndup(const char *s, size_t size);
Description
2 The strndup function creates a string initialized with no more than size initial characters of the
array pointed to by s and up to the first null character, whichever comes first, in a space allocated
as if by a call to malloc. If the array pointed to by s does not contain a null within the first size
characters, a null is appended to the copy of the array.
Returns
3 The strndup function returns a pointer to the first character of the created string. The returned
pointer can be passed to free. If space cannot be allocated the strndup function returns a null
pointer.
7.26.3 [Concatenation functions]
<IP_ADDRESS> [The strcat function]
1 Synopsis
#include <string.h>
char *strcat(char * restrict s1, const char * restrict s2);
Description
2 The strcat function appends a copy of the string pointed to by s2 (including the terminating null
character) to the end of the string pointed to by s1. The initial character of s2 overwrites the null
character at the end of s1. If copying takes place between objects that overlap, the behavior is
undefined.
Returns
3 The strcat function returns the value of s1.
<IP_ADDRESS> [The strncat function]
1 Synopsis
#include <string.h>
char *strncat(char * restrict s1, const char * restrict s2, size_t n);
Description
2 The strncat function appends not more than n characters (a null character and characters that
follow it are not appended) from the array pointed to by s2 to the end of the string pointed to by
s1. The initial character of s2 overwrites the null character at the end of s1. A terminating null
character is always appended to the result.[375] If copying takes place between objects that overlap,
the behavior is undefined.
Returns
Footnote 375) Thus, the maximum number of characters that can end up in the array pointed to by s1 is strlen(s1)+n+1.
3 The strncat function returns the value of s1.
Forward references: the strlen function (<IP_ADDRESS>).
7.26.4 [Comparison functions]
1 The sign of a nonzero value returned by the comparison functions memcmp, strcmp, and strncmp
is determined by the sign of the difference between the values of the first pair of characters (both
interpreted as unsigned char) that differ in the objects being compared.
<IP_ADDRESS> [The memcmp function]
1 Synopsis
#include <string.h>
int memcmp(const void *s1, const void *s2, size_t n);
Description
2 The memcmp function compares the first n characters of the object pointed to by s1 to the first n
characters of the object pointed to by s2376) .
Returns
3 The memcmp function returns an integer greater than, equal to, or less than zero, accordingly as the
object pointed to by s1 is greater than, equal to, or less than the object pointed to by s2.
<IP_ADDRESS> [The strcmp function]
1 Synopsis
#include <string.h>
int strcmp(const char *s1, const char *s2);
Description
2 The strcmp function compares the string pointed to by s1 to the string pointed to by s2.
Returns
3 The strcmp function returns an integer 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.
<IP_ADDRESS> [The strcoll function]
1 Synopsis
#include <string.h>
int strcoll(const char *s1, const char *s2);
Description
2 The strcoll function compares the string pointed to by s1 to the string pointed to by s2, both
interpreted as appropriate to the LC_COLLATE category of the current locale.
Returns
3 The strcoll function returns an integer 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 when both
are interpreted as appropriate to the current locale.
<IP_ADDRESS> [The strncmp function]
1 Synopsis
#include <string.h>
int strncmp(const char *s1, const char *s2, size_t n);
Description
2 The strncmp function compares not more than n characters (characters that follow a null character
are not compared) from the array pointed to by s1 to the array pointed to by s2.
Returns
3 The strncmp function returns an integer greater than, equal to, or less than zero, accordingly as the
possibly null-terminated array pointed to by s1 is greater than, equal to, or less than the possibly
null-terminated array pointed to by s2.
<IP_ADDRESS> [The strxfrm function]
1 Synopsis
#include <string.h>
size_t strxfrm(char * restrict s1, const char * restrict s2, size_t n);
Description
2 The strxfrm function transforms the string pointed to by s2 and places the resulting string into
the array pointed to by s1. The transformation is such that if the strcmp function is applied to two
transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the
result of the strcoll function applied to the same two original strings. No more than n characters
are placed into the resulting array pointed to by s1, including the terminating null character. If n is
zero, s1 is permitted to be a null pointer. If copying takes place between objects that overlap, the
behavior is undefined.
Returns
3 The strxfrm function returns the length of the transformed string (not including the terminating
null character). If the value returned is n or more, the members of the array pointed to by s1 have
an indeterminate representation.
4 EXAMPLE The value of the following expression is the size of the array needed to hold the transformation of the string
pointed to by s.
1 + strxfrm(NULL, s, 0)
7.26.5 [Search functions]
<IP_ADDRESS> [Introduction]
1 The stateless search functions in this section (memchr, strchr, strpbrk, strrchr, strstr) are
generic functions. These functions are generic in the qualification of the array to be searched and
will return a result pointer to an element with the same qualification as the passed array. If the array
to be searched is const- qualified, the result pointer will be to a const-qualified element. If the array
to be searched is not const-qualified[377] , the result pointer will be to an unqualified element.
Footnote 377) The null pointer constant is not a pointer to a const-qualified type, and therefore the result expression has the type of a
pointer to an unqualified element; however, evaluating such a call is undefined.
2 The external declarations of these generic functions have a concrete function type that returns a
pointer to an unqualified element (of type char when specified as QChar, and void when specified
as QVoid), and accepts a pointer to a const-qualified array of the same type to search. This signature
supports all correct uses. If a macro definition of any of these generic functions is suppressed in
order to access an actual function, the external declaration with the corresponding concrete type is
visible[378] .
Footnote 378) This is an obsolescent feature.
3 The volatile and restrict qualifiers are not accepted on the elements of the array to search.
<IP_ADDRESS> [The memchr generic function]
1 Synopsis
#include <string.h>
QVoid *memchr(QVoid *s, int c, size_t n);
Description
2 The memchr generic function locates the first occurrence of c (converted to an unsigned char)
in the initial n characters (each interpreted as unsigned char) of the object pointed to by s. The
implementation shall behave as if it reads the characters sequentially and stops as soon as a matching
character is found.
Returns
3 The memchr generic function returns a pointer to the located character, or a null pointer if the
character does not occur in the object.
<IP_ADDRESS> [The strchr generic function]
1 Synopsis
#include <string.h>
QChar *strchr(QChar *s, int c);
Description
2 The strchr generic function locates the first occurrence of c (converted to a char) in the string
pointed to by s. The terminating null character is considered to be part of the string.
Returns
3 The strchr generic function returns a pointer to the located character, or a null pointer if the
character does not occur in the string.
<IP_ADDRESS> [The strcspn function]
1 Synopsis
#include <string.h>
size_t strcspn(const char *s1, const char *s2);
Description
2 The strcspn function computes the length of the maximum initial segment of the string pointed to
by s1 which consists entirely of characters not from the string pointed to by s2.
Returns
3 The strcspn function returns the length of the segment.
<IP_ADDRESS> [The strpbrk generic function]
1 Synopsis
#include <string.h>
QChar *strpbrk(QChar *s1, const char *s2);
Description
2 The strpbrk generic function locates the first occurrence in the string pointed to by s1 of any
character from the string pointed to by s2.
Returns
3 The
tcodestrpbrk generic function returns a pointer to the character, or a null pointer if no character from
s2 occurs in s1.
<IP_ADDRESS> [The strrchr generic function]
1 Synopsis
#include <string.h>
QChar *strrchr(QChar *s, int c);
Description
2 The strrchr generic function locates the last occurrence of c (converted to a char) in the string
pointed to by s. The terminating null character is considered to be part of the string.
Returns
3 The strrchr generic function returns a pointer to the character, or a null pointer if c does not occur
in the string.
<IP_ADDRESS> [The strspn function]
1 Synopsis
#include <string.h>
size_t strspn(const char *s1, const char *s2);
Description
2 The strspn function computes the length of the maximum initial segment of the string pointed to
by s1 which consists entirely of characters from the string pointed to by s2.
Returns
3 The strspn function returns the length of the segment.
<IP_ADDRESS> [The strstr generic function]
1 Synopsis
#include <string.h>
QChar *strstr(QChar *s1, const char *s2);
Description
2 The strstr generic function locates the first occurrence in the string pointed to by s1 of the sequence
of characters (excluding the terminating null character) in the string pointed to by s2.
Returns
3 The strstr generic function returns a pointer to the located string, or a null pointer if the string is
not found. If s2 points to a string with zero length, the function returns s1.
<IP_ADDRESS> [The strtok function]
1 Synopsis
#include <string.h>
char *strtok(char * restrict s1, const char * restrict s2);
Description
2 A sequence of calls to the strtok function breaks the string pointed to by s1 into a sequence of
tokens, each of which is delimited by a character from the string pointed to by s2. The first call
in the sequence has a non-null first argument; subsequent calls in the sequence have a null first
argument. If any of the subsequent calls in the sequence is made by a different thread than the first,
the behavior is undefined. The separator string pointed to by s2 may be different from call to call.
3 The first call in the sequence searches the string pointed to by s1 for the first character that is not
contained in the current separator string pointed to by s2. If no such character is found, then there
are no tokens in the string pointed to by s1 and the strtok function returns a null pointer. If such a
character is found, it is the start of the first token.
4 The strtok function then searches from there for a character that is contained in the current separator
string. If no such character is found, the current token extends to the end of the string pointed to by
s1, and subsequent searches for a token will return a null pointer. If such a character is found, it is
overwritten by a null character, which terminates the current token. The strtok function saves a
pointer to the following character, from which the next search for a token will start.
5 Each subsequent call, with a null pointer as the value of the first argument, starts searching from the
saved pointer and behaves as described above.
6 The strtok function is not required to avoid data races with other calls to the strtok function.[379]
The implementation shall behave as if no library function calls the strtok function.
Returns
Footnote 379) The strtok_s function can be used instead to avoid data races.
7 The strtok function returns a pointer to the first character of a token, or a null pointer if there is no
token.
8 EXAMPLE
#include <string.h>
static char str[] = "?a???b,,,#c";
char *t;
t = strtok(str, "?"); // t points to the token "a"
t = strtok(NULL, ","); // t points to the token "??b"
t = strtok(NULL, "#,"); // t points to the token "c"
t = strtok(NULL, "?"); // t is a null pointer
Forward references: The strtok_s function (K.<IP_ADDRESS>).
7.26.6 [Miscellaneous functions]
<IP_ADDRESS> [The memset function]
1 Synopsis
#include <string.h>
void *memset(void *s, int c, size_t n);
Description
2 The memset function copies the value of c (converted to an unsigned char) into each of the first n
characters of the object pointed to by s.
Returns
3 The memset function returns the value of s.
<IP_ADDRESS> [The memset_explicit function]
1 Synopsis
#include <string.h>
void *memset_explicit(void *s, int c, size_t n);
Description
2 The memset_explicit function copies the value of c (converted to an unsigned char) into each of
the first n characters of the object pointed to by s. The purpose of this function is to make sensitive
information stored in the object inaccessible[380] .
Returns
Footnote 380) The intention is that the memory store is always performed (i.e., never elided), regardless of optimizations. This is in
contrast to calls to the memset function (<IP_ADDRESS>)
3 The memset_explicit function returns the value of s.
<IP_ADDRESS> [The strerror function]
1 Synopsis
#include <string.h>
char *strerror(int errnum);
Description
2 The strerror function maps the number in errnum to a message string. Typically, the values for
errnum come from errno, but strerror shall map any value of type int to a message.
3 The strerror function is not required to avoid data races with other calls to the strerror func-
tion.[381] The implementation shall behave as if no library function calls the strerror function.
Returns
Footnote 381) The strerror_s function can be used instead to avoid data races.
4 The strerror function returns a pointer to the string, the contents of which are locale-specific. The
array pointed to shall not be modified by the program. The behavior is undefined if the returned
value is used after a subsequent call to the strerror function, or after the thread which called the
function to obtain the returned value has exited.
Forward references: The strerror_s function (K.<IP_ADDRESS>).
<IP_ADDRESS> [The strlen function]
1 Synopsis
#include <string.h>
size_t strlen(const char *s);
Description
2 The strlen function computes the length of the string pointed to by s.
Returns
3 The strlen function returns the number of characters that precede the terminating null character.
7.27 [Type-generic math <tgmath.h>]
1 The header <tgmath.h> includes the headers <math.h> and <complex.h> and defines several
type-generic macros.
2 The feature test macro __STDC_VERSION_TGMATH_H__ expands to the token 202311L.
3 This clause specifies a many-to-one correspondence of functions in <math.h> and <complex.h> with
type-generic macros.[382] Use of a type-generic macro invokes a corresponding function whose type is
determined by the types of the arguments for particular parameters called the generic parameters.[383]
Footnote 382) Like other function-like macros in standard libraries, each type-generic macro can be suppressed to make available the
corresponding ordinary function.
Footnote 383) If the type of the argument is not compatible with the type of the parameter for the selected function, the behavior is
undefined.
4 Of the <math.h> and <complex.h> functions without an f (float) or l (long double) suffix, several
have one or more parameters whose corresponding real type is double. For each such function,
except the functions that round result to narrower type (7.12.14) (which are covered below) and
modf,
there is a corresponding type-generic macro. The parameters whose corresponding real type is
double in the function synopsis are generic parameters.
5 Some of the <math.h> functions for decimal floating types have no unsuffixed counterpart. Of these
functions with a d64 suffix, some have one or more parameters whose type is _Decimal64 . For each
such function, except decodedecd64, encodedecd64, decodebind64, and encodebind64, there is a
corresponding type-generic macro. The parameters whose real type is _Decimal64 in the function
synopsis are generic parameters.
6 If arguments for generic parameters of a type-generic macro are such that some argument has a
corresponding real type that is of standard floating type and another argument is of decimal floating
type, the behavior is undefined.
7 Except for the macros for functions that round result to a narrower type (7.12.14), use of a type-
generic macro invokes a function whose generic parameters have the corresponding real type
determined by the types of the arguments for the generic parameters as follows:
— Arguments of integer type are regarded as having type _Decimal64 if any argument has
decimal floating type, and as having type double otherwise.
— If the function has exactly one generic parameter, the type determined is the corresponding
real type of the argument for the generic parameter.
— If the function has exactly two generic parameters, the type determined is the corresponding
real type determined by the usual arithmetic conversions (<IP_ADDRESS>) applied to the arguments for
the generic parameters.
— If the function has more than two generic parameters, the type determined is the corresponding
real type determined by repeatedly applying the usual arithmetic conversions, first to the first
two arguments for generic parameters, then to that result type and the next argument for a
generic parameter, and so forth until the usual arithmetic conversions have been applied to
the last argument for a generic parameter.
If neither <math.h> and <complex.h> define a function whose generic parameters have the deter-
mined corresponding real type, the behavior is undefined.
8 For each unsuffixed function in <math.h> for which there is a function in <complex.h> with the
same name except for a c prefix, the corresponding type-generic macro (for both functions) has the
same name as the function in <math.h>. The corresponding type-generic macro for fabs and cabs
is fabs.
<math.h> <complex.h> type-generic
function function macro
acos cacos acos
asin casin asin
atan catan atan
acosh cacosh acosh
asinh casinh asinh
atanh catanh atanh
cos ccos cos
sin csin sin
tan ctan tan
cosh ccosh cosh
sinh csinh sinh
tanh ctanh tanh
exp cexp exp
log clog log
pow cpow pow
sqrt csqrt sqrt
fabs cabs fabs
If at least one argument for a generic parameter is complex, then use of the macro invokes a complex
function; otherwise, use of the macro invokes a real function.
9 For each unsuffixed function in <math.h> without a c-prefixed counterpart in <complex.h> (except
functions that round result to narrower type, modf, and canonicalize), the corresponding type-
generic macro has the same name as the function. These type-generic macros are:
acospi exp2 fmod log2 rootn
asinpi expm1 frexp logb roundeven
atan2pi fdim fromfpx logp1 round
atan2 floor fromfp lrint rsqrt
atanpi fmax hypot lround scalbln
cbrt fmaximum ilogb nearbyint scalbn
ceil fmaximum_mag ldexp nextafter sinpi
compoundn fmaximum_num lgamma nextdown tanpi
copysign fmaximum_mag_num llogb nexttoward tgamma
cospi fma llrint nextup trunc
erfc fmin llround pown ufromfpx
erf fminimum log10p1 powr ufromfp
exp10m1 fminimum_mag log10 remainder
exp10 fminimum_num log1p remquo
exp2m1 fminimum_mag_num log2p1 rint
If all arguments for generic parameters are real, then use of the macro invokes a real function
(provided <math.h> defines a function of the determined type); otherwise, use of the macro is
undefined.
10 For each unsuffixed function in <complex.h> that is not a c-prefixed counterpart to a function
in <math.h>, the corresponding type-generic macro has the same name as the function. These
type-generic macros are:
carg cimag conj cproj creal
Use of the macro with any argument of standard floating or complex type invokes a complex
function. Use of the macro with an argument of decimal floating type is undefined.
11 The functions that round result to a narrower type have type-generic macros whose names are
obtained by omitting any suffix from the function names. Thus, the macros with f or d prefix are:
fadd fsub fmul fdiv ffma fsqrt
dadd dsub dmul ddiv dfma dsqrt
and the macros with d32 or d64 prefix are:
d32add d32sub d32mul d32div d32fma d32sqrt
d64add d64sub d64mul d64div d64fma d64sqrt
All arguments shall be real. If the macro prefix is f or d, use of an argument of decimal floating
type is undefined. If the macro prefix is d32 or d64, use of an argument of standard floating type is
undefined. The function invoked is determined as follows:
— If any argument has type _Decimal128 , or if the macro prefix is d64, the function invoked has
the name of the macro, with a d128 suffix.
— Otherwise, if the macro prefix is d32, the function invoked has the name of the macro, with a
d64 suffix.
— Otherwise, if any argument has type long double, or if the macro prefix is d, the function
invoked has the name of the macro, with an l suffix.
— Otherwise, the function invoked has the name of the macro (with no suffix).
12 For each d64-suffixed function in <math.h>, except decodedecd64, encodedecd64, decodebind64,
and encodebind64, that does not have an unsuffixed counterpart, the corresponding type-generic
macro has the name of the function, but without the suffix. These type-generic macros are:
<math.h> type-generic
function macro
quantizedN quantize
samequantumdN samequantum
quantumdN quantum
llquantexpdN llquantexp
Use of the macro with an argument of standard floating or complex type or with only integer type
arguments is undefined.
13 A type-generic macro corresponding to a function indicated in the table in 7.6.2 is affected by
constant rounding modes (7.6.4).
14 NOTE The type-generic macro definition in the example in <IP_ADDRESS> does not conform to this specification. A conforming
macro could be implemented as follows:
#define cbrt(X) \
_Generic((X), \
long double: _Roundwise_cbrtl, \
default: _Roundwise_cbrt, \
float: _Roundwise_cbrtf \
)(X)
where where _Roundwise_cbrtl , _Roundwise_cbrt , and _Roundwise_cbrtf are pointers to functions that are equivalent
to cbrtl, cbrt, and cbrtf, respectively, but that are guaranteed to be affected by constant rounding modes (7.6.2).
15 EXAMPLE With the declarations
#include <tgmath.h>
int n;
float f;
double d;
long double ld;
float complex fc;
double complex dc;
long double complex ldc;
#ifdef __STDC_IEC_60559_DFP__
_Decimal32 d32;
_Decimal64 d64;
_Decimal128 d128;
#endif
functions invoked by use of type-generic macros are shown in the following table:
macro use invocation
exp(n) exp(n) , the function
acosh(f) acoshf(f)
sin(d) sin(d) , the function
atan(ld) atanl(ld)
log(fc) clogf(fc)
sqrt(dc) csqrt(dc)
pow(ldc, f) cpowl(ldc, f)
remainder(n, n) remainder(n, n) , the function
nextafter(d, f) nextafter(d, f) , the function
nexttoward(f, ld) nexttowardf(f, ld)
copysign(n, ld) copysignl(n, ld)
ceil(fc) undefined
rint(dc) undefined
fmaximum(ldc, ld) undefined
carg(n) carg(n) , the function
cproj(f) cprojf(f)
creal(d) creal(d) , the function
cimag(ld) cimagl(ld)
fabs(fc) cabsf(fc)
carg(dc) carg(dc) , the function
cproj(ldc) cprojl(ldc)
fsub(f, ld) fsubl(f, ld)
fdiv(d, n) fdiv(d, n) , the function
dfma(f, d, ld) dfmal(f, d, ld)
dadd(f, f) daddl(f, f)
dsqrt(dc) undefined
exp(d64) expd64(d64)
sqrt(d32) sqrtd32(d32)
fmaximum(d64, d128) fmaximumd128(d64, d128)
pow(d32, n) powd64(d32, n)
remainder(d64, d) undefined
creal(d64) undefined
remquo(d32, d32, &n) undefined
llquantexp(d) undefined
quantize(dc) undefined
samequantum(n, n) undefined
d32sub(d32, d128) d32subd128(d32, d128)
d32div(d64, n) d32divd64(d64, n)
d64fma(d32, d64, d128) d64fmad128(d32, d64, d128)
d64add(d32, d32) d64addd128(d32, d32)
d64sqrt(d) undefined
dadd(n, d64) undefined
acospi
asinpi
atan2pi
atan2
atanpi
cbrt
ceil
compoundn
copysign
cospi
erfc
erf
exp10m1
exp10
exp2m1
exp2
expm1
fdim
floor
fmax
fmaximum
fmaximum_mag
fmaximum_num
fmaximum_mag_num
fma
fmin
fminimum
fminimum_mag
fminimum_num
fminimum_mag_num
fmod
frexp
fromfpx
fromfp
hypot
ilogb
ldexp
lgamma
llogb
llrint
llround
log10p1
log10
log1p
log2p1
log2
logb
logp1
lrint
lround
nearbyint
nextafter
nextdown
nexttoward
nextup
pown
powr
remainder
remquo
rint
rootn
roundeven
round
rsqrt
scalbln
scalbn
sinpi
tanpi
tgamma
trunc
ufromfpx
ufromfp carg
cimag
conj
cproj
creal d32add
d64add
d32sub
d64sub
d32mul
d64mul
d32div
d64div
d32fma
d64fma
d32sqrt
d64sqrt fadd
dadd
fsub
dsub
fmul
dmul
fdiv
ddiv
ffma
dfma
fsqrt
dsqrt
7.28 [Threads <threads.h>]
7.28.1 [Introduction]
1 The header <threads.h> includes the header <time.h>, defines macros, and declares types, enu-
meration constants, and functions that support multiple threads of execution[384] .
Footnote 384) See "future library directions" (7.33.19).
2 Implementations that define the macro __STDC_NO_THREADS__ need not provide this header nor
support any of its facilities.
3 The macros are
ONCE_FLAG_INIT
which expands to a value that can be used to initialize an object of type once_flag; and
TSS_DTOR_ITERATIONS
which expands to an integer constant expression representing the maximum number of times that
destructors will be called when a thread terminates.
4 The types are
cnd_t
which is a complete object type that holds an identifier for a condition variable;
thrd_t
which is a complete object type that holds an identifier for a thread;
tss_t
which is a complete object type that holds an identifier for a thread-specific storage pointer;
mtx_t
which is a complete object type that holds an identifier for a mutex;
tss_dtor_t
which is the function pointer type void (*)(void*), used for a destructor for a thread-specific
storage pointer;
thrd_start_t
which is the function pointer type int (*)(void*) that is passed to thrd_create to create a new
thread; and
once_flag
which is a complete object type that holds a flag for use by call_once.
5 The enumeration constants are
mtx_plain
which is passed to mtx_init to create a mutex object that does not support timeout;
mtx_recursive
which is passed to mtx_init to create a mutex object that supports recursive locking;
mtx_timed
which is passed to mtx_init to create a mutex object that supports timeout;
thrd_timedout
which is returned by a timed wait function to indicate that the time specified in the call was reached
without acquiring the requested resource;
thrd_success
which is returned by a function to indicate that the requested operation succeeded;
thrd_busy
which is returned by a function to indicate that the requested operation failed because a resource
requested by a test and return function is already in use;
thrd_error
which is returned by a function to indicate that the requested operation failed; and
thrd_nomem
which is returned by a function to indicate that the requested operation failed because it was unable
to allocate memory.
Forward references: date and time (7.29).
7.28.2 [Initialization functions]
<IP_ADDRESS> [The call_once function]
1 Synopsis
#include <threads.h>
void call_once(once_flag *flag, void (*func)(void));
Description
2 The call_once function uses the once_flag pointed to by flag to ensure that func is called exactly
once, the first time the call_once function is called with that value of flag. Completion of an
effective call to the call_once function synchronizes with all subsequent calls to the call_once
function with the same value of flag.
Returns
3 The call_once function returns no value.
7.28.3 [Condition variable functions]
<IP_ADDRESS> [The cnd_broadcast function]
1 Synopsis
#include <threads.h>
int cnd_broadcast(cnd_t *cond);
Description
2 The cnd_broadcast function unblocks all of the threads that are blocked on the condition variable
pointed to by cond at the time of the call. If no threads are blocked on the condition variable pointed
to by cond at the time of the call, the function does nothing.
Returns
3 The cnd_broadcast function returns thrd_success on success, or thrd_error if the request could
not be honored.
<IP_ADDRESS> [The cnd_destroy function]
1 Synopsis
#include <threads.h>
void cnd_destroy(cnd_t *cond);
Description
2 The cnd_destroy function releases all resources used by the condition variable pointed to by cond.
The cnd_destroy function requires that no threads be blocked waiting for the condition variable
pointed to by cond.
Returns
3 The cnd_destroy function returns no value.
<IP_ADDRESS> [The cnd_init function]
1 Synopsis
#include <threads.h>
int cnd_init(cnd_t *cond);
Description
2 The cnd_init function creates a condition variable. If it succeeds it sets the variable pointed to by
cond to a value that uniquely identifies the newly created condition variable. A thread that calls
cnd_wait on a newly created condition variable will block.
Returns
3 The cnd_init function returns thrd_success on success, or thrd_nomem if no memory could be
allocated for the newly created condition, or thrd_error if the request could not be honored.
<IP_ADDRESS> [The cnd_signal function]
1 Synopsis
#include <threads.h>
int cnd_signal(cnd_t *cond);
Description
2 The cnd_signal function unblocks one of the threads that are blocked on the condition variable
pointed to by cond at the time of the call. If no threads are blocked on the condition variable at the
time of the call, the function does nothing and returns success.
Returns
3 The cnd_signal function returns thrd_success on success or thrd_error if the request could not
be honored.
<IP_ADDRESS> [The cnd_timedwait function]
1 Synopsis
#include <threads.h>
int cnd_timedwait(cnd_t *restrict cond, mtx_t *restrict mtx,
const struct timespec *restrict ts);
Description
2 The cnd_timedwait function atomically unlocks the mutex pointed to by mtx and blocks until the
condition variable pointed to by cond is signaled by a call to cnd_signal or to cnd_broadcast, or
until after the TIME_UTC-based calendar time pointed to by ts, or until it is unblocked due to an
unspecified reason. When the calling thread becomes unblocked it locks the variable pointed to by
mtx before it returns. The cnd_timedwait function requires that the mutex pointed to by mtx be
locked by the calling thread.
Returns
3 The cnd_timedwait function returns thrd_success upon success, or thrd_timedout if the time
specified in the call was reached without acquiring the requested resource, or thrd_error if the
request could not be honored.
<IP_ADDRESS> [The cnd_wait function]
1 Synopsis
#include <threads.h>
int cnd_wait(cnd_t *cond, mtx_t *mtx);
Description
2 The cnd_wait function atomically unlocks the mutex pointed to by mtx and blocks until the condi-
tion variable pointed to by cond is signaled by a call to cnd_signal or to cnd_broadcast, or until it
is unblocked due to an unspecified reason. When the calling thread becomes unblocked it locks the
mutex pointed to by mtx before it returns. The cnd_wait function requires that the mutex pointed
to by mtx be locked by the calling thread.
Returns
3 The cnd_wait function returns thrd_success on success or thrd_error if the request could not be
honored.
7.28.4 [Mutex functions]
1 For purposes of determining the existence of a data race, lock and unlock operations behave as
atomic operations. All lock and unlock operations on a particular mutex occur in some particular
total order.
2 NOTE This total order can be viewed as the modification order of the mutex.
<IP_ADDRESS> [The mtx_destroy function]
1 Synopsis
#include <threads.h>
void mtx_destroy(mtx_t *mtx);
Description
2 The mtx_destroy function releases any resources used by the mutex pointed to by mtx. No threads
can be blocked waiting for the mutex pointed to by mtx.
Returns
3 The mtx_destroy function returns no value.
<IP_ADDRESS> [The mtx_init function]
1 Synopsis
#include <threads.h>
int mtx_init(mtx_t *mtx, int type);
Description
2 The mtx_init function creates a mutex object with properties indicated by type, which shall have
one of these values:
mtx_plain for a simple non-recursive mutex,
mtx_timed for a non-recursive mutex that supports timeout,
mtx_plain | mtx_recursive for a simple recursive mutex, or
mtx_timed | mtx_recursive for a recursive mutex that supports timeout.
3 If the mtx_init function succeeds, it sets the mutex pointed to by mtx to a value that uniquely
identifies the newly created mutex.
Returns
4 The mtx_init function returns thrd_success on success, or thrd_error if the request could not
be honored.
<IP_ADDRESS> [The mtx_lock function]
1 Synopsis
#include <threads.h>
int mtx_lock(mtx_t *mtx);
Description
2 The mtx_lock function blocks until it locks the mutex pointed to by mtx. If the mutex is non-
recursive, it shall not be locked by the calling thread. Prior calls to mtx_unlock on the same mutex
synchronize with this operation.
Returns
3 The mtx_lock function returns thrd_success on success, or thrd_error if the request could not
be honored.
<IP_ADDRESS> [The mtx_timedlock function]
1 Synopsis
#include <threads.h>
int mtx_timedlock(mtx_t *restrict mtx, const struct timespec *restrict ts);
Description
2 The mtx_timedlock function endeavors to block until it locks the mutex pointed to by mtx or
until after the TIME_UTC-based calendar time pointed to by ts. The specified mutex shall support
timeout. If the operation succeeds, prior calls to mtx_unlock on the same mutex synchronize with
this operation.
Returns
3 The mtx_timedlock function returns thrd_success on success, or thrd_timedout if the time
specified was reached without acquiring the requested resource, or thrd_error if the request could
not be honored.
<IP_ADDRESS> [The mtx_trylock function]
1 Synopsis
#include <threads.h>
int mtx_trylock(mtx_t *mtx);
Description
2 The mtx_trylock function endeavors to lock the mutex pointed to by mtx. If the mutex is already
locked, the function returns without blocking. If the operation succeeds, prior calls to mtx_unlock
on the same mutex synchronize with this operation.
Returns
3 The mtx_trylock function returns thrd_success on success, or thrd_busy if the resource requested
is already in use, or thrd_error if the request could not be honored. mtx_trylock may spuriously
fail to lock an unused resource, in which case it returns thrd_busy.
<IP_ADDRESS> [The mtx_unlock function]
1 Synopsis
#include <threads.h>
int mtx_unlock(mtx_t *mtx);
Description
2 The mtx_unlock function unlocks the mutex pointed to by mtx. The mutex pointed to by mtx shall
be locked by the calling thread.
Returns
3 The mtx_unlock function returns thrd_success on success or thrd_error if the request could not
be honored.
7.28.5 [Thread functions]
<IP_ADDRESS> [The thrd_create function]
1 Synopsis
#include <threads.h>
int thrd_create(thrd_t *thr, thrd_start_t func, void *arg);
Description
2 The thrd_create function creates a new thread executing func(arg). If the thrd_create function
succeeds, it sets the object pointed to by thr to the identifier of the newly created thread. (A thread’s
identifier may be reused for a different thread once the original thread has exited and either been
detached or joined to another thread.) The completion of the thrd_create function synchronizes
with the beginning of the execution of the new thread.
3 Returning from func has the same behavior as invoking thrd_exit with the value returned from
func.
Returns
4 The thrd_create function returns thrd_success on success, or thrd_nomem if no memory could
be allocated for the thread requested, or thrd_error if the request could not be honored.
<IP_ADDRESS> [The thrd_current function]
1 Synopsis
#include <threads.h>
thrd_t thrd_current(void);
Description
2 The thrd_current function identifies the thread that called it.
Returns
3 The thrd_current function returns the identifier of the thread that called it.
<IP_ADDRESS> [The thrd_detach function]
1 Synopsis
#include <threads.h>
int thrd_detach(thrd_t thr);
Description
2 The thrd_detach function tells the operating system to dispose of any resources allocated to the
thread identified by thr when that thread terminates. The thread identified by thr shall not have
been previously detached or joined with another thread.
Returns
3 The thrd_detach function returns thrd_success on success or thrd_error if the request could
not be honored.
<IP_ADDRESS> [The thrd_equal function]
1 Synopsis
#include <threads.h>
int thrd_equal(thrd_t thr0, thrd_t thr1);
Description
2 The thrd_equal function will determine whether the thread identified by thr0 refers to the thread
identified by thr1.
Returns
3 The thrd_equal function returns zero if the thread thr0 and the thread thr1 refer to different
threads. Otherwise the thrd_equal function returns a nonzero value.
<IP_ADDRESS> [The thrd_exit function]
1 Synopsis
#include <threads.h>
[[noreturn]] void thrd_exit(int res);
Description
2 For every thread-specific storage key which was created with a non-null destructor and for which
the value is non-null, thrd_exit sets the value associated with the key to a null pointer value and
then invokes the destructor with its previous value. The order in which destructors are invoked is
unspecified.
3 If after this process there remain keys with both non-null destructors and values, the implementation
repeats this process up to TSS_DTOR_ITERATIONS times.
4 Following this, the thrd_exit function terminates execution of the calling thread and sets its result
code to res.
5 The program terminates normally after the last thread has been terminated. The behavior is as if the
program called the exit function with the status EXIT_SUCCESS at thread termination time.
Returns
6 The thrd_exit function returns no value.
<IP_ADDRESS> [The thrd_join function]
1 Synopsis
#include <threads.h>
int thrd_join(thrd_t thr, int *res);
Description
2 The thrd_join function joins the thread identified by thr with the current thread by blocking until
the other thread has terminated. If the parameter res is not a null pointer, it stores the thread’s result
code in the integer pointed to by res. The termination of the other thread synchronizes with the
completion of the thrd_join function. The thread identified by thr shall not have been previously
detached or joined with another thread.
Returns
3 The thrd_join function returns thrd_success on success or thrd_error if the request could not
be honored.
<IP_ADDRESS> [The thrd_sleep function]
1 Synopsis
#include <threads.h>
int thrd_sleep(const struct timespec *duration, struct timespec *remaining);
Description
2 The thrd_sleep function suspends execution of the calling thread until either the interval specified
by duration has elapsed or a signal which is not being ignored is received. If interrupted by a signal
and the remaining argument is not null, the amount of time remaining (the requested interval
minus the time actually slept) is stored in the interval it points to. The duration and remaining
arguments may point to the same object.
3 The suspension time may be longer than requested because the interval is rounded up to an integer
multiple of the sleep resolution or because of the scheduling of other activity by the system. But,
except for the case of being interrupted by a signal, the suspension time will not be less than that
specified, as measured by the system clock TIME_UTC.
Returns
4 The thrd_sleep function returns zero if the requested time has elapsed, −1 if it has been interrupted
by a signal, or a negative value (which may also be −1) if it fails.
<IP_ADDRESS> [The thrd_yield function]
1 Synopsis
#include <threads.h>
void thrd_yield(void);
Description
2 The thrd_yield function endeavors to permit other threads to run, even if the current thread would
ordinarily continue to run.
Returns
3 The thrd_yield function returns no value.
7.28.6 [Thread-specific storage functions]
<IP_ADDRESS> [The tss_create function]
1 Synopsis
#include <threads.h>
int tss_create(tss_t *key, tss_dtor_t dtor);
Description
2 The tss_create function creates a thread-specific storage pointer with destructor dtor, which may
be null.
3 A null pointer value is associated with the newly created key in all existing threads. Upon subsequent
thread creation, the value associated with all keys is initialized to a null pointer value in the new
thread.
4 Destructors associated with thread-specific storage are not invoked at program termination.
5 The tss_create function shall not be called from within a destructor.
Returns
6 If the tss_create function is successful, it sets the thread-specific storage pointed to by key to a
value that uniquely identifies the newly created pointer and returns thrd_success; otherwise,
thrd_error is returned and the thread-specific storage pointed to by key is set to an indeterminate
representation.
<IP_ADDRESS> [The tss_delete function]
1 Synopsis
#include <threads.h>
void tss_delete(tss_t key);
Description
2 The tss_delete function releases any resources used by the thread-specific storage identified by
key. The tss_delete function shall only be called with a value for key that was returned by a call
to tss_create before the thread commenced executing destructors.
3 If tss_delete is called while another thread is executing destructors, whether this will affect the
number of invocations of the destructor associated with key on that thread is unspecified.
4 Calling tss_delete will not result in the invocation of any destructors.
Returns
5 The tss_delete function returns no value.
<IP_ADDRESS> [The tss_get function]
1 Synopsis
#include <threads.h>
void *tss_get(tss_t key);
Description
2 The tss_get function returns the value for the current thread held in the thread-specific storage
identified by key. The tss_get function shall only be called with a value for key that was returned
by a call to tss_create before the thread commenced executing destructors.
Returns
3 The tss_get function returns the value for the current thread if successful, or zero if unsuccessful.
<IP_ADDRESS> [The tss_set function]
1 Synopsis
#include <threads.h>
int tss_set(tss_t key, void *val);
Description
2 The tss_set function sets the value for the current thread held in the thread-specific storage
identified by key to val. The tss_set function shall only be called with a value for key that was
returned by a call to tss_create before the thread commenced executing destructors.
3 This action will not invoke the destructor associated with the key on the value being replaced.
Returns
4 The tss_set function returns thrd_success on success or thrd_error if the request could not be
honored.
7.29 [Date and time <time.h>]
7.29.1 [Components of time]
1 The header <time.h> defines several macros, and declares types and functions for manipulating
time. Many functions deal with a calendar time that represents the current date (according to the
Gregorian calendar) and time. Some functions deal with local time, which is the calendar time
expressed for some specific time zone, and with Daylight Saving Time, which is a temporary change
in the algorithm for determining local time. The local time zone and Daylight Saving Time are
implementation-defined.
2 The feature test macro __STDC_VERSION_TIME_H__ expands to the token 202311L. The other macros
defined are NULL (described in 7.21);
CLOCKS_PER_SEC
which expands to an expression with type clock_t (described below) that is the number per second
of the value returned by the clock function;
TIME_UTC
TIME_MONOTONIC
which expand to integer constants greater than 0 that designates the calendar time and monotonic
time bases, respectively. Additional time base macro definitions, beginning with TIME_ and an
uppercase letter, may also be specified by the implementation[385] ; and,
TIME_ACTIVE
TIME_THREAD_ACTIVE
which, if defined, expand to integer values, designating overall execution and thread-specific active
processing time bases, respectively.
Footnote 385) See future library directions (7.33). Implementations can define additional time bases, but are only required to support a
real time clock based on UTC.
3 The definition of macros for time bases other than TIME_UTC are optional. If defined, the correspond-
ing time bases are supported by timespec_get and timespec_getres, and their values are positive.
If defined, the value of the optional macro TIME_ACTIVE shall be different from the constants
TIME_UTC and TIME_MONOTONIC and shall not change during the same program invocation. The
optional macro TIME_THREAD_ACTIVE shall not be defined if the implementation does not support
threads; its value shall be different from TIME_UTC, TIME_MONOTONIC, and TIME_ACTIVE, it shall be
the same for all expansions of the macro for the same thread, and the value provided for one thread
shall not be used by a different thread as the base argument of timespec_get or timespec_getres.
4 The types declared are size_t (described in 7.21);
clock_t
and
time_t
which are real types capable of representing times;
struct timespec
which holds an interval specified in seconds and nanoseconds (which may represent a calendar time
based on a particular epoch); and
struct tm
which holds the components of a calendar time, called the broken-down time.
5 The range and precision of times representable in clock_t and time_t are implementation-defined.
The timespec structure shall contain at least the following members, in any order. The semantics of
the members and their normal ranges are expressed in the comments.[386]
time_t tv_sec; // whole seconds -- ≥ 0
long tv_nsec; // nanoseconds -- [0, 999999999]
The tm structure shall contain at least the following members, in any order. The semantics of the
members and their normal ranges are expressed in the comments.[387]
int tm_sec; // seconds after the minute -- [0, 60]
int tm_min; // minutes after the hour -- [0, 59]
int tm_hour; // hours since midnight -- [0, 23]
int tm_mday; // day of the month -- [1, 31]
int tm_mon; // months since January -- [0, 11]
int tm_year; // years since 1900
int tm_wday; // days since Sunday -- [0, 6]
int tm_yday; // days since January 1 -- [0, 365]
int tm_isdst; // Daylight Saving Time flag
The value of tm_isdst is positive if Daylight Saving Time is in effect, zero if Daylight Saving Time
is not in effect, and negative if the information is not available.
Footnote 386) The tv_sec member is a linear count of seconds and might not have the normal semantics of a time_t.
Footnote 387) The range [0, 60] for tm_sec allows for a positive leap second.
7.29.2 [Time manipulation functions]
<IP_ADDRESS> [The clock function]
1 Synopsis
#include <time.h>
clock_t clock(void);
Description
2 The clock function determines the processor time used.
Returns
3 The clock function returns the implementation’s best approximation of the active processing time
associated with the program execution since the beginning of an implementation-defined era related
only to the program invocation. To determine the time in seconds, the value returned by the clock
function should be divided by the value of the macro CLOCKS_PER_SEC. If the processor time used
is not available, the function returns the value (clock_t) (−1). If the value cannot be represented,
the function returns an unspecified value[388] .
Footnote 388) This could be due to overflow of the clock_t type.
<IP_ADDRESS> [The difftime function]
1 Synopsis
#include <time.h>
double difftime(time_t time1, time_t time0);
Description
2 The difftime function computes the difference between two calendar times: time1 - time0.
Returns
3 The difftime function returns the difference expressed in seconds as a double.
<IP_ADDRESS> [The mktime function]
1 Synopsis
#include <time.h>
time_t mktime(struct tm *timeptr);
Description
2 The mktime function converts the broken-down time, expressed as local time, in the structure
pointed to by timeptr into a calendar time value with the same encoding as that of the values
returned by the time function. The original values of the tm_wday and tm_yday components of the
structure are ignored, and the original values of the other components are not restricted to the ranges
indicated above. [389] On successful completion, the values of the tm_wday and tm_yday components
of the structure are set appropriately, and the other components are set to represent the specified
calendar time, but with their values forced to the ranges indicated above; the final value of tm_mday
is not set until tm_mon and tm_year are determined.
Returns
Footnote 389) Thus, a positive or zero value for tm_isdst causes the mktime function to presume initially that Daylight Saving Time,
respectively, is or is not in effect for the specified time. A negative value causes it to attempt to determine whether Daylight
Saving Time is in effect for the specified time.
3 The mktime function returns the specified calendar time encoded as a value of type time_t. If the
calendar time cannot be represented, the function returns the value (time_t) (−1).
4 EXAMPLE What day of the week is July 4, 2001?
#include <stdio.h>
#include <time.h>
static const char *const wday[] = {
"Sunday", "Monday", "Tuesday", "Wednesday",
"Thursday", "Friday", "Saturday", "-unknown-"
};
struct tm time_str;
/* ... */
time_str.tm_year = 2001 - 1900;
time_str.tm_mon = 7 - 1;
time_str.tm_mday = 4;
time_str.tm_hour = 0;
time_str.tm_min = 0;
time_str.tm_sec = 1;
time_str.tm_isdst = -1;
if (mktime(&time_str) == (time_t)(-1))
time_str.tm_wday = 7;
printf("%s\n", wday[time_str.tm_wday]);
<IP_ADDRESS> [The timegm function]
1 Synopsis
#include <time.h>
time_t timegm(struct tm *timeptr);
Description
2 The timegm function converts the broken-down time, expressed as UTC time, in the structure
pointed to by timeptr into a calendar time value with the same encoding as that of the values
returned by the time function. The original values of the tm_wday and tm_yday components of the
structure are ignored, and the original values of the other components are not restricted to the ranges
indicated above. On successful completion, the values of the tm_wday and tm_yday components
of the structure are set appropriately, and the other components are set to represent the specified
calendar time, but with their values forced to the ranges indicated above; the final value of tm_mday
is not set until tm_mon and tm_year are determined.
Returns
3 The timegm function returns the specified calendar time encoded as a value of type time_t. If the
calendar time cannot be represented, the function returns the value (time_t)(-1) .
<IP_ADDRESS> [The time function]
1 Synopsis
#include <time.h>
time_t time(time_t *timer);
Description
2 The time function determines the current calendar time. The encoding of the value is unspecified.
Returns
3 The time function returns the implementation’s best approximation to the current calendar time.
The value (time_t) (−1) is returned if the calendar time is not available. If timer is not a null
pointer, the return value is also assigned to the object it points to.
<IP_ADDRESS> [The timespec_get function]
1 Synopsis
#include <time.h>
int timespec_get(struct timespec *ts, int base);
Description
2 The timespec_get function sets the interval pointed to by ts to hold the current calendar time
based on the specified time base.
3 If base is TIME_UTC, the tv_sec member is set to the number of seconds since an implementation-
defined epoch, truncated to a whole value and the tv_nsec member is set to the integral num-
ber of nanoseconds, rounded to the resolution of the system clock[390] . The optional time base
TIME_MONOTONIC is the same, but the reference point is an implementation-defined time point;
different program invocations need not refer to the same reference points[391] . For the same program
invocation, the results of two calls to timespec_get with TIME_MONOTONIC such that the first hap-
pens before the second shall not be decreasing. It is implementation-defined if TIME_MONOTONIC
accounts for time during which the execution environment is suspended[392] . For the optional time
bases TIME_ACTIVE and TIME_THREAD_ACTIVE the result is similar, but the call measures the amount
of active processing time associated with the whole program invocation or with the calling thread,
respectively.
Returns
Footnote 390) Although a struct timespec object describes times with nanosecond resolution, the available resolution is system
dependent and could even be greater than 1 second.
Footnote 391) Commonly, this reference point is the boot time of the execution environment or the start of the execution.
Footnote 392) The execution environment may, for example, not be able to track physical time that elapsed during suspension in a low
power consumption mode.
4 If the timespec_get function is successful it returns the nonzero value base; otherwise, it returns
zero.
Recommended practice
5 It is recommended practice that timing results of calls to timespec_get with TIME_ACTIVE, if
defined, and of calls to clock are as close to each other as their types, value ranges, and resolutions
(obtained with timespec_getres and CLOCKS_PER_SEC, respectively) allow. Because of its wider
value range and improved indications on error, timespec_get with time base TIME_ACTIVE should
be used instead of clock by new code whenever possible.
<IP_ADDRESS> [The timespec_getres function]
1 Synopsis
#include <time.h>
int timespec_getres(struct timespec *ts, int base);
Description
2 If ts is non-null and base is supported by the timespec_get function, the timespec_getres
function returns the resolution of the time provided by the timespec_get function for base
in the timespec structure pointed to by ts. For each supported base, multiple calls to the
timespec_getres function during the same program execution shall have identical results.
Returns
3 If the value base is supported by the timespec_get function, the timespec_getres function returns
the nonzero value base; otherwise, it returns zero.
7.29.3 [Time conversion functions]
1 Functions with a _r suffix place the result of the conversion into the buffer referred by buf and
return that pointer. These functions and the function strftime shall not be subject to data races,
unless the time or calendar state is changed in a multi-thread execution.[393]
Footnote 393) This does not mean that these functions may not read global state that describes the time and calendar settings of the
execution, such as the LC_TIME locale or the implementation-defined specification of the local time zone. Only the setting of
that state by setlocale or by means of implementation-defined functions may constitute races.
2 Functions asctime, ctime, gmtime, and localtime are the same as their counterparts suffixed with
_r. In place of the parameter buf, these functions use a pointer to an object and return it: one or two
broken-down time structures (for gmtime and localtime) or an array of char (commonly used by
asctime and ctime). Execution of any of the functions that return a pointer to one of these static
objects may overwrite the information returned from any previous call to one of these functions that
uses the same object. These functions are not reentrant and are not required to avoid data races with
each other. Accessing the returned pointer after the thread that called the function that returned
it has exited results in undefined behavior. The implementation shall behave as if no other library
functions call these functions.
<IP_ADDRESS> [The asctime function]
1 Synopsis
#include <time.h>
[[deprecated]] char *asctime(const struct tm *timeptr);
Description
2 This function is obsolescent and should be avoided in new code.
3 The asctime function converts the broken-down time in the structure pointed to by timeptr into a
string in the form
Sun Sep 16 01:03:52 1973\n\0
using the equivalent of the following algorithm.
[[deprecated]] char *asctime(const struct tm *timeptr)
{
static const char wday_name[7][3] = {
"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"
};
static const char mon_name[12][3] = {
"Jan", "Feb", "Mar", "Apr", "May", "Jun",
"Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
};
static char result[26];
snprintf(result, 26, "%.3s %.3s%3d %.2d:%.2d:%.2d %d\n",
wday_name[timeptr->tm_wday],
mon_name[timeptr->tm_mon],
timeptr->tm_mday, timeptr->tm_hour,
timeptr->tm_min, timeptr->tm_sec,
1900 + timeptr->tm_year);
return result;
}
4 If any of the members of the broken-down time contain values that are outside their normal ranges[394] ,
the behavior of the asctime function is undefined. Likewise, if the calculated year exceeds four
digits or is less than the year 1000, the behavior is undefined.
Returns
Footnote 394) See 7.29.1.
5 The asctime function returns a pointer to the string.
<IP_ADDRESS> [The ctime function]
1 Synopsis
#include <time.h>
[[deprecated]] char *ctime(const time_t *timer);
Description
2 This function is obsolescent and should be avoided in new code.
3 The ctime function converts the calendar time pointed to by timer to local time in the form of a
string. They are equivalent to:
asctime(localtime(timer))
Returns
4 The ctime function returns the pointer returned by the asctime functions with that broken-down
time as argument.
Forward references: the localtime functions (<IP_ADDRESS>).
<IP_ADDRESS> [The gmtime functions]
1 Synopsis
#include <time.h>
struct tm *gmtime(const time_t *timer);
struct tm *gmtime_r(const time_t *timer, struct tm *buf);
Description
2 The gmtime functions convert the calendar time pointed to by timer into a broken-down time,
expressed as UTC.
Returns
3 The gmtime functions return a pointer to the broken-down time, or a null pointer if the specified
time cannot be converted to UTC.
<IP_ADDRESS> [The localtime functions]
1 Synopsis
#include <time.h>
struct tm *localtime(const time_t *timer);
struct tm *localtime_r(const time_t *timer, struct tm *buf);
Description
2 The localtime functions converts the calendar time pointed to by timer into a broken-down time,
expressed as local time.
Returns
3 The localtime functions return a pointer to the broken-down time, or a null pointer if the specified
time cannot be converted to local time.
<IP_ADDRESS> [The strftime function]
1 Synopsis
#include <time.h>
size_t strftime(char * restrict s, size_t maxsize, const char * restrict format,
const struct tm * restrict timeptr);
Description
2 The strftime function places characters into the array pointed to by s as controlled by the string
pointed to by format. The format shall be a multibyte character sequence, beginning and ending in
its initial shift state. The format string consists of zero or more conversion specifiers and ordinary
multibyte characters. A conversion specifier consists of a % character, possibly followed by an E or O
modifier character (described below), followed by a character that determines the behavior of the
conversion specifier. All ordinary multibyte characters (including the terminating null character) are
copied unchanged into the array. If copying takes place between objects that overlap, the behavior is
undefined. No more than maxsize characters are placed into the array.
3 Each conversion specifier shall be replaced by appropriate characters as described in the following
list. The appropriate characters shall be determined using the LC_TIME category of the current
locale and by the values of zero or more members of the broken-down time structure pointed to
by timeptr, as specified in brackets in the description. If any of the specified values is outside the
normal range, the characters stored are unspecified.
%a is replaced by the locale’s abbreviated weekday name. [tm_wday]
%A is replaced by the locale’s full weekday name. [tm_wday]
%b is replaced by the locale’s abbreviated month name. [tm_mon]
%B is replaced by the locale’s full month name. [tm_mon]
%c is replaced by the locale’s appropriate date and time representation. [all specified in 7.29.1]
%C is replaced by the year divided by 100 and truncated to an integer, as a decimal number (00–99).
[tm_year]
%d is replaced by the day of the month as a decimal number (01–31). [tm_mday]
%D is equivalent to "%m/%d/%y". [tm_mon, tm_mday, tm_year]
%e is replaced by the day of the month as a decimal number (1–31); a single digit is preceded by a
space. [tm_mday]
%F is equivalent to "%Y-%m-%d" (the ISO 8601 date format). [tm_year, tm_mon, tm_mday]
%g is replaced by the last 2 digits of the week-based year (see below) as a decimal number (00–99).
[tm_year, tm_wday, tm_yday]
%G is replaced by the week-based year (see below) as a decimal number (e.g., 1997). [tm_year,
tm_wday, tm_yday]
%h is equivalent to "%b". [tm_mon]
%H is replaced by the hour (24-hour clock) as a decimal number (00–23). [tm_hour]
%I is replaced by the hour (12-hour clock) as a decimal number (01–12). [tm_hour]
%j is replaced by the day of the year as a decimal number (001–366). [tm_yday]
%m is replaced by the month as a decimal number (01–12). [tm_mon]
%M is replaced by the minute as a decimal number (00–59). [tm_min]
%n is replaced by a new-line character.
%p is replaced by the locale’s equivalent of the AM/PM designations associated with a 12-hour
clock. [tm_hour]
%r is replaced by the locale’s 12-hour clock time. [tm_hour, tm_min, tm_sec]
%R is equivalent to "%H:%M". [tm_hour, tm_min ]
%S is replaced by the second as a decimal number (00–60). [tm_sec]
%t is replaced by a horizontal-tab character.
%T is equivalent to "%H:%M:%S" (the ISO 8601 time format). [tm_hour, tm_min, tm_sec]
%u is replaced by the ISO 8601 weekday as a decimal number (1–7), where Monday is 1. [tm_wday]
%U is replaced by the week number of the year (the first Sunday as the first day of week 1) as a
decimal number (00–53). [tm_year, tm_wday, tm_yday]
%V is replaced by the ISO 8601 week number (see below) as a decimal number (01–53). [tm_year,
tm_wday, tm_yday]
%w is replaced by the weekday as a decimal number (0–6), where Sunday is 0. [tm_wday]
%W is replaced by the week number of the year (the first Monday as the first day of week 1) as a
decimal number (00–53). [tm_year, tm_wday, tm_yday]
%x is replaced by the locale’s appropriate date representation. [all specified in 7.29.1]
%X is replaced by the locale’s appropriate time representation. [all specified in 7.29.1]
%y is replaced by the last 2 digits of the year as a decimal number (00–99). [tm_year]
%Y is replaced by the year as a decimal number (e.g., 1997). [tm_year]
%z is replaced by the offset from UTC in the ISO 8601 format "-0430" (meaning 4 hours 30
minutes behind UTC, west of Greenwich), or by no characters if no time zone is determinable.
[tm_isdst]
%Z is replaced by the locale’s time zone name or abbreviation, or by no characters if no time zone is
determinable. [tm_isdst]
%% is replaced by %.
4 Some conversion specifiers can be modified by the inclusion of an E or O modifier character to
indicate an alternative format or specification. If the alternative format or specification does not
exist for the current locale, the modifier is ignored.
%Ec is replaced by the locale’s alternative date and time representation.
%EC is replaced by the name of the base year (period) in the locale’s alternative representation.
%Ex is replaced by the locale’s alternative date representation.
%EX is replaced by the locale’s alternative time representation.
%Ey is replaced by the offset from %EC (year only) in the locale’s alternative representation.
%EY is replaced by the locale’s full alternative year representation.
%Ob is replaced by the locale’s abbreviated alternative month name.
%OB is replaced by the locale’s alternative appropriate full month name.
%Od is replaced by the day of the month, using the locale’s alternative numeric symbols (filled as
needed with leading zeros, or with leading spaces if there is no alternative symbol for zero).
%Oe is replaced by the day of the month, using the locale’s alternative numeric symbols (filled as
needed with leading spaces).
%OH is replaced by the hour (24-hour clock), using the locale’s alternative numeric symbols.
%OI is replaced by the hour (12-hour clock), using the locale’s alternative numeric symbols.
%Om is replaced by the month, using the locale’s alternative numeric symbols.
%OM is replaced by the minutes, using the locale’s alternative numeric symbols.
%OS is replaced by the seconds, using the locale’s alternative numeric symbols.
%Ou is replaced by the ISO 8601 weekday as a number in the locale’s alternative representation,
where Monday is 1.
%OU is replaced by the week number, using the locale’s alternative numeric symbols.
%OV is replaced by the ISO 8601 week number, using the locale’s alternative numeric symbols.
%Ow is replaced by the weekday as a number, using the locale’s alternative numeric symbols.
%OW is replaced by the week number of the year, using the locale’s alternative numeric symbols.
%Oy is replaced by the last 2 digits of the year, using the locale’s alternative numeric symbols.
5 %g, %G, and %V give values according to the ISO 8601 week-based year. In this system, weeks begin
on a Monday and week 1 of the year is the week that includes January 4th, which is also the week
that includes the first Thursday of the year, and is also the first week that contains at least four days
in the year. If the first Monday of January is the 2nd, 3rd, or 4th, the preceding days are part of the
last week of the preceding year; thus, for Saturday 2nd January 1999, %G is replaced by 1998 and %V
is replaced by 53. If December 29th, 30th, or 31st is a Monday, it and any following days are part of
week 1 of the following year. Thus, for Tuesday 30th December 1997, %G is replaced by 1998 and %V
is replaced by 01.
6 If a conversion specifier is not one of the above, the behavior is undefined.
7 In the "C" locale, the E and O modifiers are ignored and the replacement strings for the following
specifiers are:
%a the first three characters of %A.
%A one of "Sunday", "Monday", . . . , "Saturday".
%b the first three characters of %B.
%B one of "January", "February", . . . , "December".
%c equivalent to "%a %b %e %T %Y".
%p one of "AM" or "PM".
%r equivalent to "%I:%M:%S %p".
%x equivalent to "%m/%d/%y".
%X equivalent to %T.
%Z implementation-defined.
Returns
8 If the total number of resulting characters including the terminating null character is not more than
maxsize, the strftime function returns the number of characters placed into the array pointed to
by s not including the terminating null character. Otherwise, zero is returned and the members of
the array have an indeterminate representation.
7.30 [Unicode utilities <uchar.h>]
1 The header <uchar.h> declares types and functions for manipulating Unicode characters.
2 The types declared are mbstate_t (described in 7.31.1) and size_t (described in 7.21);
char8_t
which is an unsigned integer type used for 8-bit characters and is the same type as unsigned char;
char16_t
which is an unsigned integer type used for 16-bit characters and is the same type as uint_least16_t
(described in <IP_ADDRESS>); and
char32_t
which is an unsigned integer type used for 32-bit characters and is the same type as uint_least32_t
(also described in <IP_ADDRESS>).
7.30.1 [Restartable multibyte/wide character conversion functions]
1 These functions have a parameter, ps, of type pointer to mbstate_t that points to an object that can
completely describe the current conversion state of the associated multibyte character sequence,
which the functions alter as necessary. If ps is a null pointer, each function uses its own internal
mbstate_t object instead, which is initialized prior to the first call to the function to the initial
conversion state; the functions are not required to avoid data races with other calls to the same
function in this case. It is implementation-defined whether the internal mbstate_t object has thread
storage duration; if it has thread storage duration, it is initialized to the initial conversion state
prior to the first call to the function on the new thread. The implementation behaves as if no library
function calls these functions with a null pointer for ps.
<IP_ADDRESS> [The mbrtoc8 function]
1 Synopsis
#include <uchar.h>
size_t mbrtoc8(char8_t * restrict pc8, const char * restrict s, size_t n,
mbstate_t * restrict ps);
Description
2 If s is a null pointer, the mbrtoc8 function is equivalent to the call:
mbrtoc8(NULL, "", 1, ps)
In this case, the values of the parameters pc8 and n are ignored.
3 If s is not a null pointer, the mbrtoc8 function function inspects at most n bytes beginning with
the byte pointed to by s to determine the number of bytes needed to complete the next multibyte
character (including any shift sequences). If the function determines that the next multibyte character
is complete and valid, it determines the values of the corresponding characters and then, if pc8 is
not a null pointer, stores the value of the first (or only) such character in the object pointed to by pc8.
Subsequent calls will store successive characters without consuming any additional input until all
the characters have been stored. If the corresponding character is the null character, the resulting
state described is the initial conversion state.
Returns
4 The mbrtoc8 function returns the first of the following that applies (given the current conversion
state):
0 if the next n or fewer bytes complete the multibyte character that corresponds to
the null character (which is the value stored).
between 1 and n inclusive if the next n or fewer bytes complete a valid multibyte character (which
is the value stored); the value returned is the number of bytes that complete the
multibyte character.
(size_t) (−3) if the next character resulting from a previous call has been stored (no bytes from
the input have been consumed by this call).
(size_t) (−2) if the next n bytes contribute to an incomplete (but potentially valid) multibyte
character, and all n bytes have been processed (no value is stored).[395]
(size_t) (−1) if an encoding error occurs, in which case the next n or fewer bytes do not contribute
to a complete and valid multibyte character (no value is stored); the value of the
macro EILSEQ is stored in errno, and the conversion state is unspecified.
Footnote 395) When n has at least the value of the MB_CUR_MAX macro, this case can only occur if s points at a sequence of redundant
shift sequences (for implementations with state-dependent encodings).
<IP_ADDRESS> [The c8rtomb function]
1 Synopsis
#include <uchar.h>
size_t c8rtomb(char * restrict s, char8_t c8, mbstate_t * restrict ps);
Description
2 If s is a null pointer, the c8rtomb function is equivalent to the call
c8rtomb(buf, u8’\0’, ps)
where buf is an internal buffer.
3 If s is not a null pointer, the c8rtomb function determines the number of bytes needed to represent
the multibyte character that corresponds to the character given or completed by c8 (including any
shift sequences), and stores the multibyte character representation in the array whose first element is
pointed to by s, or stores nothing if c8 does not represent a complete character. At most MB_CUR_MAX
bytes are stored. If c8 is a null character, a null byte is stored, preceded by any shift sequence needed
to restore the initial shift state; the resulting state described is the initial conversion state.
Returns
4 The c8rtomb function returns the number of bytes stored in the array object (including any shift
sequences). When c8 is not a valid character, an encoding error occurs: the function stores the value
of the macro EILSEQ in errno and returns (size_t) (−1); the conversion state is unspecified.
<IP_ADDRESS> [The mbrtoc16 function]
1 Synopsis
#include <uchar.h>
size_t mbrtoc16(char16_t * restrict pc16, const char * restrict s, size_t n,
mbstate_t * restrict ps);
Description
2 If s is a null pointer, the mbrtoc16 function is equivalent to the call:
mbrtoc16(NULL, "", 1, ps)
In this case, the values of the parameters pc16 and n are ignored.
3 If s is not a null pointer, the mbrtoc16 function inspects at most n bytes beginning with the byte
pointed to by s to determine the number of bytes needed to complete the next multibyte character
(including any shift sequences). If the function determines that the next multibyte character is
complete and valid, it determines the values of the corresponding wide characters and then, if pc16
is not a null pointer, stores the value of the first (or only) such character in the object pointed to by
pc16. Subsequent calls will store successive wide characters without consuming any additional
input until all the characters have been stored. If the corresponding wide character is the null wide
character, the resulting state described is the initial conversion state.
Returns
4 The mbrtoc16 function returns the first of the following that applies (given the current conversion
state):
0 if the next n or fewer bytes complete the multibyte character that corresponds to
the null wide character (which is the value stored).
between 1 and n inclusive if the next n or fewer bytes complete a valid multibyte character (which
is the value stored); the value returned is the number of bytes that complete the
multibyte character.
(size_t) (−3) if the next character resulting from a previous call has been stored (no bytes from
the input have been consumed by this call).
(size_t) (−2) if the next n bytes contribute to an incomplete (but potentially valid) multibyte
character, and all n bytes have been processed (no value is stored).[396]
(size_t) (−1) if an encoding error occurs, in which case the next n or fewer bytes do not contribute
to a complete and valid multibyte character (no value is stored); the value of the
macro EILSEQ is stored in errno, and the conversion state is unspecified.
Footnote 396) When n has at least the value of the MB_CUR_MAX macro, this case can only occur if s points at a sequence of redundant
shift sequences (for implementations with state-dependent encodings).
<IP_ADDRESS> [The c16rtomb function]
1 Synopsis
#include <uchar.h>
size_t c16rtomb(char * restrict s, char16_t c16, mbstate_t * restrict ps);
Description
2 If s is a null pointer, the c16rtomb function is equivalent to the call
c16rtomb(buf, u’\0’, ps)
where buf is an internal buffer.
3 If s is not a null pointer, the c16rtomb function determines the number of bytes needed to represent
the multibyte character that corresponds to the wide character given or completed by c16 (including
any shift sequences), and stores the multibyte character representation in the array whose first
element is pointed to by s, or stores nothing if c16 does not represent a complete character. At
most MB_CUR_MAX bytes are stored. If c16 is a null wide character, a null byte is stored, preceded by
any shift sequence needed to restore the initial shift state; the resulting state described is the initial
conversion state.
Returns
4 The c16rtomb function returns the number of bytes stored in the array object (including any shift
sequences). When c16 is not a valid wide character, an encoding error occurs: the function stores the
value of the macro EILSEQ in errno and returns (size_t) (−1); the conversion state is unspecified.
<IP_ADDRESS> [The mbrtoc32 function]
1 Synopsis
#include <uchar.h>
size_t mbrtoc32(char32_t * restrict pc32, const char * restrict s, size_t n,
mbstate_t * restrict ps);
Description
2 If s is a null pointer, the mbrtoc32 function is equivalent to the call:
mbrtoc32(NULL, "", 1, ps)
In this case, the values of the parameters pc32 and n are ignored.
3 If s is not a null pointer, the mbrtoc32 function inspects at most n bytes beginning with the byte
pointed to by s to determine the number of bytes needed to complete the next multibyte character
(including any shift sequences). If the function determines that the next multibyte character is
complete and valid, it determines the values of the corresponding wide characters and then, if pc32
is not a null pointer, stores the value of the first (or only) such character in the object pointed to by
pc32. Subsequent calls will store successive wide characters without consuming any additional
input until all the characters have been stored. If the corresponding wide character is the null wide
character, the resulting state described is the initial conversion state.
Returns
4 The mbrtoc32 function returns the first of the following that applies (given the current conversion
state):
0 if the next n or fewer bytes complete the multibyte character that corresponds to
the null wide character (which is the value stored).
between 1 and n inclusive if the next n or fewer bytes complete a valid multibyte character (which
is the value stored); the value returned is the number of bytes that complete the
multibyte character.
(size_t) (−3) if the next character resulting from a previous call has been stored (no bytes from
the input have been consumed by this call).
(size_t) (−2) if the next n bytes contribute to an incomplete (but potentially valid) multibyte
character, and all n bytes have been processed (no value is stored).[397]
(size_t) (−1) if an encoding error occurs, in which case the next n or fewer bytes do not contribute
to a complete and valid multibyte character (no value is stored); the value of the
macro EILSEQ is stored in errno, and the conversion state is unspecified.
Footnote 397) When n has at least the value of the MB_CUR_MAX macro, this case can only occur if s points at a sequence of redundant
shift sequences (for implementations with state-dependent encodings).
<IP_ADDRESS> [The c32rtomb function]
1 Synopsis
#include <uchar.h>
size_t c32rtomb(char * restrict s, char32_t c32, mbstate_t * restrict ps);
Description
2 If s is a null pointer, the c32rtomb function is equivalent to the call
c32rtomb(buf, U’\0’, ps)
where buf is an internal buffer.
3 If s is not a null pointer, the c32rtomb function determines the number of bytes needed to represent
the multibyte character that corresponds to the wide character given by c32 (including any shift
sequences), and stores the multibyte character representation in the array whose first element is
pointed to by s. At most MB_CUR_MAX bytes are stored. If c32 is a null wide character, a null byte is
stored, preceded by any shift sequence needed to restore the initial shift state; the resulting state
described is the initial conversion state.
Returns
4 The c32rtomb function returns the number of bytes stored in the array object (including any shift