libc
2.2.0This file documents the ANSI C library.
Copyright (C) 1992, 1993, 1994-2014 Red Hat, Inc.
libc
includes software developed by the University
of California, Berkeley and its contributors.
libc
includes software developed by Martin
Jackson, Graham Haley and Steve Chamberlain of Tadpole Technology and
released to Cygnus.
libc
uses floating-point conversion software
developed at AT&T, which includes this copyright information:
The author of this software is David M. Gay.
Copyright (c) 1991 by AT&T.
Permission to use, copy, modify, and distribute this software for any purpose without fee is hereby granted, provided that this entire notice is included in all copies of any software which is or includes a copy or modification of this software and in all copies of the supporting documentation for such software.
THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED WARRANTY. IN PARTICULAR, NEITHER THE AUTHOR NOR AT&T MAKES ANY REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, subject to the terms of the GNU General Public License, which includes the provision that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.
Table of Contents
stdlib.h
)ctype.h
)stdio.h
)fgets
instead)stdio.h
)string.h
)wchar.h
)signal.h
)time.h
)locale.h
)This reference manual describes the functions provided by the Red Hat “newlib” version of the standard ANSI C library. This document is not intended as an overview or a tutorial for the C library. Each library function is listed with a synopsis of its use, a brief description, return values (including error handling), and portability issues.
Some of the library functions depend on support from the underlying operating system and may not be available on every platform. For embedded systems in particular, many of these underlying operating system services may not be available or may not be fully functional. The specific operating system subroutines required for a particular library function are listed in the “Portability” section of the function description. See Chapter 13, System Calls, for a description of the relevant operating system calls.
Table of Contents
This chapter groups utility functions useful in a variety of programs.
The corresponding declarations are in the header file stdlib.h
.
_Exit — end program execution with no cleanup processing
#include <stdlib.h>
void _Exit( | int code) ; |
Use _Exit
to return control from a program to the host operating
environment. Use the argument code
to pass an exit status to the
operating environment: two particular values, EXIT_SUCCESS
and
EXIT_FAILURE
, are defined in `stdlib.h
' to indicate success or
failure in a portable fashion.
_Exit
differs from exit
in that it does not run any
application-defined cleanup functions registered with atexit
and
it does not clean up files and streams. It is identical to _exit
.
a64l — convert between radix-64 ASCII string and long
#include <stdlib.h>
long a64l( | const char *input) ; |
char *l64a( | long input) ; |
Conversion is performed between long and radix-64 characters. The
l64a
routine transforms up to 32 bits of input value starting from
least significant bits to the most significant bits. The input value
is split up into a maximum of 5 groups of 6 bits and possibly one
group of 2 bits (bits 31 and 30).
Each group of 6 bits forms a value from 0--63 which is translated into a character as follows:
0 = '.'
1 = '/'
2--11 = '0' to '9'
12--37 = 'A' to 'Z'
38--63 = 'a' to 'z'
When the remaining bits are zero or all bits have been translated, a null terminator is appended to the string. An input value of 0 results in the empty string.
The a64l
function performs the reverse translation. Each
character is used to generate a 6-bit value for up to 30 bits and then
a 2-bit value to complete a 32-bit result. The null terminator means
that the remaining digits are 0. An empty input string or NULL string
results in 0L. An invalid string results in undefined behavior. If
the size of a long is greater than 32 bits, the result is sign-extended.
abort — abnormal termination of a program
#include <stdlib.h>
void abort( | void) ; |
Use abort
to signal that your program has detected a condition it
cannot deal with. Normally, abort
ends your program's execution.
Before terminating your program, abort
raises the exception SIGABRT
(using `raise(SIGABRT)
'). If you have used signal
to register
an exception handler for this condition, that handler has the
opportunity to retain control, thereby avoiding program termination.
In this implementation, abort
does not perform any stream- or
file-related cleanup (the host environment may do so; if not, you can
arrange for your program to do its own cleanup with a SIGABRT
exception handler).
abs — integer absolute value (magnitude)
#include <stdlib.h>
int abs( | int i) ; |
assert — macro for debugging diagnostics
#include <assert.h>
void assert( | int expression) ; |
Use this macro to embed debuggging diagnostic statements in
your programs. The argument expression
should be an
expression which evaluates to true (nonzero) when your program
is working as you intended.
When expression
evaluates to false (zero), assert
calls abort
, after first printing a message showing what
failed and where:
Assertion failed:expression
, filefilename
, linelineno
, function:func
If the name of the current function is not known (for example, when using a C89 compiler that does not understand __func__), the function location is omitted.
The macro is defined to permit you to turn off all uses of
assert
at compile time by defining NDEBUG
as a
preprocessor variable. If you do this, the assert
macro
expands to
(void(0))
atexit — request execution of functions at program exit
#include <stdlib.h>
int atexit( | void (*function)(void)) ; |
You can use atexit
to enroll functions in a list of functions that
will be called when your program terminates normally. The argument is
a pointer to a user-defined function (which must not require arguments and
must not return a result).
The functions are kept in a LIFO stack; that is, the last function
enrolled by atexit
will be the first to execute when your program
exits.
There is no built-in limit to the number of functions you can enroll
in this list; however, after every group of 32 functions is enrolled,
atexit
will call malloc
to get space for the next part of the
list. The initial list of 32 functions is statically allocated, so
you can always count on at least that many slots available.
atof — string to double or float
#include <stdlib.h>
double atof( | const char *s) ; |
float atoff( | const char *s) ; |
atof
converts the initial portion of a string to a double
.
atoff
converts the initial portion of a string to a float
.
The functions parse the character string s
,
locating a substring which can be converted to a floating-point
value. The substring must match the format:
[+|-]digits
[.][digits
][(e|E)[+|-]digits
]
The substring converted is the longest initial
fragment of s
that has the expected format, beginning with
the first non-whitespace character. The substring
is empty if str
is empty, consists entirely
of whitespace, or if the first non-whitespace character is
something other than +
, -
, .
, or a digit.
atof(
is implemented as s
)strtod(
.
s
, NULL)atoff(
is implemented as s
)strtof(
.
s
, NULL)
atof
returns the converted substring value, if any, as a
double
; or 0.0
, if no conversion could be performed.
If the correct value is out of the range of representable values, plus
or minus HUGE_VAL
is returned, and ERANGE
is stored in
errno
.
If the correct value would cause underflow, 0.0
is returned
and ERANGE
is stored in errno
.
atoff
obeys the same rules as atof
, except that it
returns a float
.
atof
is ANSI C. atof
, atoi
, and atol
are subsumed by strod
and strol
, but are used extensively in existing code. These functions are
less reliable, but may be faster if the argument is verified to be in a valid
range.
Supporting OS subroutines required: close
, fstat
, isatty
,
lseek
, read
, sbrk
, write
.
atoi — string to integer
#include <stdlib.h>
int atoi( | const char *s) ; |
long atol( | const char *s) ; |
int _atoi_r( | struct _reent *ptr, |
const char *s) ; |
long _atol_r( | struct _reent *ptr, |
const char *s) ; |
atoi
converts the initial portion of a string to an int
.
atol
converts the initial portion of a string to a long
.
atoi(s)
is implemented as (int)strtol(s, NULL, 10).
atol(s)
is implemented as strtol(s, NULL, 10).
_atoi_r
and _atol_r
are reentrant versions of atoi
and
atol
respectively, passing the reentrancy struct pointer.
atoll — convert a string to a long long integer
#include <stdlib.h>
long long atoll( | const char *str) ; |
long long _atoll_r( | struct _reent *ptr, |
const char *str) ; |
The function atoll
converts the initial portion of the string
pointed to by *
to a type str
long long
. A call to
atoll(str) in this implementation is equivalent to
strtoll(str, (char **)NULL, 10) including behavior on error.
The alternate function _atoll_r
is a reentrant version. The
extra argument reent
is a pointer to a reentrancy structure.
bsearch — binary search
#include <stdlib.h>
void *bsearch( | const void *key, |
const void *base, | |
size_t nmemb, | |
size_t size, | |
int (*compar)(const void *, const void *)) ; |
bsearch
searches an array beginning at base
for any element
that matches key
, using binary search. nmemb
is the element
count of the array; size
is the size of each element.
The array must be sorted in ascending order with respect to the
comparison function compar
(which you supply as the last argument of
bsearch
).
You must define the comparison function (*
to have two
arguments; its result must be negative if the first argument is
less than the second, zero if the two arguments match, and
positive if the first argument is greater than the second (where
``less than'' and ``greater than'' refer to whatever arbitrary
ordering is appropriate).
compar
)
calloc — allocate space for arrays
#include <stdlib.h>
void *calloc( | size_t n, |
size_t s) ; |
void *_calloc_r( | void *reent, |
size_t n, | |
size_t s) ; |
Use calloc
to request a block of memory sufficient to hold an
array of n
elements, each of which has size s
.
The memory allocated by calloc
comes out of the same memory pool
used by malloc
, but the memory block is initialized to all zero
bytes. (To avoid the overhead of initializing the space, use
malloc
instead.)
The alternate function _calloc_r
is reentrant.
The extra argument reent
is a pointer to a reentrancy structure.
div — divide two integers
#include <stdlib.h>
div_t div( | int n, |
int d) ; |
The result is represented with the structure
typedef struct { int quot; int rem; } div_t;
where the quot
field represents the quotient, and rem
the
remainder. For nonzero d
, if `
' then
r
= div(n
,d
);n
equals `
'.
r
.rem + d
*r
.quot
To divide long
rather than int
values, use the similar
function ldiv
.
ecvt — double or float to string
#include <stdlib.h>
char *ecvt( | double val, |
int chars, | |
int *decpt, | |
int *sgn) ; |
char *ecvtf( | float val, |
int chars, | |
int *decpt, | |
int *sgn) ; |
char *fcvt( | double val, |
int decimals, | |
int *decpt, | |
int *sgn) ; |
char *fcvtf( | float val, |
int decimals, | |
int *decpt, | |
int *sgn) ; |
ecvt
and fcvt
produce (null-terminated) strings of digits
representating the double
number val
.
ecvtf
and fcvtf
produce the corresponding character
representations of float
numbers.
(The stdlib
functions ecvtbuf
and fcvtbuf
are reentrant
versions of ecvt
and fcvt
.)
The only difference between ecvt
and fcvt
is the
interpretation of the second argument (chars
or decimals
).
For ecvt
, the second argument chars
specifies the total number
of characters to write (which is also the number of significant digits
in the formatted string, since these two functions write only digits).
For fcvt
, the second argument decimals
specifies the number of
characters to write after the decimal point; all digits for the integer
part of val
are always included.
Since ecvt
and fcvt
write only digits in the output string,
they record the location of the decimal point in *
, and
the sign of the number in decpt
*
. After formatting a number,
sgn
*
contains the number of digits to the left of the
decimal point. decpt
*
contains sgn
0
if the number is positive,
and 1
if it is negative.
gcvt — format double or float as string
#include <stdlib.h>
char *gcvt( | double val, |
int precision, | |
char *buf) ; |
char *gcvtf( | float val, |
int precision, | |
char *buf) ; |
gcvt
writes a fully formatted number as a null-terminated
string in the buffer *
. buf
gcvtf
produces corresponding
character representations of float
numbers.
gcvt
uses the same rules as the printf
format
`%.
'---only negative values are signed (with
`precision
g-
'), and either exponential or ordinary decimal-fraction format
is chosen depending on the number of significant digits (specified by
precision
).
ecvtbuf — double or float to string
#include <stdio.h>
char *ecvtbuf( | double val, |
int chars, | |
int *decpt, | |
int *sgn, | |
char *buf) ; |
char *fcvtbuf( | double val, |
int decimals, | |
int *decpt, | |
int *sgn, | |
char *buf) ; |
ecvtbuf
and fcvtbuf
produce (null-terminated) strings
of digits representating the double
number val
.
The only difference between ecvtbuf
and fcvtbuf
is the
interpretation of the second argument (chars
or
decimals
). For ecvtbuf
, the second argument chars
specifies the total number of characters to write (which is
also the number of significant digits in the formatted string,
since these two functions write only digits). For fcvtbuf
,
the second argument decimals
specifies the number of
characters to write after the decimal point; all digits for
the integer part of val
are always included.
Since ecvtbuf
and fcvtbuf
write only digits in the
output string, they record the location of the decimal point
in *
, and the sign of the number in decpt
*
.
After formatting a number, sgn
*
contains the number
of digits to the left of the decimal point. decpt
*
contains sgn
0
if the number is positive, and 1
if it is
negative. For both functions, you supply a pointer buf
to
an area of memory to hold the converted string.
__env_lock — lock environ variable
#include <envlock.h>
void __env_lock( | struct _reent *reent) ; |
void __env_unlock( | struct _reent *reent) ; |
The setenv
family of routines call these functions when they need to
modify the environ variable. The version of these routines supplied in the
library use the lock API defined in sys/lock.h. If multiple threads of
execution can call setenv
, or if setenv
can be called reentrantly,
then you need to define your own versions of these functions in order to
safely lock the memory pool during a call. If you do not, the memory pool
may become corrupted.
A call to setenv
may call __env_lock
recursively; that is,
the sequence of calls may go __env_lock
, __env_lock
,
__env_unlock
, __env_unlock
. Any implementation of these
routines must be careful to avoid causing a thread to wait for a lock
that it already holds.
exit — end program execution
#include <stdlib.h>
void exit( | int code) ; |
Use exit
to return control from a program to the host operating
environment. Use the argument code
to pass an exit status to the
operating environment: two particular values, EXIT_SUCCESS
and
EXIT_FAILURE
, are defined in `stdlib.h
' to indicate success or
failure in a portable fashion.
exit
does two kinds of cleanup before ending execution of your
program. First, it calls all application-defined cleanup functions
you have enrolled with atexit
. Second, files and streams are
cleaned up: any pending output is delivered to the host system, each
open file or stream is closed, and files created by tmpfile
are
deleted.
getenv — look up environment variable
#include <stdlib.h>
char *getenv( | const char *name) ; |
getenv
searches the list of environment variable names and values
(using the global pointer ``char **environ
'') for a variable whose
name matches the string at name
. If a variable name matches,
getenv
returns a pointer to the associated value.
itoa — integer to string
#include <stdlib.h>
char *itoa( | int value, |
char *str, | |
int base) ; |
char *__itoa( | int value, |
char *str, | |
int base) ; |
itoa
converts the integer value
to a null-terminated string
using the specified base, which must be between 2 and 36, inclusive.
If base
is 10, value
is treated as signed and the string will be
prefixed with '-' if negative. For all other bases, value
is treated as
unsigned. str
should be an array long enough to contain the converted
value, which in the worst case is sizeof(int)*8+1 bytes.
labs — long integer absolute value
#include <stdlib.h>
long labs( | long i) ; |
ldiv — divide two long integers
#include <stdlib.h>
ldiv_t ldiv( | long n, |
long d) ; |
Divide
n
/d
,
returning quotient and remainder as two long integers in a structure ldiv_t
.
The result is represented with the structure
typedef struct { long quot; long rem; } ldiv_t;
where the quot
field represents the quotient, and rem
the
remainder. For nonzero d
, if `
' then
r
= ldiv(n
,d
);n
equals `
'.
r
.rem + d
*r
.quot
To divide int
rather than long
values, use the similar
function div
.
llabs — compute the absolute value of an long long integer.
#include <stdlib.h>
long long llabs( | long long j) ; |
lldiv — divide two long long integers
#include <stdlib.h>
lldiv_t lldiv( | long long n, |
long long d) ; |
Divide
n
/d
,
returning quotient and remainder as two long long integers in a structure
lldiv_t
.
The result is represented with the structure
typedef struct { long long quot; long long rem; } lldiv_t;
where the quot
field represents the quotient, and rem
the
remainder. For nonzero d
, if `
' then
r
= ldiv(n
,d
);n
equals `
'.
r
.rem + d
*r
.quot
To divide long
rather than long long
values, use the similar
function ldiv
.
malloc — manage memory
#include <stdlib.h>
void *malloc( | size_t nbytes) ; |
void *realloc( | void *aptr, |
size_t nbytes) ; |
void *reallocf( | void *aptr, |
size_t nbytes) ; |
void free( | void *aptr) ; |
void *memalign( | size_t align, |
size_t nbytes) ; |
size_t malloc_usable_size( | void *aptr) ; |
void *_malloc_r( | void *reent, |
size_t nbytes) ; |
void *_realloc_r( | void *reent, |
void *aptr, | |
size_t nbytes) ; |
void *_reallocf_r( | void *reent, |
void *aptr, | |
size_t nbytes) ; |
void _free_r( | void *reent, |
void *aptr) ; |
void *_memalign_r( | void *reent, |
size_t align, | |
size_t nbytes) ; |
size_t _malloc_usable_size_r( | void *reent, |
void *aptr) ; |
These functions manage a pool of system memory.
Use malloc
to request allocation of an object with at least
nbytes
bytes of storage available. If the space is available,
malloc
returns a pointer to a newly allocated block as its result.
If you already have a block of storage allocated by malloc
, but
you no longer need all the space allocated to it, you can make it
smaller by calling realloc
with both the object pointer and the
new desired size as arguments. realloc
guarantees that the
contents of the smaller object match the beginning of the original object.
Similarly, if you need more space for an object, use realloc
to
request the larger size; again, realloc
guarantees that the
beginning of the new, larger object matches the contents of the
original object.
When you no longer need an object originally allocated by malloc
or realloc
(or the related function calloc
), return it to the
memory storage pool by calling free
with the address of the object
as the argument. You can also use realloc
for this purpose by
calling it with 0
as the nbytes
argument.
The reallocf
function behaves just like realloc
except if the
function is required to allocate new storage and this fails. In this
case reallocf
will free the original object passed in whereas
realloc
will not.
The memalign
function returns a block of size nbytes
aligned
to a align
boundary. The align
argument must be a power of
two.
The malloc_usable_size
function takes a pointer to a block
allocated by malloc
. It returns the amount of space that is
available in the block. This may or may not be more than the size
requested from malloc
, due to alignment or minimum size
constraints.
The alternate functions _malloc_r
, _realloc_r
, _reallocf_r
,
_free_r
, _memalign_r
, and _malloc_usable_size_r
are reentrant
versions. The extra argument reent
is a pointer to a reentrancy structure.
If you have multiple threads of execution which may call any of these
routines, or if any of these routines may be called reentrantly, then
you must provide implementations of the __malloc_lock
and
__malloc_unlock
functions for your system. See the documentation
for those functions.
These functions operate by calling the function _sbrk_r
or
sbrk
, which allocates space. You may need to provide one of these
functions for your system. _sbrk_r
is called with a positive
value to allocate more space, and with a negative value to release
previously allocated space if it is no longer required.
See the section called “Definitions for OS interface”.
malloc
returns a pointer to the newly allocated space, if
successful; otherwise it returns NULL
. If your application needs
to generate empty objects, you may use malloc(0)
for this purpose.
realloc
returns a pointer to the new block of memory, or NULL
if a new block could not be allocated. NULL
is also the result
when you use `realloc(
' (which has the same effect as
`aptr
,0)free(
'). You should always check the result of
aptr
)realloc
; successful reallocation is not guaranteed even when
you request a smaller object.
free
does not return a result.
memalign
returns a pointer to the newly allocated space.
malloc_usable_size
returns the usable size.
mallinfo — malloc support
#include <malloc.h>
struct mallinfo mallinfo( | void) ; |
void malloc_stats( | void) ; |
int mallopt( | int parameter, |
value
) ; |
struct mallinfo _mallinfo_r( | void *reent) ; |
void _malloc_stats_r( | void *reent) ; |
int _mallopt_r( | void *reent, |
int parameter, | |
value
) ; |
mallinfo
returns a structure describing the current state of
memory allocation. The structure is defined in malloc.h. The
following fields are defined: arena
is the total amount of space
in the heap; ordblks
is the number of chunks which are not in use;
uordblks
is the total amount of space allocated by malloc
;
fordblks
is the total amount of space not in use; keepcost
is
the size of the top most memory block.
malloc_stats
print some statistics about memory allocation on
standard error.
mallopt
takes a parameter and a value. The parameters are defined
in malloc.h, and may be one of the following: M_TRIM_THRESHOLD
sets the maximum amount of unused space in the top most block before
releasing it back to the system in free
(the space is released by
calling _sbrk_r
with a negative argument); M_TOP_PAD
is the
amount of padding to allocate whenever _sbrk_r
is called to
allocate more space.
The alternate functions _mallinfo_r
, _malloc_stats_r
, and
_mallopt_r
are reentrant versions. The extra argument reent
is a pointer to a reentrancy structure.
__malloc_lock — lock malloc pool
#include <malloc.h>
void __malloc_lock( | struct _reent *reent) ; |
void __malloc_unlock( | struct _reent *reent) ; |
The malloc
family of routines call these functions when they need to lock
the memory pool. The version of these routines supplied in the library use
the lock API defined in sys/lock.h. If multiple threads of execution can
call malloc
, or if malloc
can be called reentrantly, then you need to
define your own versions of these functions in order to safely lock the
memory pool during a call. If you do not, the memory pool may become
corrupted.
A call to malloc
may call __malloc_lock
recursively; that is,
the sequence of calls may go __malloc_lock
, __malloc_lock
,
__malloc_unlock
, __malloc_unlock
. Any implementation of these
routines must be careful to avoid causing a thread to wait for a lock
that it already holds.
mblen — minimal multibyte length function
#include <stdlib.h>
int mblen( | const char *s, |
size_t n) ; |
When _MB_CAPABLE is not defined, this is a minimal ANSI-conforming
implementation of mblen
. In this case, the
only ``multi-byte character sequences'' recognized are single bytes,
and thus 1
is returned unless s
is the null pointer or
has a length of 0 or is the empty string.
When _MB_CAPABLE is defined, this routine calls _mbtowc_r
to perform
the conversion, passing a state variable to allow state dependent
decoding. The result is based on the locale setting which may
be restricted to a defined set of locales.
mbsrtowcs — convert a character string to a wide-character string
#include <wchar.h>
size_t mbsrtowcs( | wchar_t *__restrict dst, |
const char **__restrict src, | |
size_t len, | |
mbstate_t *__restrict ps) ; |
#include <wchar.h>
size_t _mbsrtowcs_r( | struct _reent *ptr, |
wchar_t *dst, | |
const char **src, | |
size_t len, | |
mbstate_t *ps) ; |
#include <wchar.h>
size_t mbsnrtowcs( | wchar_t *__ restrict dst, |
const char **__restrict src, | |
size_t nms, | |
size_t len, | |
mbstate_t *__restrict ps) ; |
#include <wchar.h>
size_t _mbsnrtowcs_r( | struct _reent *ptr, |
wchar_t *dst, | |
const char **src, | |
size_t nms, | |
size_t len, | |
mbstate_t *ps) ; |
The mbsrtowcs
function converts a sequence of multibyte characters
pointed to indirectly by src
into a sequence of corresponding wide
characters and stores at most len
of them in the wchar_t array pointed
to by dst
, until it encounters a terminating null character ('\0').
If dst
is NULL, no characters are stored.
If dst
is not NULL, the pointer pointed to by src
is updated to point
to the character after the one that conversion stopped at. If conversion
stops because a null character is encountered, *src
is set to NULL.
The mbstate_t argument, ps
, is used to keep track of the shift state. If
it is NULL, mbsrtowcs
uses an internal, static mbstate_t object, which
is initialized to the initial conversion state at program startup.
The mbsnrtowcs
function behaves identically to mbsrtowcs
, except that
conversion stops after reading at most nms
bytes from the buffer pointed
to by src
.
mbstowcs — minimal multibyte string to wide char converter
#include <stdlib.h>
int mbstowcs( | wchar_t *restrict pwc, |
const char *restrict s, | |
size_t n) ; |
When _MB_CAPABLE is not defined, this is a minimal ANSI-conforming
implementation of mbstowcs
. In this case, the
only ``multi-byte character sequences'' recognized are single bytes,
and they are ``converted'' to wide-char versions simply by byte
extension.
When _MB_CAPABLE is defined, this routine calls _mbstowcs_r
to perform
the conversion, passing a state variable to allow state dependent
decoding. The result is based on the locale setting which may
be restricted to a defined set of locales.
This implementation of mbstowcs
returns 0
if
s
is NULL
or is the empty string;
it returns -1
if _MB_CAPABLE and one of the
multi-byte characters is invalid or incomplete;
otherwise it returns the minimum of: n
or the
number of multi-byte characters in s
plus 1 (to
compensate for the nul character).
If the return value is -1, the state of the pwc
string is
indeterminate. If the input has a length of 0, the output
string will be modified to contain a wchar_t nul terminator.
mbtowc — minimal multibyte to wide char converter
#include <stdlib.h>
int mbtowc( | wchar_t *restrict pwc, |
const char *restrict s, | |
size_t n) ; |
When _MB_CAPABLE is not defined, this is a minimal ANSI-conforming
implementation of mbtowc
. In this case,
only ``multi-byte character sequences'' recognized are single bytes,
and they are ``converted'' to themselves.
Each call to mbtowc
copies one character from *
to
s
*
, unless pwc
s
is a null pointer. The argument n
is ignored.
When _MB_CAPABLE is defined, this routine calls _mbtowc_r
to perform
the conversion, passing a state variable to allow state dependent
decoding. The result is based on the locale setting which may
be restricted to a defined set of locales.
This implementation of mbtowc
returns 0
if
s
is NULL
or is the empty string;
it returns 1
if not _MB_CAPABLE or
the character is a single-byte character; it returns -1
if n is 0
or the multi-byte character is invalid;
otherwise it returns the number of bytes in the multibyte character.
If the return value is -1, no changes are made to the pwc
output string. If the input is the empty string, a wchar_t nul
is placed in the output string and 0 is returned. If the input
has a length of 0, no changes are made to the pwc
output string.
on_exit — request execution of function with argument at program exit
#include <stdlib.h>
int on_exit( | void (*function)(int, void *), |
void *arg) ; |
You can use on_exit
to enroll functions in a list of functions that
will be called when your program terminates normally. The argument is
a pointer to a user-defined function which takes two arguments. The
first is the status code passed to exit and the second argument is of type
pointer to void. The function must not return a result. The value
of arg
is registered and passed as the argument to function
.
The functions are kept in a LIFO stack; that is, the last function
enrolled by atexit
or on_exit
will be the first to execute when
your program exits. You can intermix functions using atexit
and
on_exit
.
There is no built-in limit to the number of functions you can enroll
in this list; however, after every group of 32 functions is enrolled,
atexit
/on_exit
will call malloc
to get space for the next part
of the list. The initial list of 32 functions is statically allocated, so
you can always count on at least that many slots available.
qsort — sort an array
#include <stdlib.h>
void qsort( | void *base, |
size_t nmemb, | |
size_t size, | |
int (*compar)(const void *, const void *)) ; |
qsort
sorts an array (beginning at base
) of nmemb
objects.
size
describes the size of each element of the array.
You must supply a pointer to a comparison function, using the argument
shown as compar
. (This permits sorting objects of unknown
properties.) Define the comparison function to accept two arguments,
each a pointer to an element of the array starting at base
. The
result of (*
must be negative if the first argument is
less than the second, zero if the two arguments match, and positive if
the first argument is greater than the second (where ``less than'' and
``greater than'' refer to whatever arbitrary ordering is appropriate).
compar
)
The array is sorted in place; that is, when qsort
returns, the
array elements beginning at base
have been reordered.
rand — pseudo-random numbers
#include <stdlib.h>
int rand( | void) ; |
void srand( | unsigned int seed) ; |
int rand_r( | unsigned int *seed) ; |
rand
returns a different integer each time it is called; each
integer is chosen by an algorithm designed to be unpredictable, so
that you can use rand
when you require a random number.
The algorithm depends on a static variable called the ``random seed'';
starting with a given value of the random seed always produces the
same sequence of numbers in successive calls to rand
.
You can set the random seed using srand
; it does nothing beyond
storing its argument in the static variable used by rand
. You can
exploit this to make the pseudo-random sequence less predictable, if
you wish, by using some other unpredictable value (often the least
significant parts of a time-varying value) as the random seed before
beginning a sequence of calls to rand
; or, if you wish to ensure
(for example, while debugging) that successive runs of your program
use the same ``random'' numbers, you can use srand
to set the same
random seed at the outset.
rand
returns the next pseudo-random integer in sequence; it is a
number between 0
and RAND_MAX
(inclusive).
srand
does not return a result.
rand48 — pseudo-random number generators and initialization routines
#include <stdlib.h>
double drand48( | void) ; |
double erand48( | unsigned short xseed[3]) ; |
long lrand48( | void) ; |
long nrand48( | unsigned short xseed[3]) ; |
long mrand48( | void) ; |
long jrand48( | unsigned short xseed[3]) ; |
void srand48( | long seed) ; |
unsigned short *seed48( | unsigned short xseed[3]) ; |
void lcong48( | unsigned short p[7]) ; |
The rand48
family of functions generates pseudo-random numbers
using a linear congruential algorithm working on integers 48 bits in size.
The particular formula employed is
r(n+1) = (a * r(n) + c) mod m
where the default values are
for the multiplicand a = 0xfdeece66d = 25214903917 and
the addend c = 0xb = 11. The modulo is always fixed at m = 2 ** 48.
r(n) is called the seed of the random number generator.
For all the six generator routines described next, the first computational step is to perform a single iteration of the algorithm.
drand48
and erand48
return values of type double. The full 48 bits of r(n+1) are
loaded into the mantissa of the returned value, with the exponent set
such that the values produced lie in the interval [0.0, 1.0].
lrand48
and nrand48
return values of type long in the range
[0, 2**31-1]. The high-order (31) bits of
r(n+1) are loaded into the lower bits of the returned value, with
the topmost (sign) bit set to zero.
mrand48
and jrand48
return values of type long in the range
[-2**31, 2**31-1]. The high-order (32) bits of
r(n+1) are loaded into the returned value.
drand48
, lrand48
, and mrand48
use an internal buffer to store r(n). For these functions
the initial value of r(0) = 0x1234abcd330e = 20017429951246.
On the other hand, erand48
, nrand48
, and jrand48
use a user-supplied buffer to store the seed r(n),
which consists of an array of 3 shorts, where the zeroth member
holds the least significant bits.
All functions share the same multiplicand and addend.
srand48
is used to initialize the internal buffer r(n) of
drand48
, lrand48
, and mrand48
such that the 32 bits of the seed value are copied into the upper 32 bits
of r(n), with the lower 16 bits of r(n) arbitrarily being set to 0x330e.
Additionally, the constant multiplicand and addend of the algorithm are
reset to the default values given above.
seed48
also initializes the internal buffer r(n) of
drand48
, lrand48
, and mrand48
,
but here all 48 bits of the seed can be specified in an array of 3 shorts,
where the zeroth member specifies the lowest bits. Again,
the constant multiplicand and addend of the algorithm are
reset to the default values given above.
seed48
returns a pointer to an array of 3 shorts which contains
the old seed.
This array is statically allocated, thus its contents are lost after
each new call to seed48
.
Finally, lcong48
allows full control over the multiplicand and
addend used in drand48
, erand48
, lrand48
, nrand48
,
mrand48
, and jrand48
,
and the seed used in drand48
, lrand48
, and mrand48
.
An array of 7 shorts is passed as parameter; the first three shorts are
used to initialize the seed; the second three are used to initialize the
multiplicand; and the last short is used to initialize the addend.
It is thus not possible to use values greater than 0xffff as the addend.
Note that all three methods of seeding the random number generator always also set the multiplicand and addend for any of the six generator calls.
For a more powerful random number generator, see random
.
rpmatch — determine whether response to question is affirmative or negative
#include <stdlib.h>
int rpmatch( | const char *response) ; |
The rpmatch
function determines whether response
is an affirmative
or negative response to a question according to the current locale.
strtod — string to double or float
#include <stdlib.h>
double strtod( | const char *restrict str, |
char **restrict tail) ; |
float strtof( | const char *restrict str, |
char **restrict tail) ; |
double _strtod_r( | void *reent, |
const char *restrict str, | |
char **restrict tail) ; |
The function strtod
parses the character string str
,
producing a substring which can be converted to a double
value. The substring converted is the longest initial
subsequence of str
, beginning with the first
non-whitespace character, that has one of these formats:
[+|-]digits
[.[digits
]][(e|E)[+|-]digits
] [+|-].digits
[(e|E)[+|-]digits
] [+|-](i|I)(n|N)(f|F)[(i|I)(n|N)(i|I)(t|T)(y|Y)] [+|-](n|N)(a|A)(n|N)[<(>[hexdigits
]<)>] [+|-]0(x|X)hexdigits
[.[hexdigits
]][(p|P)[+|-]digits
] [+|-]0(x|X).hexdigits
[(p|P)[+|-]digits
]
The substring contains no characters if str
is empty, consists
entirely of whitespace, or if the first non-whitespace
character is something other than +
, -
, .
, or a
digit, and cannot be parsed as infinity or NaN. If the platform
does not support NaN, then NaN is treated as an empty substring.
If the substring is empty, no conversion is done, and
the value of str
is stored in *
. Otherwise,
the substring is converted, and a pointer to the final string
(which will contain at least the terminating null character of
tail
str
) is stored in *
. If you want no
assignment to tail
*
, pass a null pointer as tail
tail
.
strtof
is identical to strtod
except for its return type.
This implementation returns the nearest machine number to the
input decimal string. Ties are broken by using the IEEE
round-even rule. However, strtof
is currently subject to
double rounding errors.
The alternate function _strtod_r
is a reentrant version.
The extra argument reent
is a pointer to a reentrancy structure.
strtod
returns the converted substring value, if any. If
no conversion could be performed, 0 is returned. If the
correct value is out of the range of representable values,
plus or minus HUGE_VAL
is returned, and ERANGE
is
stored in errno. If the correct value would cause underflow, 0
is returned and ERANGE
is stored in errno.
Supporting OS subroutines required: close
, fstat
, isatty
,
lseek
, read
, sbrk
, write
.
strtol — string to long
#include <stdlib.h>
long strtol( | const char *restrict s, |
char **restrict ptr, | |
int base) ; |
long _strtol_r( | void *reent, |
const char *restrict s, | |
char **restrict ptr, | |
int base) ; |
The function strtol
converts the string *
to
a s
long
. First, it breaks down the string into three parts:
leading whitespace, which is ignored; a subject string consisting
of characters resembling an integer in the radix specified by base
;
and a trailing portion consisting of zero or more unparseable characters,
and always including the terminating null character. Then, it attempts
to convert the subject string into a long
and returns the
result.
If the value of base
is 0, the subject string is expected to look
like a normal C integer constant: an optional sign, a possible `0x
'
indicating a hexadecimal base, and a number. If base
is between
2 and 36, the expected form of the subject is a sequence of letters
and digits representing an integer in the radix specified by base
,
with an optional plus or minus sign. The letters a
--z
(or,
equivalently, A
--Z
) are used to signify values from 10 to 35;
only letters whose ascribed values are less than base
are
permitted. If base
is 16, a leading 0x
is permitted.
The subject sequence is the longest initial sequence of the input string that has the expected form, starting with the first non-whitespace character. If the string is empty or consists entirely of whitespace, or if the first non-whitespace character is not a permissible letter or digit, the subject string is empty.
If the subject string is acceptable, and the value of base
is zero,
strtol
attempts to determine the radix from the input string. A
string with a leading 0x
is treated as a hexadecimal value; a string with
a leading 0 and no x
is treated as octal; all other strings are
treated as decimal. If base
is between 2 and 36, it is used as the
conversion radix, as described above. If the subject string begins with
a minus sign, the value is negated. Finally, a pointer to the first
character past the converted subject string is stored in ptr
, if
ptr
is not NULL
.
If the subject string is empty (or not in acceptable form), no conversion
is performed and the value of s
is stored in ptr
(if ptr
is
not NULL
).
The alternate function _strtol_r
is a reentrant version. The
extra argument reent
is a pointer to a reentrancy structure.
strtoll — string to long long
#include <stdlib.h>
long long strtoll( | const char *restrict s, |
char **restrict ptr, | |
int base) ; |
long long _strtoll_r( | void *reent, |
const char *restrict s, | |
char **restrict ptr, | |
int base) ; |
The function strtoll
converts the string *
to
a s
long long
. First, it breaks down the string into three parts:
leading whitespace, which is ignored; a subject string consisting
of characters resembling an integer in the radix specified by base
;
and a trailing portion consisting of zero or more unparseable characters,
and always including the terminating null character. Then, it attempts
to convert the subject string into a long long
and returns the
result.
If the value of base
is 0, the subject string is expected to look
like a normal C integer constant: an optional sign, a possible `0x
'
indicating a hexadecimal base, and a number. If base
is between
2 and 36, the expected form of the subject is a sequence of letters
and digits representing an integer in the radix specified by base
,
with an optional plus or minus sign. The letters a
--z
(or,
equivalently, A
--Z
) are used to signify values from 10 to 35;
only letters whose ascribed values are less than base
are
permitted. If base
is 16, a leading 0x
is permitted.
The subject sequence is the longest initial sequence of the input string that has the expected form, starting with the first non-whitespace character. If the string is empty or consists entirely of whitespace, or if the first non-whitespace character is not a permissible letter or digit, the subject string is empty.
If the subject string is acceptable, and the value of base
is zero,
strtoll
attempts to determine the radix from the input string. A
string with a leading 0x
is treated as a hexadecimal value; a string with
a leading 0 and no x
is treated as octal; all other strings are
treated as decimal. If base
is between 2 and 36, it is used as the
conversion radix, as described above. If the subject string begins with
a minus sign, the value is negated. Finally, a pointer to the first
character past the converted subject string is stored in ptr
, if
ptr
is not NULL
.
If the subject string is empty (or not in acceptable form), no conversion
is performed and the value of s
is stored in ptr
(if ptr
is
not NULL
).
The alternate function _strtoll_r
is a reentrant version. The
extra argument reent
is a pointer to a reentrancy structure.
strtoul — string to unsigned long
#include <stdlib.h>
unsigned long strtoul( | const char *restrict s, |
char **restrict ptr, | |
int base) ; |
unsigned long _strtoul_r( | void *reent, |
const char *restrict s, | |
char **restrict ptr, | |
int base) ; |
The function strtoul
converts the string *
to
an s
unsigned long
. First, it breaks down the string into three parts:
leading whitespace, which is ignored; a subject string consisting
of the digits meaningful in the radix specified by base
(for example, 0
through 7
if the value of base
is 8);
and a trailing portion consisting of one or more unparseable characters,
which always includes the terminating null character. Then, it attempts
to convert the subject string into an unsigned long integer, and returns the
result.
If the value of base
is zero, the subject string is expected to look
like a normal C integer constant (save that no optional sign is permitted):
a possible 0x
indicating hexadecimal radix, and a number.
If base
is between 2 and 36, the expected form of the subject is a
sequence of digits (which may include letters, depending on the
base) representing an integer in the radix specified by base
.
The letters a
--z
(or A
--Z
) are used as digits valued from
10 to 35. If base
is 16, a leading 0x
is permitted.
The subject sequence is the longest initial sequence of the input string that has the expected form, starting with the first non-whitespace character. If the string is empty or consists entirely of whitespace, or if the first non-whitespace character is not a permissible digit, the subject string is empty.
If the subject string is acceptable, and the value of base
is zero,
strtoul
attempts to determine the radix from the input string. A
string with a leading 0x
is treated as a hexadecimal value; a string with
a leading 0
and no x
is treated as octal; all other strings are
treated as decimal. If base
is between 2 and 36, it is used as the
conversion radix, as described above. Finally, a pointer to the first
character past the converted subject string is stored in ptr
, if
ptr
is not NULL
.
If the subject string is empty (that is, if *
s
does not start
with a substring in acceptable form), no conversion
is performed and the value of s
is stored in ptr
(if ptr
is
not NULL
).
The alternate function _strtoul_r
is a reentrant version. The
extra argument reent
is a pointer to a reentrancy structure.
strtoull — string to unsigned long long
#include <stdlib.h>
unsigned long long strtoull( | const char *restrict s, |
char **restrict ptr, | |
int base) ; |
unsigned long long _strtoull_r( | void *reent, |
const char *restrict s, | |
char **restrict ptr, | |
int base) ; |
The function strtoull
converts the string *
to
an s
unsigned long long
. First, it breaks down the string into three parts:
leading whitespace, which is ignored; a subject string consisting
of the digits meaningful in the radix specified by base
(for example, 0
through 7
if the value of base
is 8);
and a trailing portion consisting of one or more unparseable characters,
which always includes the terminating null character. Then, it attempts
to convert the subject string into an unsigned long long integer, and returns the
result.
If the value of base
is zero, the subject string is expected to look
like a normal C integer constant (save that no optional sign is permitted):
a possible 0x
indicating hexadecimal radix, and a number.
If base
is between 2 and 36, the expected form of the subject is a
sequence of digits (which may include letters, depending on the
base) representing an integer in the radix specified by base
.
The letters a
--z
(or A
--Z
) are used as digits valued from
10 to 35. If base
is 16, a leading 0x
is permitted.
The subject sequence is the longest initial sequence of the input string that has the expected form, starting with the first non-whitespace character. If the string is empty or consists entirely of whitespace, or if the first non-whitespace character is not a permissible digit, the subject string is empty.
If the subject string is acceptable, and the value of base
is zero,
strtoull
attempts to determine the radix from the input string. A
string with a leading 0x
is treated as a hexadecimal value; a string with
a leading 0
and no x
is treated as octal; all other strings are
treated as decimal. If base
is between 2 and 36, it is used as the
conversion radix, as described above. Finally, a pointer to the first
character past the converted subject string is stored in ptr
, if
ptr
is not NULL
.
If the subject string is empty (that is, if *
s
does not start
with a substring in acceptable form), no conversion
is performed and the value of s
is stored in ptr
(if ptr
is
not NULL
).
The alternate function _strtoull_r
is a reentrant version. The
extra argument reent
is a pointer to a reentrancy structure.
wcsrtombs — convert a wide-character string to a character string
#include <wchar.h>
size_t wcsrtombs( | char *__restrict dst, |
const wchar_t **__restrict src, | |
size_t len, | |
mbstate_t *__restrict ps) ; |
#include <wchar.h>
size_t _wcsrtombs_r( | struct _reent *ptr, |
char *dst, | |
const wchar_t **src, | |
size_t len, | |
mbstate_t *ps) ; |
#include <wchar.h>
size_t wcsnrtombs( | char *__restrict dst, |
const wchar_t **__restrict src, | |
size_t nwc, | |
size_t len, | |
mbstate_t *__restrict ps) ; |
#include <wchar.h>
size_t _wcsnrtombs_r( | struct _reent *ptr, |
char *dst, | |
const wchar_t **src, | |
size_t nwc, | |
size_t len, | |
mbstate_t *ps) ; |
The wcsrtombs
function converts a string of wide characters indirectly
pointed to by src
to a corresponding multibyte character string stored in
the array pointed to by dst
. No more than len
bytes are written to
dst
.
If dst
is NULL, no characters are stored.
If dst
is not NULL, the pointer pointed to by src
is updated to point
to the character after the one that conversion stopped at. If conversion
stops because a null character is encountered, *src
is set to NULL.
The mbstate_t argument, ps
, is used to keep track of the shift state. If
it is NULL, wcsrtombs
uses an internal, static mbstate_t object, which
is initialized to the initial conversion state at program startup.
The wcsnrtombs
function behaves identically to wcsrtombs
, except that
conversion stops after reading at most nwc
characters from the buffer
pointed to by src
.
wcstod — wide char string to double or float
#include <stdlib.h>
double wcstod( | const wchar_t *__restrict str, |
wchar_t **__restrict tail) ; |
float wcstof( | const wchar_t *__restrict str, |
wchar_t **__restrict tail) ; |
double _wcstod_r( | void *reent, |
const wchar_t *str, | |
wchar_t **tail) ; |
float _wcstof_r( | void *reent, |
const wchar_t *str, | |
wchar_t **tail) ; |
The function wcstod
parses the wide character string str
,
producing a substring which can be converted to a double
value. The substring converted is the longest initial
subsequence of str
, beginning with the first
non-whitespace character, that has one of these formats:
[+|-]digits
[.[digits
]][(e|E)[+|-]digits
] [+|-].digits
[(e|E)[+|-]digits
] [+|-](i|I)(n|N)(f|F)[(i|I)(n|N)(i|I)(t|T)(y|Y)] [+|-](n|N)(a|A)(n|N)[<(>[hexdigits
]<)>] [+|-]0(x|X)hexdigits
[.[hexdigits
]][(p|P)[+|-]digits
] [+|-]0(x|X).hexdigits
[(p|P)[+|-]digits
]
The substring contains no characters if str
is empty, consists
entirely of whitespace, or if the first non-whitespace
character is something other than +
, -
, .
, or a
digit, and cannot be parsed as infinity or NaN. If the platform
does not support NaN, then NaN is treated as an empty substring.
If the substring is empty, no conversion is done, and
the value of str
is stored in *
. Otherwise,
the substring is converted, and a pointer to the final string
(which will contain at least the terminating null character of
tail
str
) is stored in *
. If you want no
assignment to tail
*
, pass a null pointer as tail
tail
.
wcstof
is identical to wcstod
except for its return type.
This implementation returns the nearest machine number to the
input decimal string. Ties are broken by using the IEEE
round-even rule. However, wcstof
is currently subject to
double rounding errors.
The alternate functions _wcstod_r
and _wcstof_r
are
reentrant versions of wcstod
and wcstof
, respectively.
The extra argument reent
is a pointer to a reentrancy structure.
Return the converted substring value, if any. If
no conversion could be performed, 0 is returned. If the
correct value is out of the range of representable values,
plus or minus HUGE_VAL
is returned, and ERANGE
is
stored in errno. If the correct value would cause underflow, 0
is returned and ERANGE
is stored in errno.
Supporting OS subroutines required: close
, fstat
, isatty
,
lseek
, read
, sbrk
, write
.
wcstol — wide string to long
#include <wchar.h>
long wcstol( | const wchar_t *__restrict s, |
wchar_t **__restrict ptr, | |
int base) ; |
long _wcstol_r( | void *reent, |
const wchar_t *s, | |
wchar_t **ptr, | |
int base) ; |
The function wcstol
converts the wide string *
to
a s
long
. First, it breaks down the string into three parts:
leading whitespace, which is ignored; a subject string consisting
of characters resembling an integer in the radix specified by base
;
and a trailing portion consisting of zero or more unparseable characters,
and always including the terminating null character. Then, it attempts
to convert the subject string into a long
and returns the
result.
If the value of base
is 0, the subject string is expected to look
like a normal C integer constant: an optional sign, a possible `0x
'
indicating a hexadecimal base, and a number. If base
is between
2 and 36, the expected form of the subject is a sequence of letters
and digits representing an integer in the radix specified by base
,
with an optional plus or minus sign. The letters a
--z
(or,
equivalently, A
--Z
) are used to signify values from 10 to 35;
only letters whose ascribed values are less than base
are
permitted. If base
is 16, a leading 0x
is permitted.
The subject sequence is the longest initial sequence of the input string that has the expected form, starting with the first non-whitespace character. If the string is empty or consists entirely of whitespace, or if the first non-whitespace character is not a permissible letter or digit, the subject string is empty.
If the subject string is acceptable, and the value of base
is zero,
wcstol
attempts to determine the radix from the input string. A
string with a leading 0x
is treated as a hexadecimal value; a string with
a leading 0 and no x
is treated as octal; all other strings are
treated as decimal. If base
is between 2 and 36, it is used as the
conversion radix, as described above. If the subject string begins with
a minus sign, the value is negated. Finally, a pointer to the first
character past the converted subject string is stored in ptr
, if
ptr
is not NULL
.
If the subject string is empty (or not in acceptable form), no conversion
is performed and the value of s
is stored in ptr
(if ptr
is
not NULL
).
The alternate function _wcstol_r
is a reentrant version. The
extra argument reent
is a pointer to a reentrancy structure.
wcstoll — wide string to long long
#include <wchar.h>
long long wcstoll( | const wchar_t *__restrict s, |
wchar_t **__restrict ptr, | |
int base) ; |
long long _wcstoll_r( | void *reent, |
const wchar_t *s, | |
wchar_t **ptr, | |
int base) ; |
The function wcstoll
converts the wide string *
to
a s
long long
. First, it breaks down the string into three parts:
leading whitespace, which is ignored; a subject string consisting
of characters resembling an integer in the radix specified by base
;
and a trailing portion consisting of zero or more unparseable characters,
and always including the terminating null character. Then, it attempts
to convert the subject string into a long long
and returns the
result.
If the value of base
is 0, the subject string is expected to look
like a normal C integer constant: an optional sign, a possible `0x
'
indicating a hexadecimal base, and a number. If base
is between
2 and 36, the expected form of the subject is a sequence of letters
and digits representing an integer in the radix specified by base
,
with an optional plus or minus sign. The letters a
--z
(or,
equivalently, A
--Z
) are used to signify values from 10 to 35;
only letters whose ascribed values are less than base
are
permitted. If base
is 16, a leading 0x
is permitted.
The subject sequence is the longest initial sequence of the input string that has the expected form, starting with the first non-whitespace character. If the string is empty or consists entirely of whitespace, or if the first non-whitespace character is not a permissible letter or digit, the subject string is empty.
If the subject string is acceptable, and the value of base
is zero,
wcstoll
attempts to determine the radix from the input string. A
string with a leading 0x
is treated as a hexadecimal value; a string with
a leading 0 and no x
is treated as octal; all other strings are
treated as decimal. If base
is between 2 and 36, it is used as the
conversion radix, as described above. If the subject string begins with
a minus sign, the value is negated. Finally, a pointer to the first
character past the converted subject string is stored in ptr
, if
ptr
is not NULL
.
If the subject string is empty (or not in acceptable form), no conversion
is performed and the value of s
is stored in ptr
(if ptr
is
not NULL
).
The alternate function _wcstoll_r
is a reentrant version. The
extra argument reent
is a pointer to a reentrancy structure.
wcstoul — wide string to unsigned long
#include <wchar.h>
unsigned long wcstoul( | const wchar_t *__restrict s, |
wchar_t **__restrict ptr, | |
int base) ; |
unsigned long _wcstoul_r( | void *reent, |
const wchar_t *s, | |
wchar_t **ptr, | |
int base) ; |
The function wcstoul
converts the wide string *
to
an s
unsigned long
. First, it breaks down the string into three parts:
leading whitespace, which is ignored; a subject string consisting
of the digits meaningful in the radix specified by base
(for example, 0
through 7
if the value of base
is 8);
and a trailing portion consisting of one or more unparseable characters,
which always includes the terminating null character. Then, it attempts
to convert the subject string into an unsigned long integer, and returns the
result.
If the value of base
is zero, the subject string is expected to look
like a normal C integer constant (save that no optional sign is permitted):
a possible 0x
indicating hexadecimal radix, and a number.
If base
is between 2 and 36, the expected form of the subject is a
sequence of digits (which may include letters, depending on the
base) representing an integer in the radix specified by base
.
The letters a
--z
(or A
--Z
) are used as digits valued from
10 to 35. If base
is 16, a leading 0x
is permitted.
The subject sequence is the longest initial sequence of the input string that has the expected form, starting with the first non-whitespace character. If the string is empty or consists entirely of whitespace, or if the first non-whitespace character is not a permissible digit, the subject string is empty.
If the subject string is acceptable, and the value of base
is zero,
wcstoul
attempts to determine the radix from the input string. A
string with a leading 0x
is treated as a hexadecimal value; a string with
a leading 0
and no x
is treated as octal; all other strings are
treated as decimal. If base
is between 2 and 36, it is used as the
conversion radix, as described above. Finally, a pointer to the first
character past the converted subject string is stored in ptr
, if
ptr
is not NULL
.
If the subject string is empty (that is, if *
s
does not start
with a substring in acceptable form), no conversion
is performed and the value of s
is stored in ptr
(if ptr
is
not NULL
).
The alternate function _wcstoul_r
is a reentrant version. The
extra argument reent
is a pointer to a reentrancy structure.
wcstoull — wide string to unsigned long long
#include <wchar.h>
unsigned long long wcstoull( | const wchar_t *__restrict s, |
wchar_t **__restrict ptr, | |
int base) ; |
unsigned long long _wcstoull_r( | void *reent, |
const wchar_t *s, | |
wchar_t **ptr, | |
int base) ; |
The function wcstoull
converts the wide string *
to
an s
unsigned long long
. First, it breaks down the string into three parts:
leading whitespace, which is ignored; a subject string consisting
of the digits meaningful in the radix specified by base
(for example, 0
through 7
if the value of base
is 8);
and a trailing portion consisting of one or more unparseable characters,
which always includes the terminating null character. Then, it attempts
to convert the subject string into an unsigned long long integer, and returns the
result.
If the value of base
is zero, the subject string is expected to look
like a normal C integer constant: an optional sign (+
or -
),
a possible 0x
indicating hexadecimal radix or a possible <0> indicating
octal radix, and a number.
If base
is between 2 and 36, the expected form of the subject is a
sequence of digits (which may include letters, depending on the
base) representing an integer in the radix specified by base
.
The letters a
--z
(or A
--Z
) are used as digits valued from
10 to 35. If base
is 16, a leading 0x
is permitted.
The subject sequence is the longest initial sequence of the input string that has the expected form, starting with the first non-whitespace character. If the string is empty or consists entirely of whitespace, or if the first non-whitespace character is not a permissible digit, the subject string is empty.
If the subject string is acceptable, and the value of base
is zero,
wcstoull
attempts to determine the radix from the input string. A
string with a leading 0x
is treated as a hexadecimal value; a string with
a leading 0
and no x
is treated as octal; all other strings are
treated as decimal. If base
is between 2 and 36, it is used as the
conversion radix, as described above. Finally, a pointer to the first
character past the converted subject string is stored in ptr
, if
ptr
is not NULL
.
If the subject string is empty (that is, if *
s
does not start
with a substring in acceptable form), no conversion
is performed and the value of s
is stored in ptr
(if ptr
is
not NULL
).
The alternate function _wcstoull_r
is a reentrant version. The
extra argument reent
is a pointer to a reentrancy structure.
system — execute command string
#include <stdlib.h>
int system( | char *s) ; |
int _system_r( | void *reent, |
char *s) ; |
Use system
to pass a command string *
to s
/bin/sh
on
your system, and wait for it to finish executing.
Use ``system(NULL)
'' to test whether your system has /bin/sh
available.
The alternate function _system_r
is a reentrant version. The
extra argument reent
is a pointer to a reentrancy structure.
system(NULL)
returns a non-zero value if /bin/sh
is available, and
0
if it is not.
With a command argument, the result of system
is the exit status
returned by /bin/sh
.
ANSI C requires system
, but leaves the nature and effects of a
command processor undefined. ANSI C does, however, specify that
system(NULL)
return zero or nonzero to report on the existence of
a command processor.
POSIX.2 requires system
, and requires that it invoke a sh
.
Where sh
is found is left unspecified.
Supporting OS subroutines required: _exit
, _execve
, _fork_r
,
_wait_r
.
utoa — unsigned integer to string
#include <stdlib.h>
char *utoa( | unsigned value, |
char *str, | |
int base) ; |
char *__utoa( | unsigned value, |
char *str, | |
int base) ; |
wcstombs — minimal wide char string to multibyte string converter
#include <stdlib.h>
size_t wcstombs( | char *restrict s, |
const wchar_t *restrict pwc, | |
size_t n) ; |
When _MB_CAPABLE is not defined, this is a minimal ANSI-conforming
implementation of wcstombs
. In this case,
all wide-characters are expected to represent single bytes and so
are converted simply by casting to char.
When _MB_CAPABLE is defined, this routine calls _wcstombs_r
to perform
the conversion, passing a state variable to allow state dependent
decoding. The result is based on the locale setting which may
be restricted to a defined set of locales.
This implementation of wcstombs
returns 0
if
s
is NULL
or is the empty string;
it returns -1
if _MB_CAPABLE and one of the
wide-char characters does not represent a valid multi-byte character;
otherwise it returns the minimum of: n
or the
number of bytes that are transferred to s
, not including the
nul terminator.
If the return value is -1, the state of the pwc
string is
indeterminate. If the input has a length of 0, the output
string will be modified to contain a wchar_t nul terminator if
n
> 0.
wctomb — minimal wide char to multibyte converter
#include <stdlib.h>
int wctomb( | char *s, |
wchar_t wchar) ; |
When _MB_CAPABLE is not defined, this is a minimal ANSI-conforming
implementation of wctomb
. The
only ``wide characters'' recognized are single bytes,
and they are ``converted'' to themselves.
When _MB_CAPABLE is defined, this routine calls _wctomb_r
to perform
the conversion, passing a state variable to allow state dependent
decoding. The result is based on the locale setting which may
be restricted to a defined set of locales.
Each call to wctomb
modifies *
unless s
s
is a null
pointer or _MB_CAPABLE is defined and wchar
is invalid.
This implementation of wctomb
returns 0
if
s
is NULL
; it returns -1
if _MB_CAPABLE is enabled
and the wchar is not a valid multi-byte character, it returns 1
if _MB_CAPABLE is not defined or the wchar is in reality a single
byte character, otherwise it returns the number of bytes in the
multi-byte character.
Table of Contents
This chapter groups macros (which are also available as subroutines) to classify characters into several categories (alphabetic, numeric, control characters, whitespace, and so on), or to perform simple character mappings.
The header file ctype.h
defines the macros.
isalnum — alphanumeric character predicate
#include <ctype.h>
int isalnum( | int c) ; |
isalnum
is a macro which classifies ASCII integer values by table
lookup. It is a predicate returning non-zero for alphabetic or
numeric ASCII characters, and 0
for other arguments. It is defined
only if c
is representable as an unsigned char or if c
is EOF.
You can use a compiled subroutine instead of the macro definition by
undefining the macro using `#undef isalnum
'.
isalpha — alphabetic character predicate
#include <ctype.h>
int isalpha( | int c) ; |
isalpha
is a macro which classifies ASCII integer values by table
lookup. It is a predicate returning non-zero when c
represents an
alphabetic ASCII character, and 0 otherwise. It is defined only if
c
is representable as an unsigned char or if c
is EOF.
You can use a compiled subroutine instead of the macro definition by
undefining the macro using `#undef isalpha
'.
isascii — ASCII character predicate
#include <ctype.h>
int isascii( | int c) ; |
isblank — blank character predicate
#include <ctype.h>
int isblank( | int c) ; |
iscntrl — control character predicate
#include <ctype.h>
int iscntrl( | int c) ; |
iscntrl
is a macro which classifies ASCII integer values by table
lookup. It is a predicate returning non-zero for control characters, and 0
for other characters. It is defined only if c
is representable as an
unsigned char or if c
is EOF.
You can use a compiled subroutine instead of the macro definition by
undefining the macro using `#undef iscntrl
'.
isdigit — decimal digit predicate
#include <ctype.h>
int isdigit( | int c) ; |
isdigit
is a macro which classifies ASCII integer values by table
lookup. It is a predicate returning non-zero for decimal digits, and 0 for
other characters. It is defined only if c
is representable as an
unsigned char or if c
is EOF.
You can use a compiled subroutine instead of the macro definition by
undefining the macro using `#undef isdigit
'.
islower — lowercase character predicate
#include <ctype.h>
int islower( | int c) ; |
islower
is a macro which classifies ASCII integer values by table
lookup. It is a predicate returning non-zero for minuscules
(lowercase alphabetic characters), and 0 for other characters.
It is defined only if c
is representable as an unsigned char or if
c
is EOF.
You can use a compiled subroutine instead of the macro definition by
undefining the macro using `#undef islower
'.
isprint — printable character predicates
#include <ctype.h>
int isprint( | int c) ; |
int isgraph( | int c) ; |
isprint
is a macro which classifies ASCII integer values by table
lookup. It is a predicate returning non-zero for printable
characters, and 0 for other character arguments.
It is defined only if c
is representable as an unsigned char or if
c
is EOF.
You can use a compiled subroutine instead of the macro definition by
undefining either macro using `#undef isprint
' or `#undef isgraph
'.
ispunct — punctuation character predicate
#include <ctype.h>
int ispunct( | int c) ; |
ispunct
is a macro which classifies ASCII integer values by table
lookup. It is a predicate returning non-zero for printable
punctuation characters, and 0 for other characters. It is defined only
if c
is representable as an unsigned char or if c
is EOF.
You can use a compiled subroutine instead of the macro definition by
undefining the macro using `#undef ispunct
'.
isspace — whitespace character predicate
#include <ctype.h>
int isspace( | int c) ; |
isspace
is a macro which classifies ASCII integer values by table
lookup. It is a predicate returning non-zero for whitespace
characters, and 0 for other characters. It is defined only when isascii
(c
) is true or c
is EOF.
You can use a compiled subroutine instead of the macro definition by
undefining the macro using `#undef isspace
'.
isupper — uppercase character predicate
#include <ctype.h>
int isupper( | int c) ; |
isupper
is a macro which classifies ASCII integer values by table
lookup. It is a predicate returning non-zero for uppercase letters
(A
--Z
), and 0 for other characters. It is defined only when
isascii
(c
) is true or c
is EOF.
You can use a compiled subroutine instead of the macro definition by
undefining the macro using `#undef isupper
'.
isxdigit — hexadecimal digit predicate
#include <ctype.h>
int isxdigit( | int c) ; |
isxdigit
is a macro which classifies ASCII integer values by table
lookup. It is a predicate returning non-zero for hexadecimal digits,
and 0
for other characters. It is defined only if c
is
representable as an unsigned char or if c
is EOF.
You can use a compiled subroutine instead of the macro definition by
undefining the macro using `#undef isxdigit
'.
toascii — force integers to ASCII range
#include <ctype.h>
int toascii( | int c) ; |
tolower — translate characters to lowercase
#include <ctype.h>
int tolower( | int c) ; |
int _tolower( | int c) ; |
tolower
is a macro which converts uppercase characters to lowercase,
leaving all other characters unchanged. It is only defined when
c
is an integer in the range EOF
to 255
.
You can use a compiled subroutine instead of the macro definition by
undefining this macro using `#undef tolower
'.
_tolower
performs the same conversion as tolower
, but should
only be used when c
is known to be an uppercase character (A
--Z
).
toupper — translate characters to uppercase
#include <ctype.h>
int toupper( | int c) ; |
int _toupper( | int c) ; |
toupper
is a macro which converts lowercase characters to uppercase,
leaving all other characters unchanged. It is only defined when
c
is an integer in the range EOF
to 255
.
You can use a compiled subroutine instead of the macro definition by
undefining this macro using `#undef toupper
'.
_toupper
performs the same conversion as toupper
, but should
only be used when c
is known to be a lowercase character (a
--z
).
iswcntrl — control wide character test
#include <wctype.h>
int iswcntrl( | wint_t c) ; |
iswblank — blank wide character test
#include <wctype.h>
int iswblank( | wint_t c) ; |
iswlower — lowercase wide character test
#include <wctype.h>
int iswlower( | wint_t c) ; |
iswspace — whitespace wide character test
#include <wctype.h>
int iswspace( | wint_t c) ; |
iswupper — uppercase wide character test
#include <wctype.h>
int iswupper( | wint_t c) ; |
iswxdigit — hexadecimal digit wide character test
#include <wctype.h>
int iswxdigit( | wint_t c) ; |
iswctype — extensible wide-character test
#include <wctype.h>
int iswctype( | wint_t c, |
wctype_t desc) ; |
iswctype
is a function which classifies wide-character values using the
wide-character test specified by desc
.
wctype — get wide-character classification type
#include <wctype.h>
wctype_t wctype( | const char *c) ; |
wctype
is a function which takes a string c
and gives back
the appropriate wctype_t type value associated with the string,
if one exists. The following values are guaranteed to be recognized:
"alnum", "alpha", "blank", "cntrl", "digit", "graph", "lower", "print",
"punct", "space", "upper", and "xdigit".
towlower — translate wide characters to lowercase
#include <wctype.h>
wint_t towlower( | wint_t c) ; |
towlower
is a function which converts uppercase wide characters to
lowercase, leaving all other characters unchanged.
towupper — translate wide characters to uppercase
#include <wctype.h>
wint_t towupper( | wint_t c) ; |
towupper
is a function which converts lowercase wide characters to
uppercase, leaving all other characters unchanged.
towctrans — extensible wide-character translation
#include <wctype.h>
wint_t towctrans( | wint_t c, |
wctrans_t w) ; |
towctrans
is a function which converts wide characters based on
a specified translation type w
. If the translation type is
invalid or cannot be applied to the current character, no change
to the character is made.
wctrans — get wide-character translation type
#include <wctype.h>
wctrans_t wctrans( | const char *c) ; |
wctrans
is a function which takes a string c
and gives back
the appropriate wctrans_t type value associated with the string,
if one exists. The following values are guaranteed to be recognized:
"tolower" and "toupper".
Table of Contents
fgets
instead)This chapter comprises functions to manage files or other input/output streams. Among these functions are subroutines to generate or scan strings according to specifications from a format string.
The underlying facilities for input and output depend on the host system, but these functions provide a uniform interface.
The corresponding declarations are in stdio.h
.
The reentrant versions of these functions use macros
_stdin_r(reent
)
_stdout_r(reent
)
_stderr_r(reent
)
instead of the globals stdin
, stdout
, and
stderr
. The argument reent
is a pointer to a reentrancy
structure.
clearerr — clear file or stream error indicator
#include <stdio.h>
void clearerr( | FILE *fp) ; |
#define _BSD_SOURCE
#include <stdio.h>
void clearerr_unlocked( | FILE *fp) ; |
The stdio
functions maintain an error indicator with each file
pointer fp
, to record whether any read or write errors have
occurred on the associated file or stream. Similarly, it maintains an
end-of-file indicator to record whether there is no more data in the
file.
Use clearerr
to reset both of these indicators.
See ferror
and feof
to query the two indicators.
clearerr_unlocked
is a non-thread-safe version of clearerr
.
clearerr_unlocked
may only safely be used within a scope
protected by flockfile() (or ftrylockfile()) and funlockfile(). This
function may safely be used in a multi-threaded program if and only
if they are called while the invoking thread owns the (FILE *)
object, as is the case after a successful call to the flockfile() or
ftrylockfile() functions. If threads are disabled, then
clearerr_unlocked
is equivalent to clearerr
.
diprintf — print to a file descriptor (integer only)
#include <stdio.h>
#include <stdarg.h>
int diprintf( | int fd, | |
const char *format, | ||
...) ; |
int vdiprintf( | int fd, |
const char *format, | |
va_list ap) ; |
int _diprintf_r( | struct _reent *ptr, | |
int fd, | ||
const char *format, | ||
...) ; |
int _vdiprintf_r( | struct _reent *ptr, |
int fd, | |
const char *format, | |
va_list ap) ; |
dprintf — print to a file descriptor
#include <stdio.h>
#include <stdarg.h>
int dprintf( | int fd, | |
const char *restrict format, | ||
...) ; |
int vdprintf( | int fd, |
const char *restrict format, | |
va_list ap) ; |
int _dprintf_r( | struct _reent *ptr, | |
int fd, | ||
const char *restrict format, | ||
...) ; |
int _vdprintf_r( | struct _reent *ptr, |
int fd, | |
const char *restrict format, | |
va_list ap) ; |
dprintf
and vdprintf
allow printing a format, similarly to
printf
, but write to a file descriptor instead of to a FILE
stream.
The functions _dprintf_r
and _vdprintf_r
are simply
reentrant versions of the functions above.
fclose — close a file
#include <stdio.h>
int fclose( | FILE *fp) ; |
int _fclose_r( | struct _reent *reent, |
FILE *fp) ; |
If the file or stream identified by fp
is open, fclose
closes
it, after first ensuring that any pending data is written (by calling
fflush(
).
fp
)
The alternate function _fclose_r
is a reentrant version.
The extra argument reent
is a pointer to a reentrancy structure.
fcloseall — close all files
#include <stdio.h>
int fcloseall( | void) ; |
int _fcloseall_r( | struct _reent *ptr) ; |
fdopen — turn open file into a stream
#include <stdio.h>
FILE *fdopen( | int fd, |
const char *mode) ; |
FILE *_fdopen_r( | struct _reent *reent, |
int fd, | |
const char *mode) ; |
feof — test for end of file
#include <stdio.h>
int feof( | FILE *fp) ; |
#define _BSD_SOURCE
#include <stdio.h>
int feof_unlocked( | FILE *fp) ; |
feof
tests whether or not the end of the file identified by fp
has been reached.
feof_unlocked
is a non-thread-safe version of feof
.
feof_unlocked
may only safely be used within a scope
protected by flockfile() (or ftrylockfile()) and funlockfile(). This
function may safely be used in a multi-threaded program if and only
if they are called while the invoking thread owns the (FILE *)
object, as is the case after a successful call to the flockfile() or
ftrylockfile() functions. If threads are disabled, then
feof_unlocked
is equivalent to feof
.
ferror — test whether read/write error has occurred
#include <stdio.h>
int ferror( | FILE *fp) ; |
#define _BSD_SOURCE
#include <stdio.h>
int ferror_unlocked( | FILE *fp) ; |
The stdio
functions maintain an error indicator with each file
pointer fp
, to record whether any read or write errors have
occurred on the associated file or stream.
Use ferror
to query this indicator.
See clearerr
to reset the error indicator.
ferror_unlocked
is a non-thread-safe version of ferror
.
ferror_unlocked
may only safely be used within a scope
protected by flockfile() (or ftrylockfile()) and funlockfile(). This
function may safely be used in a multi-threaded program if and only
if they are called while the invoking thread owns the (FILE *)
object, as is the case after a successful call to the flockfile() or
ftrylockfile() functions. If threads are disabled, then
ferror_unlocked
is equivalent to ferror
.
fflush — flush buffered file output
#include <stdio.h>
int fflush( | FILE *fp) ; |
#define _BSD_SOURCE
#include <stdio.h>
int fflush_unlocked( | FILE *fp) ; |
#include <stdio.h>
int _fflush_r( | struct _reent *reent, |
FILE *fp) ; |
#define _BSD_SOURCE
#include <stdio.h>
int _fflush_unlocked_r( | struct _reent *reent, |
FILE *fp) ; |
The stdio
output functions can buffer output before delivering it
to the host system, in order to minimize the overhead of system calls.
Use fflush
to deliver any such pending output (for the file
or stream identified by fp
) to the host system.
If fp
is NULL
, fflush
delivers pending output from all
open files.
Additionally, if fp
is a seekable input stream visiting a file
descriptor, set the position of the file descriptor to match next
unread byte, useful for obeying POSIX semantics when ending a process
without consuming all input from the stream.
fflush_unlocked
is a non-thread-safe version of fflush
.
fflush_unlocked
may only safely be used within a scope
protected by flockfile() (or ftrylockfile()) and funlockfile(). This
function may safely be used in a multi-threaded program if and only
if they are called while the invoking thread owns the (FILE *)
object, as is the case after a successful call to the flockfile() or
ftrylockfile() functions. If threads are disabled, then
fflush_unlocked
is equivalent to fflush
.
The alternate functions _fflush_r
and _fflush_unlocked_r
are
reentrant versions, where the extra argument reent
is a pointer to
a reentrancy structure, and fp
must not be NULL.
fgetc — get a character from a file or stream
#include <stdio.h>
int fgetc( | FILE *fp) ; |
#define _BSD_SOURCE
#include <stdio.h>
int fgetc_unlocked( | FILE *fp) ; |
#include <stdio.h>
int _fgetc_r( | struct _reent *ptr, |
FILE *fp) ; |
#define _BSD_SOURCE
#include <stdio.h>
int _fgetc_unlocked_r( | struct _reent *ptr, |
FILE *fp) ; |
Use fgetc
to get the next single character from the file or stream
identified by fp
. As a side effect, fgetc
advances the file's
current position indicator.
For a macro version of this function, see getc
.
fgetc_unlocked
is a non-thread-safe version of fgetc
.
fgetc_unlocked
may only safely be used within a scope
protected by flockfile() (or ftrylockfile()) and funlockfile(). This
function may safely be used in a multi-threaded program if and only
if they are called while the invoking thread owns the (FILE *)
object, as is the case after a successful call to the flockfile() or
ftrylockfile() functions. If threads are disabled, then
fgetc_unlocked
is equivalent to fgetc
.
The functions _fgetc_r
and _fgetc_unlocked_r
are simply reentrant
versions that are passed the additional reentrant structure pointer
argument: ptr
.
fgetpos — record position in a stream or file
#include <stdio.h>
int fgetpos( | FILE *restrict fp, |
fpos_t *restrict pos) ; |
int _fgetpos_r( | struct _reent *ptr, |
FILE *restrict fp, | |
fpos_t *restrict pos) ; |
Objects of type FILE
can have a ``position'' that records how much
of the file your program has already read. Many of the stdio
functions
depend on this position, and many change it as a side effect.
You can use fgetpos
to report on the current position for a file
identified by fp
; fgetpos
will write a value
representing that position at *
. Later, you can
use this value with pos
fsetpos
to return the file to this
position.
In the current implementation, fgetpos
simply uses a character
count to represent the file position; this is the same number that
would be returned by ftell
.
fgetpos
returns 0
when successful. If fgetpos
fails, the
result is 1
. Failure occurs on streams that do not support
positioning; the global errno
indicates this condition with the
value ESPIPE
.
fgetpos
is required by the ANSI C standard, but the meaning of the
value it records is not specified beyond requiring that it be
acceptable as an argument to fsetpos
. In particular, other
conforming C implementations may return a different result from
ftell
than what fgetpos
writes at *
.
pos
No supporting OS subroutines are required.
fgets — get character string from a file or stream
#include <stdio.h>
char *fgets( | char *restrict buf, |
int n, | |
FILE *restrict fp) ; |
#define _GNU_SOURCE
#include <stdio.h>
char *fgets_unlocked( | char *restrict buf, |
int n, | |
FILE *restrict fp) ; |
#include <stdio.h>
char *_fgets_r( | struct _reent *ptr, |
char *restrict buf, | |
int n, | |
FILE *restrict fp) ; |
#include <stdio.h>
char *_fgets_unlocked_r( | struct _reent *ptr, |
char *restrict buf, | |
int n, | |
FILE *restrict fp) ; |
Reads at most n-1
characters from fp
until a newline
is found. The characters including to the newline are stored
in buf
. The buffer is terminated with a 0.
fgets_unlocked
is a non-thread-safe version of fgets
.
fgets_unlocked
may only safely be used within a scope
protected by flockfile() (or ftrylockfile()) and funlockfile(). This
function may safely be used in a multi-threaded program if and only
if they are called while the invoking thread owns the (FILE *)
object, as is the case after a successful call to the flockfile() or
ftrylockfile() functions. If threads are disabled, then
fgets_unlocked
is equivalent to fgets
.
The functions _fgets_r
and _fgets_unlocked_r
are simply
reentrant versions that are passed the additional reentrant structure
pointer argument: ptr
.
fgetwc — get a wide character from a file or stream
#include <stdio.h>
#include <wchar.h>
wint_t fgetwc( | FILE *fp) ; |
#define _GNU_SOURCE
#include <stdio.h>
#include <wchar.h>
wint_t fgetwc_unlocked( | FILE *fp) ; |
#include <stdio.h>
#include <wchar.h>
wint_t _fgetwc_r( | struct _reent *ptr, |
FILE *fp) ; |
#include <stdio.h>
#include <wchar.h>
wint_t _fgetwc_unlocked_r( | struct _reent *ptr, |
FILE *fp) ; |
#include <stdio.h>
#include <wchar.h>
wint_t getwc( | FILE *fp) ; |
#define _GNU_SOURCE
#include <stdio.h>
#include <wchar.h>
wint_t getwc_unlocked( | FILE *fp) ; |
#include <stdio.h>
#include <wchar.h>
wint_t _getwc_r( | struct _reent *ptr, |
FILE *fp) ; |
#include <stdio.h>
#include <wchar.h>
wint_t _getwc_unlocked_r( | struct _reent *ptr, |
FILE *fp) ; |
Use fgetwc
to get the next wide character from the file or stream
identified by fp
. As a side effect, fgetwc
advances the file's
current position indicator.
fgetwc_unlocked
is a non-thread-safe version of fgetwc
.
fgetwc_unlocked
may only safely be used within a scope
protected by flockfile() (or ftrylockfile()) and funlockfile(). This
function may safely be used in a multi-threaded program if and only
if they are called while the invoking thread owns the (FILE *)
object, as is the case after a successful call to the flockfile() or
ftrylockfile() functions. If threads are disabled, then
fgetwc_unlocked
is equivalent to fgetwc
.
The getwc
and getwc_unlocked
functions or macros functions identically
to fgetwc
and fgetwc_unlocked
. It may be implemented as a macro, and
may evaluate its argument more than once. There is no reason ever to use it.
_fgetwc_r
, _getwc_r
, _fgetwc_unlocked_r
, and _getwc_unlocked_r
are simply reentrant versions of the above functions that are passed the
additional reentrant structure pointer argument: ptr
.
fgetws — get wide character string from a file or stream
#include <wchar.h>
wchar_t *fgetws( | wchar_t *__restrict ws, |
int n, | |
FILE *__restrict fp) ; |
#define _GNU_SOURCE
#include <wchar.h>
wchar_t *fgetws_unlocked( | wchar_t *__restrict ws, |
int n, | |
FILE *__restrict fp) ; |
#include <wchar.h>
wchar_t *_fgetws_r( | struct _reent *ptr, |
wchar_t *ws, | |
int n, | |
FILE *fp) ; |
#include <wchar.h>
wchar_t *_fgetws_unlocked_r( | struct _reent *ptr, |
wchar_t *ws, | |
int n, | |
FILE *fp) ; |
Reads at most n-1
wide characters from fp
until a newline
is found. The wide characters including to the newline are stored
in ws
. The buffer is terminated with a 0.
fgetws_unlocked
is a non-thread-safe version of fgetws
.
fgetws_unlocked
may only safely be used within a scope
protected by flockfile() (or ftrylockfile()) and funlockfile(). This
function may safely be used in a multi-threaded program if and only
if they are called while the invoking thread owns the (FILE *)
object, as is the case after a successful call to the flockfile() or
ftrylockfile() functions. If threads are disabled, then
fgetws_unlocked
is equivalent to fgetws
.
The _fgetws_r
and _fgetws_unlocked_r
functions are simply reentrant
version of the above and are passed an additional reentrancy structure
pointer: ptr
.
fileno — return file descriptor associated with stream
#include <stdio.h>
int fileno( | FILE *fp) ; |
#define _BSD_SOURCE
#include <stdio.h>
int fileno_unlocked( | FILE *fp) ; |
You can use fileno
to return the file descriptor identified by fp
.
fileno_unlocked
is a non-thread-safe version of fileno
.
fileno_unlocked
may only safely be used within a scope
protected by flockfile() (or ftrylockfile()) and funlockfile(). This
function may safely be used in a multi-threaded program if and only
if they are called while the invoking thread owns the (FILE *)
object, as is the case after a successful call to the flockfile() or
ftrylockfile() functions. If threads are disabled, then
fileno_unlocked
is equivalent to fileno
.
fmemopen — open a stream around a fixed-length string
#include <stdio.h>
FILE *fmemopen( | void *restrict buf, |
size_t size, | |
const char *restrict mode) ; |
fmemopen
creates a seekable FILE
stream that wraps a
fixed-length buffer of size
bytes starting at buf
. The stream
is opened with mode
treated as in fopen
, where append mode
starts writing at the first NUL byte. If buf
is NULL, then
size
bytes are automatically provided as if by malloc
, with
the initial size of 0, and mode
must contain +
so that data
can be read after it is written.
The stream maintains a current position, which moves according to
bytes read or written, and which can be one past the end of the array.
The stream also maintains a current file size, which is never greater
than size
. If mode
starts with r
, the position starts at
0
, and file size starts at size
if buf
was provided. If
mode
starts with w
, the position and file size start at 0
,
and if buf
was provided, the first byte is set to NUL. If
mode
starts with a
, the position and file size start at the
location of the first NUL byte, or else size
if buf
was
provided.
When reading, NUL bytes have no significance, and reads cannot exceed
the current file size. When writing, the file size can increase up to
size
as needed, and NUL bytes may be embedded in the stream (see
open_memstream
for an alternative that automatically enlarges the
buffer). When the stream is flushed or closed after a write that
changed the file size, a NUL byte is written at the current position
if there is still room; if the stream is not also open for reading, a
NUL byte is additionally written at the last byte of buf
when the
stream has exceeded size
, so that a write-only buf
is always
NUL-terminated when the stream is flushed or closed (and the initial
size
should take this into account). It is not possible to seek
outside the bounds of size
. A NUL byte written during a flush is
restored to its previous value when seeking elsewhere in the string.
fopen — open a file
#include <stdio.h>
FILE *fopen( | const char *file, |
const char *mode) ; |
FILE *_fopen_r( | struct _reent *reent, |
const char *file, | |
const char *mode) ; |
fopen
initializes the data structures needed to read or write a
file. Specify the file's name as the string at file
, and the kind
of access you need to the file with the string at mode
.
The alternate function _fopen_r
is a reentrant version.
The extra argument reent
is a pointer to a reentrancy structure.
Three fundamental kinds of access are available: read, write, and append.
*
must begin with one of the three characters `mode
r
',
`w
', or `a
', to select one of these:
r
| Open the file for reading; the operation will fail if the file does not exist, or if the host system does not permit you to read it. |
w
| Open the file for writing from the beginning of the file: effectively, this always creates a new file. If the file whose name you specified already existed, its old contents are discarded. |
a
|
Open the file for appending data, that is writing from the end of
file. When you open a file this way, all data always goes to the
current end of file; you cannot change this using |
Some host systems distinguish between ``binary'' and ``text'' files.
Such systems may perform data transformations on data written to, or
read from, files opened as ``text''.
If your system is one of these, then you can append a `b
' to any
of the three modes above, to specify that you are opening the file as
a binary file (the default is to open the file as a text file).
`rb
', then, means ``read binary''; `wb
', ``write binary''; and
`ab
', ``append binary''.
To make C programs more portable, the `b
' is accepted on all
systems, whether or not it makes a difference.
Finally, you might need to both read and write from the same file.
You can also append a `+
' to any of the three modes, to permit
this. (If you want to append both `b
' and `+
', you can do it
in either order: for example, "rb+"
means the same thing as
"r+b"
when used as a mode string.)
Use "r+"
(or "rb+"
) to permit reading and writing anywhere in
an existing file, without discarding any data; "w+"
(or "wb+"
)
to create a new file (or begin by discarding all data from an old one)
that permits reading and writing anywhere in it; and "a+"
(or
"ab+"
) to permit reading anywhere in an existing file, but writing
only at the end.
fopencookie — open a stream with custom callbacks
#include <stdio.h>
FILE *fopencookie( | const void *cookie, |
const char *mode, | |
cookie_io_functions_t functions) ; |
fopencookie
creates a FILE
stream where I/O is performed using
custom callbacks. The callbacks are registered via the structure:
typedef ssize_t (*cookie_read_function_t)(void *_cookie, char *_buf, size_t _n); typedef ssize_t (*cookie_write_function_t)(void *_cookie, const char *_buf, size_t _n); typedef int (*cookie_seek_function_t)(void *_cookie, off_t *_off, int _whence); typedef int (*cookie_close_function_t)(void *_cookie);
typedef struct { cookie_read_function_t *read; cookie_write_function_t *write; cookie_seek_function_t *seek; cookie_close_function_t *close; } cookie_io_functions_t;
The stream is opened with mode
treated as in fopen
. The
callbacks functions.read
and functions.write
may only be NULL
when mode
does not require them.
functions.read
should return -1 on failure, or else the number of
bytes read (0 on EOF). It is similar to read
, except that
cookie
will be passed as the first argument.
functions.write
should return -1 on failure, or else the number of
bytes written. It is similar to write
, except that cookie
will be passed as the first argument.
functions.seek
should return -1 on failure, and 0 on success, with
_off
set to the current file position. It is a cross between
lseek
and fseek
, with the _whence
argument interpreted in
the same manner. A NULL functions.seek
makes the stream behave
similarly to a pipe in relation to stdio functions that require
positioning.
functions.close
should return -1 on failure, or 0 on success. It
is similar to close
, except that cookie
will be passed as the
first argument. A NULL functions.close
merely flushes all data
then lets fclose
succeed. A failed close will still invalidate
the stream.
Read and write I/O functions are allowed to change the underlying
buffer on fully buffered or line buffered streams by calling
setvbuf
. They are also not required to completely fill or empty
the buffer. They are not, however, allowed to change streams from
unbuffered to buffered or to change the state of the line buffering
flag. They must also be prepared to have read or write calls occur on
buffers other than the one most recently specified.
fpurge — discard pending file I/O
#include <stdio.h>
int fpurge( | FILE *fp) ; |
int _fpurge_r( | struct _reent *reent, |
FILE *fp) ; |
#include <stdio.h>
#include <stdio_ext.h>
void __fpurge( | FILE *fp) ; |
Use fpurge
to clear all buffers of the given stream. For output
streams, this discards data not yet written to disk. For input streams,
this discards any data from ungetc
and any data retrieved from disk
but not yet read via getc
. This is more severe than fflush
,
and generally is only needed when manually altering the underlying file
descriptor of a stream.
__fpurge
behaves exactly like fpurge
but does not return a value.
The alternate function _fpurge_r
is a reentrant version, where the
extra argument reent
is a pointer to a reentrancy structure, and
fp
must not be NULL.
fputc — write a character on a stream or file
#include <stdio.h>
int fputc( | int ch, |
FILE *fp) ; |
#define _BSD_SOURCE
#include <stdio.h>
int fputc_unlocked( | int ch, |
FILE *fp) ; |
#include <stdio.h>
int _fputc_r( | struct _rent *ptr, |
int ch, | |
FILE *fp) ; |
#include <stdio.h>
int _fputc_unlocked_r( | struct _rent *ptr, |
int ch, | |
FILE *fp) ; |
fputc
converts the argument ch
from an int
to an
unsigned char
, then writes it to the file or stream identified by
fp
.
If the file was opened with append mode (or if the stream cannot support positioning), then the new character goes at the end of the file or stream. Otherwise, the new character is written at the current value of the position indicator, and the position indicator oadvances by one.
For a macro version of this function, see putc
.
fputc_unlocked
is a non-thread-safe version of fputc
.
fputc_unlocked
may only safely be used within a scope
protected by flockfile() (or ftrylockfile()) and funlockfile(). This
function may safely be used in a multi-threaded program if and only
if they are called while the invoking thread owns the (FILE *)
object, as is the case after a successful call to the flockfile() or
ftrylockfile() functions. If threads are disabled, then
fputc_unlocked
is equivalent to fputc
.
The _fputc_r
and _fputc_unlocked_r
functions are simply reentrant
versions of the above that take an additional reentrant structure
argument: ptr
.
fputs — write a character string in a file or stream
#include <stdio.h>
int fputs( | const char *restrict s, |
FILE *restrict fp) ; |
#define _GNU_SOURCE
#include <stdio.h>
int fputs_unlocked( | const char *restrict s, |
FILE *restrict fp) ; |
#include <stdio.h>
int _fputs_r( | struct _reent *ptr, |
const char *restrict s, | |
FILE *restrict fp) ; |
#include <stdio.h>
int _fputs_unlocked_r( | struct _reent *ptr, |
const char *restrict s, | |
FILE *restrict fp) ; |
fputs
writes the string at s
(but without the trailing null)
to the file or stream identified by fp
.
fputs_unlocked
is a non-thread-safe version of fputs
.
fputs_unlocked
may only safely be used within a scope
protected by flockfile() (or ftrylockfile()) and funlockfile(). This
function may safely be used in a multi-threaded program if and only
if they are called while the invoking thread owns the (FILE *)
object, as is the case after a successful call to the flockfile() or
ftrylockfile() functions. If threads are disabled, then
fputs_unlocked
is equivalent to fputs
.
_fputs_r
and _fputs_unlocked_r
are simply reentrant versions of the
above that take an additional reentrant struct pointer argument: ptr
.
fputwc — write a wide character on a stream or file
#include <stdio.h>
#include <wchar.h>
wint_t fputwc( | wchar_t wc, |
FILE *fp) ; |
#define _GNU_SOURCE
#include <stdio.h>
#include <wchar.h>
wint_t fputwc_unlocked( | wchar_t wc, |
FILE *fp) ; |
#include <stdio.h>
#include <wchar.h>
wint_t _fputwc_r( | struct _reent *ptr, |
wchar_t wc, | |
FILE *fp) ; |
#include <stdio.h>
#include <wchar.h>
wint_t _fputwc_unlocked_r( | struct _reent *ptr, |
wchar_t wc, | |
FILE *fp) ; |
#include <stdio.h>
#include <wchar.h>
wint_t putwc( | wchar_t wc, |
FILE *fp) ; |
#define _GNU_SOURCE
#include <stdio.h>
#include <wchar.h>
wint_t putwc_unlocked( | wchar_t wc, |
FILE *fp) ; |
#include <stdio.h>
#include <wchar.h>
wint_t _putwc_r( | struct _reent *ptr, |
wchar_t wc, | |
FILE *fp) ; |
#include <stdio.h>
#include <wchar.h>
wint_t _putwc_unlocked_r( | struct _reent *ptr, |
wchar_t wc, | |
FILE *fp) ; |
fputwc
writes the wide character argument wc
to the file or
stream identified by fp
.
If the file was opened with append mode (or if the stream cannot support positioning), then the new wide character goes at the end of the file or stream. Otherwise, the new wide character is written at the current value of the position indicator, and the position indicator oadvances by one.
fputwc_unlocked
is a non-thread-safe version of fputwc
.
fputwc_unlocked
may only safely be used within a scope
protected by flockfile() (or ftrylockfile()) and funlockfile(). This
function may safely be used in a multi-threaded program if and only
if they are called while the invoking thread owns the (FILE *)
object, as is the case after a successful call to the flockfile() or
ftrylockfile() functions. If threads are disabled, then
fputwc_unlocked
is equivalent to fputwc
.
The putwc
and putwc_unlocked
functions or macros function identically
to fputwc
and fputwc_unlocked
. They may be implemented as a macro, and
may evaluate its argument more than once. There is no reason ever to use them.
The _fputwc_r
, _putwc_r
, _fputwc_unlocked_r
, and
_putwc_unlocked_r
functions are simply reentrant versions of the above
that take an additional reentrant structure argument: ptr
.
fputws — write a wide character string in a file or stream
#include <wchar.h>
int fputws( | const wchar_t *__restrict ws, |
FILE *__restrict fp) ; |
#define _GNU_SOURCE
#include <wchar.h>
int fputws_unlocked( | const wchar_t *__restrict ws, |
FILE *__restrict fp) ; |
#include <wchar.h>
int _fputws_r( | struct _reent *ptr, |
const wchar_t *ws, | |
FILE *fp) ; |
#include <wchar.h>
int _fputws_unlocked_r( | struct _reent *ptr, |
const wchar_t *ws, | |
FILE *fp) ; |
fputws
writes the wide character string at ws
(but without the
trailing null) to the file or stream identified by fp
.
fputws_unlocked
is a non-thread-safe version of fputws
.
fputws_unlocked
may only safely be used within a scope
protected by flockfile() (or ftrylockfile()) and funlockfile(). This
function may safely be used in a multi-threaded program if and only
if they are called while the invoking thread owns the (FILE *)
object, as is the case after a successful call to the flockfile() or
ftrylockfile() functions. If threads are disabled, then
fputws_unlocked
is equivalent to fputws
.
_fputws_r
and _fputws_unlocked_r
are simply reentrant versions of the
above that take an additional reentrant struct pointer argument: ptr
.
fread — read array elements from a file
#include <stdio.h>
size_t fread( | void *restrict buf, |
size_t size, | |
size_t count, | |
FILE *restrict fp) ; |
#define _BSD_SOURCE
#include <stdio.h>
size_t fread_unlocked( | void *restrict buf, |
size_t size, | |
size_t count, | |
FILE *restrict fp) ; |
#include <stdio.h>
size_t _fread_r( | struct _reent *ptr, |
void *restrict buf, | |
size_t size, | |
size_t count, | |
FILE *restrict fp) ; |
#include <stdio.h>
size_t _fread_unlocked_r( | struct _reent *ptr, |
void *restrict buf, | |
size_t size, | |
size_t count, | |
FILE *restrict fp) ; |
fread
attempts to copy, from the file or stream identified by
fp
, count
elements (each of size size
) into memory,
starting at buf
. fread
may copy fewer elements than
count
if an error, or end of file, intervenes.
fread
also advances the file position indicator (if any) for
fp
by the number of characters actually read.
fread_unlocked
is a non-thread-safe version of fread
.
fread_unlocked
may only safely be used within a scope
protected by flockfile() (or ftrylockfile()) and funlockfile(). This
function may safely be used in a multi-threaded program if and only
if they are called while the invoking thread owns the (FILE *)
object, as is the case after a successful call to the flockfile() or
ftrylockfile() functions. If threads are disabled, then
fread_unlocked
is equivalent to fread
.
_fread_r
and _fread_unlocked_r
are simply reentrant versions of the
above that take an additional reentrant structure pointer argument: ptr
.
freopen — open a file using an existing file descriptor
#include <stdio.h>
FILE *freopen( | const char *restrict file, |
const char *restrict mode, | |
FILE *restrict fp) ; |
FILE *_freopen_r( | struct _reent *ptr, |
const char *restrict file, | |
const char *restrict mode, | |
FILE *restrict fp) ; |
Use this variant of fopen
if you wish to specify a particular file
descriptor fp
(notably stdin
, stdout
, or stderr
) for
the file.
If fp
was associated with another file or stream, freopen
closes that other file or stream (but ignores any errors while closing
it).
file
and mode
are used just as in fopen
.
If file
is NULL
, the underlying stream is modified rather than
closed. The file cannot be given a more permissive access mode (for
example, a mode
of "w" will fail on a read-only file descriptor),
but can change status such as append or binary mode. If modification
is not possible, failure occurs.
fseek — set file position
#include <stdio.h>
int fseek( | FILE *fp, |
long offset, | |
int whence) ; |
int fseeko( | FILE *fp, |
off_t offset, | |
int whence) ; |
int _fseek_r( | struct _reent *ptr, |
FILE *fp, | |
long offset, | |
int whence) ; |
int _fseeko_r( | struct _reent *ptr, |
FILE *fp, | |
off_t offset, | |
int whence) ; |
Objects of type FILE
can have a ``position'' that records how much
of the file your program has already read. Many of the stdio
functions
depend on this position, and many change it as a side effect.
You can use fseek
/fseeko
to set the position for the file identified by
fp
. The value of offset
determines the new position, in one
of three ways selected by the value of whence
(defined as macros
in `stdio.h
'):
SEEK_SET
---offset
is the absolute file position (an offset
from the beginning of the file) desired. offset
must be positive.
SEEK_CUR
---offset
is relative to the current file position.
offset
can meaningfully be either positive or negative.
SEEK_END
---offset
is relative to the current end of file.
offset
can meaningfully be either positive (to increase the size
of the file) or negative.
See ftell
/ftello
to determine the current file position.
__fsetlocking — set or query locking mode on FILE stream
#include <stdio.h>
#include <stdio_ext.h>
int __fsetlocking( | FILE *fp, |
int type) ; |
This function sets how the stdio functions handle locking of FILE fp
.
The following values describe type
:
FSETLOCKING_INTERNAL
is the default state, where stdio functions
automatically lock and unlock the stream.
FSETLOCKING_BYCALLER
means that automatic locking in stdio functions
is disabled. Applications which set this take all responsibility for file
locking themselves.
FSETLOCKING_QUERY
returns the current locking mode without changing it.
fsetpos — restore position of a stream or file
#include <stdio.h>
int fsetpos( | FILE *fp, |
const fpos_t *pos) ; |
int _fsetpos_r( | struct _reent *ptr, |
FILE *fp, | |
const fpos_t *pos) ; |
Objects of type FILE
can have a ``position'' that records how much
of the file your program has already read. Many of the stdio
functions
depend on this position, and many change it as a side effect.
You can use fsetpos
to return the file identified by fp
to a previous
position *
(after first recording it with pos
fgetpos
).
See fseek
for a similar facility.
ftell — return position in a stream or file
#include <stdio.h>
long ftell( | FILE *fp) ; |
off_t ftello( | FILE *fp) ; |
long _ftell_r( | struct _reent *ptr, |
FILE *fp) ; |
off_t _ftello_r( | struct _reent *ptr, |
FILE *fp) ; |
Objects of type FILE
can have a ``position'' that records how much
of the file your program has already read. Many of the stdio
functions
depend on this position, and many change it as a side effect.
The result of ftell
/ftello
is the current position for a file
identified by fp
. If you record this result, you can later
use it with fseek
/fseeko
to return the file to this
position. The difference between ftell
and ftello
is that
ftell
returns long
and ftello
returns off_t
.
In the current implementation, ftell
/ftello
simply uses a character
count to represent the file position; this is the same number that
would be recorded by fgetpos
.
ftell
/ftello
return the file position, if possible. If they cannot do
this, they return -1L
. Failure occurs on streams that do not support
positioning; the global errno
indicates this condition with the
value ESPIPE
.
ftell
is required by the ANSI C standard, but the meaning of its
result (when successful) is not specified beyond requiring that it be
acceptable as an argument to fseek
. In particular, other
conforming C implementations may return a different result from
ftell
than what fgetpos
records.
ftello
is defined by the Single Unix specification.
No supporting OS subroutines are required.
funopen — open a stream with custom callbacks
#include <stdio.h>
FILE *funopen( | const void *cookie, |
int (*readfn) (void *cookie, char *buf, int n), | |
int (*writefn) (void *cookie, const char *buf, int n), | |
fpos_t (*seekfn) (void *cookie, fpos_t off, int whence), | |
int (*closefn) (void *cookie)) ; |
FILE *fropen( | const void *cookie, |
int (*readfn) (void *cookie, char *buf, int n)) ; |
FILE *fwopen( | const void *cookie, |
int (*writefn) (void *cookie, const char *buf, int n)) ; |
funopen
creates a FILE
stream where I/O is performed using
custom callbacks. At least one of readfn
and writefn
must be
provided, which determines whether the stream behaves with mode <"r">,
<"w">, or <"r+">.
readfn
should return -1 on failure, or else the number of bytes
read (0 on EOF). It is similar to read
, except that <int> rather
than <size_t> bounds a transaction size, and cookie
will be passed
as the first argument. A NULL readfn
makes attempts to read the
stream fail.
writefn
should return -1 on failure, or else the number of bytes
written. It is similar to write
, except that <int> rather than
<size_t> bounds a transaction size, and cookie
will be passed as
the first argument. A NULL writefn
makes attempts to write the
stream fail.
seekfn
should return (fpos_t)-1 on failure, or else the current
file position. It is similar to lseek
, except that cookie
will be passed as the first argument. A NULL seekfn
makes the
stream behave similarly to a pipe in relation to stdio functions that
require positioning. This implementation assumes fpos_t and off_t are
the same type.
closefn
should return -1 on failure, or 0 on success. It is
similar to close
, except that cookie
will be passed as the
first argument. A NULL closefn
merely flushes all data then lets
fclose
succeed. A failed close will still invalidate the stream.
Read and write I/O functions are allowed to change the underlying
buffer on fully buffered or line buffered streams by calling
setvbuf
. They are also not required to completely fill or empty
the buffer. They are not, however, allowed to change streams from
unbuffered to buffered or to change the state of the line buffering
flag. They must also be prepared to have read or write calls occur on
buffers other than the one most recently specified.
The functions fropen
and fwopen
are convenience macros around
funopen
that only use the specified callback.
fwide — set and determine the orientation of a FILE stream
#include <wchar.h>
int fwide( | FILE *fp, |
int mode) ; |
int _fwide_r( | struct _reent *ptr, |
FILE *fp, | |
int mode) ; |
When mode
is zero, the fwide
function determines the current
orientation of fp
. It returns a value > 0 if fp
is
wide-character oriented, i.e. if wide character I/O is permitted but
char I/O is disallowed. It returns a value < 0 if fp
is byte
oriented, i.e. if char I/O is permitted but wide character I/O is
disallowed. It returns zero if fp
has no orientation yet; in
this case the next I/O operation might change the orientation (to byte
oriented if it is a char I/O operation, or to wide-character oriented
if it is a wide character I/O operation).
Once a stream has an orientation, it cannot be changed and persists until the stream is closed, unless the stream is re-opened with freopen, which removes the orientation of the stream.
When mode
is non-zero, the fwide
function first attempts to set
fp
's orientation (to wide-character oriented if mode
> 0, or to
byte oriented if mode
< 0). It then returns a value denoting the
current orientation, as above.
fwrite — write array elements
#include <stdio.h>
size_t fwrite( | const void *restrict buf, |
size_t size, | |
size_t count, | |
FILE *restrict fp) ; |
#define _BSD_SOURCE
#include <stdio.h>
size_t fwrite_unlocked( | const void *restrict buf, |
size_t size, | |
size_t count, | |
FILE *restrict fp) ; |
#include <stdio.h>
size_t _fwrite_r( | struct _reent *ptr, |
const void *restrict buf, | |
size_t size, | |
size_t count, | |
FILE *restrict fp) ; |
#include <stdio.h>
size_t _fwrite_unlocked_r( | struct _reent *ptr, |
const void *restrict buf, | |
size_t size, | |
size_t count, | |
FILE *restrict fp) ; |
fwrite
attempts to copy, starting from the memory location
buf
, count
elements (each of size size
) into the file or
stream identified by fp
. fwrite
may copy fewer elements than
count
if an error intervenes.
fwrite
also advances the file position indicator (if any) for
fp
by the number of characters actually written.
fwrite_unlocked
is a non-thread-safe version of fwrite
.
fwrite_unlocked
may only safely be used within a scope
protected by flockfile() (or ftrylockfile()) and funlockfile(). This
function may safely be used in a multi-threaded program if and only
if they are called while the invoking thread owns the (FILE *)
object, as is the case after a successful call to the flockfile() or
ftrylockfile() functions. If threads are disabled, then
fwrite_unlocked
is equivalent to fwrite
.
_fwrite_r
and _fwrite_unlocked_r
are simply reentrant versions of the
above that take an additional reentrant structure argument: ptr
.
getc — read a character (macro)
#include <stdio.h>
int getc( | FILE *fp) ; |
#include <stdio.h>
int _getc_r( | struct _reent *ptr, |
FILE *fp) ; |
getc
is a macro, defined in stdio.h
. You can use getc
to get the next single character from the file or stream
identified by fp
. As a side effect, getc
advances the file's
current position indicator.
For a subroutine version of this macro, see fgetc
.
The _getc_r
function is simply the reentrant version of getc
which passes an additional reentrancy structure pointer argument: ptr
.
The next character (read as an unsigned char
, and cast to
int
), unless there is no more data, or the host system reports a
read error; in either of these situations, getc
returns EOF
.
You can distinguish the two situations that cause an EOF
result by
using the ferror
and feof
functions.
ANSI C requires getc
; it suggests, but does not require, that
getc
be implemented as a macro. The standard explicitly permits
macro implementations of getc
to use the argument more than once;
therefore, in a portable program, you should not use an expression
with side effects as the getc
argument.
Supporting OS subroutines required: close
, fstat
, isatty
,
lseek
, read
, sbrk
, write
.
getc_unlocked — non-thread-safe version of getc (macro)
#include <stdio.h>
int getc_unlocked( | FILE *fp) ; |
#include <stdio.h>
int _getc_unlocked_r( | FILE *fp) ; |
getc_unlocked
is a non-thread-safe version of getc
declared in
stdio.h
. getc_unlocked
may only safely be used within a scope
protected by flockfile() (or ftrylockfile()) and funlockfile(). These
functions may safely be used in a multi-threaded program if and only
if they are called while the invoking thread owns the ( FILE *)
object, as is the case after a successful call to the flockfile() or
ftrylockfile() functions. If threads are disabled, then
getc_unlocked
is equivalent to getc
.
The _getc_unlocked_r
function is simply the reentrant version of
get_unlocked
which passes an additional reentrancy structure pointer
argument: ptr
.
getchar — read a character (macro)
#include <stdio.h>
int getchar( | void) ; |
int _getchar_r( | struct _reent *reent) ; |
getchar
is a macro, defined in stdio.h
. You can use getchar
to get the next single character from the standard input stream.
As a side effect, getchar
advances the standard input's
current position indicator.
The alternate function _getchar_r
is a reentrant version. The
extra argument reent
is a pointer to a reentrancy structure.
The next character (read as an unsigned char
, and cast to
int
), unless there is no more data, or the host system reports a
read error; in either of these situations, getchar
returns EOF
.
You can distinguish the two situations that cause an EOF
result by
using `ferror(stdin)
' and `feof(stdin)
'.
getchar_unlocked — non-thread-safe version of getchar (macro)
#include <stdio.h>
int getchar_unlocked( | void) ; |
#include <stdio.h>
int _getchar_unlocked_r( | struct _reent *ptr) ; |
getchar_unlocked
is a non-thread-safe version of getchar
declared in stdio.h
. getchar_unlocked
may only safely be used
within a scope protected by flockfile() (or ftrylockfile()) and
funlockfile(). These functions may safely be used in a multi-threaded
program if and only if they are called while the invoking thread owns
the ( FILE *) object, as is the case after a successful call to the
flockfile() or ftrylockfile() functions. If threads are disabled,
then getchar_unlocked
is equivalent to getchar
.
The _getchar_unlocked_r
function is simply the reentrant version of
getchar_unlocked
which passes an addtional reentrancy structure pointer
argument: ptr
.
getdelim — read a line up to a specified line delimiter
#include <stdio.h>
int getdelim( | char **bufptr, |
size_t *n, | |
int delim, | |
FILE *fp) ; |
getdelim
reads a file fp
up to and possibly including a specified
delimiter delim
. The line is read into a buffer pointed to
by bufptr
and designated with size *n
. If the buffer is
not large enough, it will be dynamically grown by getdelim
.
As the buffer is grown, the pointer to the size n
will be
updated.
getline — read a line from a file
#include <stdio.h>
ssize_t getline( | char **bufptr, |
size_t *n, | |
FILE *fp) ; |
getline
reads a file fp
up to and possibly including the
newline character. The line is read into a buffer pointed to
by bufptr
and designated with size *n
. If the buffer is
not large enough, it will be dynamically grown by getdelim
.
As the buffer is grown, the pointer to the size n
will be
updated.
getline
is equivalent to getdelim(bufptr, n, '\n', fp);
gets — get character string (obsolete, use fgets
instead)
#include <stdio.h>
char *gets( | char *buf) ; |
char *_gets_r( | struct _reent *reent, |
char *buf) ; |
Reads characters from standard input until a newline is found.
The characters up to the newline are stored in buf
. The
newline is discarded, and the buffer is terminated with a 0.
This is a dangerous function, as it has no way of checking
the amount of space available in buf
. One of the attacks
used by the Internet Worm of 1988 used this to overrun a
buffer allocated on the stack of the finger daemon and
overwrite the return address, causing the daemon to execute
code downloaded into it over the connection.
The alternate function _gets_r
is a reentrant version. The extra
argument reent
is a pointer to a reentrancy structure.
gets
returns the buffer passed to it, with the data filled
in. If end of file occurs with some data already accumulated,
the data is returned with no other indication. If end of file
occurs with no data in the buffer, NULL is returned.
Supporting OS subroutines required: close
, fstat
, isatty
,
lseek
, read
, sbrk
, write
.
getw — read a word (int)
#include <stdio.h>
int getw( | FILE *fp) ; |
getw
is a function, defined in stdio.h
. You can use getw
to get the next word from the file or stream identified by fp
. As
a side effect, getw
advances the file's current position
indicator.
getwchar — read a wide character from standard input
#include <wchar.h>
wint_t getwchar( | void) ; |
#define _GNU_SOURCE
#include <wchar.h>
wint_t getwchar_unlocked( | void) ; |
#include <wchar.h>
wint_t _getwchar_r( | struct _reent *reent) ; |
#include <wchar.h>
wint_t _getwchar_unlocked_r( | struct _reent *reent) ; |
getwchar
function or macro is the wide character equivalent of
the getchar
function. You can use getwchar
to get the next
wide character from the standard input stream. As a side effect,
getwchar
advances the standard input's current position indicator.
getwchar_unlocked
is a non-thread-safe version of getwchar
.
getwchar_unlocked
may only safely be used within a scope
protected by flockfile() (or ftrylockfile()) and funlockfile(). This
function may safely be used in a multi-threaded program if and only
if they are called while the invoking thread owns the (FILE *)
object, as is the case after a successful call to the flockfile() or
ftrylockfile() functions. If threads are disabled, then
getwchar_unlocked
is equivalent to getwchar
.
The alternate functions _getwchar_r
and _getwchar_unlocked_r
are
reentrant versions of the above. The extra argument reent
is a pointer to
a reentrancy structure.
mktemp — generate unused file name, generate unused directory
#include <stdlib.h>
char *mktemp( | char *path) ; |
char *mkdtemp( | char *path) ; |
int mkstemp( | char *path) ; |
int mkstemps( | char *path, |
int suffixlen) ; |
int mkostemp( | char *path, |
int flags) ; |
int mkostemps( | char *path, |
int suffixlen, | |
int flags) ; |
char *_mktemp_r( | struct _reent *reent, |
char *path) ; |
char *_mkdtemp_r( | struct _reent *reent, |
char *path) ; |
int *_mkstemp_r( | struct _reent *reent, |
char *path) ; |
int *_mkstemps_r( | struct _reent *reent, |
char *path, | |
int len) ; |
int *_mkostemp_r( | struct _reent *reent, |
char *path, | |
int flags) ; |
int *_mkostemps_r( | struct _reent *reent, |
char *path, | |
int len, | |
int flags) ; |
mktemp
, mkstemp
, and mkstemps
attempt to generate a file name
that is not yet in use for any existing file. mkstemp
and mkstemps
create the file and open it for reading and writing; mktemp
simply
generates the file name (making mktemp
a security risk). mkostemp
and mkostemps
allow the addition of other open
flags, such
as O_CLOEXEC
, O_APPEND
, or O_SYNC
. On platforms with a
separate text mode, mkstemp
forces O_BINARY
, while mkostemp
allows the choice between O_BINARY
, O_TEXT
, or 0 for default.
mkdtemp
attempts to create a directory instead of a file, with a
permissions mask of 0700.
You supply a simple pattern for the generated file name, as the string
at path
. The pattern should be a valid filename (including path
information if you wish) ending with at least six `X
'
characters. The generated filename will match the leading part of the
name you supply, with the trailing `X
' characters replaced by some
combination of digits and letters. With mkstemps
, the `X
'
characters end suffixlen
bytes before the end of the string.
The alternate functions _mktemp_r
, _mkdtemp_r
, _mkstemp_r
,
_mkostemp_r
, _mkostemps_r
, and _mkstemps_r
are reentrant
versions. The extra argument reent
is a pointer to a reentrancy
structure.
mktemp
returns the pointer path
to the modified string
representing an unused filename, unless it could not generate one, or
the pattern you provided is not suitable for a filename; in that case,
it returns NULL
. Be aware that there is an inherent race between
generating the name and attempting to create a file by that name;
you are advised to use O_EXCL|O_CREAT
.
mkdtemp
returns the pointer path
to the modified string if the
directory was created, otherwise it returns NULL
.
mkstemp
, mkstemps
, mkostemp
, and mkostemps
return a file
descriptor to the newly created file, unless it could not generate an
unused filename, or the pattern you provided is not suitable for a
filename; in that case, it returns -1
.
Never use mktemp
. The generated filenames are easy to guess and
there's a race between the test if the file exists and the creation
of the file. In combination this makes mktemp
prone to attacks
and using it is a security risk. Whenever possible use mkstemp
instead. It doesn't suffer the race condition.
ANSI C does not require either mktemp
or mkstemp
; the System
V Interface Definition requires mktemp
as of Issue 2. POSIX 2001
requires mkstemp
, and POSIX 2008 requires mkdtemp
while
deprecating mktemp
. mkstemps
, mkostemp
, and mkostemps
are not standardized.
Supporting OS subroutines required: getpid
, mkdir
, open
, stat
.
open_memstream — open a write stream around an arbitrary-length string
#include <stdio.h>
FILE *open_memstream( | char **restrict buf, |
size_t *restrict size) ; |
#include <wchar.h>
FILE *open_wmemstream( | wchar_t **restrict buf, |
size_t *restrict size) ; |
open_memstream
creates a seekable, byte-oriented FILE
stream that
wraps an arbitrary-length buffer, created as if by malloc
. The current
contents of *buf
are ignored; this implementation uses *size
as a hint of the maximum size expected, but does not fail if the hint
was wrong. The parameters buf
and size
are later stored
through following any call to fflush
or fclose
, set to the
current address and usable size of the allocated string; although
after fflush, the pointer is only valid until another stream operation
that results in a write. Behavior is undefined if the user alters
either *buf
or *size
prior to fclose
.
open_wmemstream
is like open_memstream
just with the associated
stream being wide-oriented. The size set in size
in subsequent
operations is the number of wide characters.
The stream is write-only, since the user can directly read *buf
after a flush; see fmemopen
for a way to wrap a string with a
readable stream. The user is responsible for calling free
on
the final *buf
after fclose
.
Any time the stream is flushed, a NUL byte is written at the current
position (but is not counted in the buffer length), so that the string
is always NUL-terminated after at most *size
bytes (or wide characters
in case of open_wmemstream
). However, data previously written beyond
the current stream offset is not lost, and the NUL value written during a
flush is restored to its previous value when seeking elsewhere in the string.
perror — print an error message on standard error
#include <stdio.h>
void perror( | char *prefix) ; |
void _perror_r( | struct _reent *reent, |
char *prefix) ; |
Use perror
to print (on standard error) an error message
corresponding to the current value of the global variable errno
.
Unless you use NULL
as the value of the argument prefix
, the
error message will begin with the string at prefix
, followed by a
colon and a space (:
). The remainder of the error message is one
of the strings described for strerror
.
The alternate function _perror_r
is a reentrant version. The
extra argument reent
is a pointer to a reentrancy structure.
putc — write a character (macro)
#include <stdio.h>
int putc( | int ch, |
FILE *fp) ; |
#include <stdio.h>
int _putc_r( | struct _reent *ptr, |
int ch, | |
FILE *fp) ; |
putc
is a macro, defined in stdio.h
. putc
writes the argument ch
to the file or stream identified by
fp
, after converting it from an int
to an unsigned char
.
If the file was opened with append mode (or if the stream cannot support positioning), then the new character goes at the end of the file or stream. Otherwise, the new character is written at the current value of the position indicator, and the position indicator advances by one.
For a subroutine version of this macro, see fputc
.
The _putc_r
function is simply the reentrant version of
putc
that takes an additional reentrant structure argument: ptr
.
If successful, putc
returns its argument ch
. If an error
intervenes, the result is EOF
. You can use `ferror(
' to
query for errors.
fp
)
ANSI C requires putc
; it suggests, but does not require, that
putc
be implemented as a macro. The standard explicitly permits
macro implementations of putc
to use the fp
argument more than once;
therefore, in a portable program, you should not use an expression
with side effects as this argument.
Supporting OS subroutines required: close
, fstat
, isatty
,
lseek
, read
, sbrk
, write
.
putc_unlocked — non-thread-safe version of putc (macro)
#include <stdio.h>
int putc_unlocked( | int ch, |
FILE *fp) ; |
#include <stdio.h>
int _putc_unlocked_r( | struct _reent *ptr, |
int ch, | |
FILE *fp) ; |
putc_unlocked
is a non-thread-safe version of putc
declared in
stdio.h
. putc_unlocked
may only safely be used within a scope
protected by flockfile() (or ftrylockfile()) and funlockfile(). These
functions may safely be used in a multi-threaded program if and only
if they are called while the invoking thread owns the ( FILE *)
object, as is the case after a successful call to the flockfile() or
ftrylockfile() functions. If threads are disabled, then
putc_unlocked
is equivalent to putc
.
The function _putc_unlocked_r
is simply the reentrant version of
putc_unlocked
that takes an additional reentrant structure pointer
argument: ptr
.
putchar — write a character (macro)
#include <stdio.h>
int putchar( | int ch) ; |
int _putchar_r( | struct _reent *reent, |
int ch) ; |
putchar
is a macro, defined in stdio.h
. putchar
writes its argument to the standard output stream,
after converting it from an int
to an unsigned char
.
The alternate function _putchar_r
is a reentrant version. The
extra argument reent
is a pointer to a reentrancy structure.
putchar_unlocked — non-thread-safe version of putchar (macro)
#include <stdio.h>
int putchar_unlocked( | int ch) ; |
putchar_unlocked
is a non-thread-safe version of putchar
declared in stdio.h
. putchar_unlocked
may only safely be used
within a scope protected by flockfile() (or ftrylockfile()) and
funlockfile(). These functions may safely be used in a multi-threaded
program if and only if they are called while the invoking thread owns
the ( FILE *) object, as is the case after a successful call to the
flockfile() or ftrylockfile() functions. If threads are disabled,
then putchar_unlocked
is equivalent to putchar
.
puts — write a character string
#include <stdio.h>
int puts( | const char *s) ; |
int _puts_r( | struct _reent *reent, |
const char *s) ; |
putw — write a word (int)
#include <stdio.h>
int putw( | int w, |
FILE *fp) ; |
putwchar — write a wide character to standard output
#include <wchar.h>
wint_t putwchar( | wchar_t wc) ; |
#include <wchar.h>
wint_t putwchar_unlocked( | wchar_t wc) ; |
#include <wchar.h>
wint_t _putwchar_r( | struct _reent *reent, |
wchar_t wc) ; |
#include <wchar.h>
wint_t _putwchar_unlocked_r( | struct _reent *reent, |
wchar_t wc) ; |
The putwchar
function or macro is the wide-character equivalent of
the putchar
function. It writes the wide character wc to stdout.
putwchar_unlocked
is a non-thread-safe version of putwchar
.
putwchar_unlocked
may only safely be used within a scope
protected by flockfile() (or ftrylockfile()) and funlockfile(). This
function may safely be used in a multi-threaded program if and only
if they are called while the invoking thread owns the (FILE *)
object, as is the case after a successful call to the flockfile() or
ftrylockfile() functions. If threads are disabled, then
putwchar_unlocked
is equivalent to putwchar
.
The alternate functions _putwchar_r
and _putwchar_unlocked_r
are
reentrant versions of the above. The extra argument reent
is a pointer
to a reentrancy structure.
remove — delete a file's name
#include <stdio.h>
int remove( | char *filename) ; |
int _remove_r( | struct _reent *reent, |
char *filename) ; |
Use remove
to dissolve the association between a particular
filename (the string at filename
) and the file it represents.
After calling remove
with a particular filename, you will no
longer be able to open the file by that name.
In this implementation, you may use remove
on an open file without
error; existing file descriptors for the file will continue to access
the file's data until the program using them closes the file.
The alternate function _remove_r
is a reentrant version. The
extra argument reent
is a pointer to a reentrancy structure.
rename — rename a file
#include <stdio.h>
int rename( | const char *old, |
const char *new) ; |
Use rename
to establish a new name (the string at new
) for a
file now known by the string at old
. After a successful
rename
, the file is no longer accessible by the string at old
.
If rename
fails, the file named *
is unaffected. The
conditions for failure depend on the host operating system.
old
rewind — reinitialize a file or stream
#include <stdio.h>
void rewind( | FILE *fp) ; |
void _rewind_r( | struct _reent *ptr, |
FILE *fp) ; |
setbuf — specify full buffering for a file or stream
#include <stdio.h>
void setbuf( | FILE *fp, |
char *buf) ; |
setbuf
specifies that output to the file or stream identified by fp
should be fully buffered. All output for this file will go to a
buffer (of size BUFSIZ
, specified in `stdio.h
'). Output will
be passed on to the host system only when the buffer is full, or when
an input operation intervenes.
You may, if you wish, supply your own buffer by passing a pointer to
it as the argument buf
. It must have size BUFSIZ
. You can
also use NULL
as the value of buf
, to signal that the
setbuf
function is to allocate the buffer.
You may only use setbuf
before performing any file operation other
than opening the file.
If you supply a non-null buf
, you must ensure that the associated
storage continues to be available until you close the stream
identified by fp
.
Both ANSI C and the System V Interface Definition (Issue 2) require
setbuf
. However, they differ on the meaning of a NULL
buffer
pointer: the SVID issue 2 specification says that a NULL
buffer
pointer requests unbuffered output. For maximum portability, avoid
NULL
buffer pointers.
Supporting OS subroutines required: close
, fstat
, isatty
,
lseek
, read
, sbrk
, write
.
setbuffer — specify full buffering for a file or stream with size
#include <stdio.h>
void setbuffer( | FILE *fp, |
char *buf, | |
int size) ; |
setbuffer
specifies that output to the file or stream identified by
fp
should be fully buffered. All output for this file will go to a
buffer (of size size
). Output will be passed on to the host system
only when the buffer is full, or when an input operation intervenes.
You may, if you wish, supply your own buffer by passing a pointer to
it as the argument buf
. It must have size size
. You can
also use NULL
as the value of buf
, to signal that the
setbuffer
function is to allocate the buffer.
setlinebuf — specify line buffering for a file or stream
#include <stdio.h>
void setlinebuf( | FILE *fp) ; |
setlinebuf
specifies that output to the file or stream identified by
fp
should be line buffered. This causes the file or stream to pass
on output to the host system at every newline, as well as when the
buffer is full, or when an input operation intervenes.
setvbuf — specify file or stream buffering
#include <stdio.h>
int setvbuf( | FILE *fp, |
char *buf, | |
int mode, | |
size_t size) ; |
Use setvbuf
to specify what kind of buffering you want for the
file or stream identified by fp
, by using one of the following
values (from stdio.h
) as the mode
argument:
_IONBF
|
Do not use a buffer: send output directly to the host system for the
file or stream identified by |
_IOFBF
| Use full output buffering: output will be passed on to the host system only when the buffer is full, or when an input operation intervenes. |
_IOLBF
| Use line buffering: pass on output to the host system at every newline, as well as when the buffer is full, or when an input operation intervenes. |
Use the size
argument to specify how large a buffer you wish. You
can supply the buffer itself, if you wish, by passing a pointer to a
suitable area of memory as buf
. Otherwise, you may pass NULL
as the buf
argument, and setvbuf
will allocate the buffer.
You may only use setvbuf
before performing any file operation other
than opening the file.
If you supply a non-null buf
, you must ensure that the associated
storage continues to be available until you close the stream
identified by fp
.
Both ANSI C and the System V Interface Definition (Issue 2) require
setvbuf
. However, they differ on the meaning of a NULL
buffer
pointer: the SVID issue 2 specification says that a NULL
buffer
pointer requests unbuffered output. For maximum portability, avoid
NULL
buffer pointers.
Both specifications describe the result on failure only as a nonzero value.
Supporting OS subroutines required: close
, fstat
, isatty
,
lseek
, read
, sbrk
, write
.
siprintf — format output (integer only)
#include <stdio.h>
int iprintf( | const char *format, | |
...) ; |
int fiprintf( | FILE *fd, | |
const char *format, | ||
...) ; |
int siprintf( | char *str, | |
const char *format, | ||
...) ; |
int sniprintf( | char *str, | |
size_t size, | ||
const char *format, | ||
...) ; |
int asiprintf( | char **strp, | |
const char *format, | ||
...) ; |
char *asniprintf( | char *str, | |
size_t *size, | ||
const char *format, | ||
...) ; |
int _iprintf_r( | struct _reent *ptr, | |
const char *format, | ||
...) ; |
int _fiprintf_r( | struct _reent *ptr, | |
FILE *fd, | ||
const char *format, | ||
...) ; |
int _siprintf_r( | struct _reent *ptr, | |
char *str, | ||
const char *format, | ||
...) ; |
int _sniprintf_r( | struct _reent *ptr, | |
char *str, | ||
size_t size, | ||
const char *format, | ||
...) ; |
int _asiprintf_r( | struct _reent *ptr, | |
char **strp, | ||
const char *format, | ||
...) ; |
char *_asniprintf_r( | struct _reent *ptr, | |
char *str, | ||
size_t *size, | ||
const char *format, | ||
...) ; |
iprintf
, fiprintf
, siprintf
, sniprintf
,
asiprintf
, and asniprintf
are the same as printf
,
fprintf
, sprintf
, snprintf
, asprintf
, and
asnprintf
, respectively, except that they restrict usage
to non-floating-point format specifiers.
_iprintf_r
, _fiprintf_r
, _asiprintf_r
,
_siprintf_r
, _sniprintf_r
, _asniprintf_r
are
simply reentrant versions of the functions above.
siscanf — scan and format non-floating input
#include <stdio.h>
int iscanf( | const char *format, | |
...) ; |
int fiscanf( | FILE *fd, | |
const char *format, | ||
...) ; |
int siscanf( | const char *str, | |
const char *format, | ||
...) ; |
int _iscanf_r( | struct _reent *ptr, | |
const char *format, | ||
...) ; |
int _fiscanf_r( | struct _reent *ptr, | |
FILE *fd, | ||
const char *format, | ||
...) ; |
int _siscanf_r( | struct _reent *ptr, | |
const char *str, | ||
const char *format, | ||
...) ; |
iscanf
, fiscanf
, and siscanf
are the same as
scanf
, fscanf
, and sscanf
respectively, only that
they restrict the available formats to non-floating-point
format specifiers.
The routines _iscanf_r
, _fiscanf_r
, and _siscanf_r
are reentrant
versions of iscanf
, fiscanf
, and siscanf
that take an additional
first argument pointing to a reentrancy structure.
sprintf — format output
#include <stdio.h>
int printf( | const char *restrict format, | |
...) ; |
int fprintf( | FILE *restrict fd, | |
const char *restrict format, | ||
...) ; |
int sprintf( | char *restrict str, | |
const char *restrict format, | ||
...) ; |
int snprintf( | char *restrict str, | |
size_t size, | ||
const char *restrict format, | ||
...) ; |
int asprintf( | char **restrict strp, | |
const char *restrict format, | ||
...) ; |
char *asnprintf( | char *restrict str, | |
size_t *restrict size, | ||
const char *restrict format, | ||
...) ; |
int _printf_r( | struct _reent *ptr, | |
const char *restrict format, | ||
...) ; |
int _fprintf_r( | struct _reent *ptr, | |
FILE *restrict fd, | ||
const char *restrict format, | ||
...) ; |
int _sprintf_r( | struct _reent *ptr, | |
char *restrict str, | ||
const char *restrict format, | ||
...) ; |
int _snprintf_r( | struct _reent *ptr, | |
char *restrict str, | ||
size_t size, | ||
const char *restrict format, | ||
...) ; |
int _asprintf_r( | struct _reent *ptr, | |
char **restrict strp, | ||
const char *restrict format, | ||
...) ; |
char *_asnprintf_r( | struct _reent *ptr, | |
char *restrict str, | ||
size_t *restrict size, | ||
const char *restrict format, | ||
...) ; |
printf
accepts a series of arguments, applies to each a
format specifier from *
, and writes the
formatted data to format
stdout
, without a terminating NUL
character. The behavior of printf
is undefined if there
are not enough arguments for the format. printf
returns
when it reaches the end of the format string. If there are
more arguments than the format requires, excess arguments are
ignored.
fprintf
is like printf
, except that output is directed
to the stream fd
rather than stdout
.
sprintf
is like printf
, except that output is directed
to the buffer str
, and a terminating NUL is output.
Behavior is undefined if more output is generated than the
buffer can hold.
snprintf
is like sprintf
, except that output is
limited to at most size
bytes, including the terminating
NUL
. As a special case, if size
is 0, str
can be
NULL, and snprintf
merely calculates how many bytes would
be printed.
asprintf
is like sprintf
, except that the output is
stored in a dynamically allocated buffer, pstr
, which
should be freed later with free
.
asnprintf
is like sprintf
, except that the return type
is either the original str
if it was large enough, or a
dynamically allocated string if the output exceeds *size
;
the length of the result is returned in *size
. When
dynamic allocation occurs, the contents of the original
str
may have been modified.
For sprintf
, snprintf
, and asnprintf
, the behavior
is undefined if the output *
overlaps with one of
the arguments. Behavior is also undefined if the argument for
str
%n
within *
overlaps another argument.
format
format
is a pointer to a character string containing two
types of objects: ordinary characters (other than %
),
which are copied unchanged to the output, and conversion
specifications, each of which is introduced by %
. (To
include %
in the output, use %%
in the format string.)
A conversion specification has the following form:
%[pos
][flags
][width
][.prec
][size
]type
The fields of the conversion specification have the following meanings:
pos
Conversions normally consume arguments in the order that they
are presented. However, it is possible to consume arguments
out of order, and reuse an argument for more than one
conversion specification (although the behavior is undefined
if the same argument is requested with different types), by
specifying pos
, which is a decimal integer followed by
'$'. The integer must be between 1 and <NL_ARGMAX> from
limits.h, and if argument %n$
is requested, all earlier
arguments must be requested somewhere within format
. If
positional parameters are used, then all conversion
specifications except for %%
must specify a position.
This positional parameters method is a POSIX extension to the C
standard definition for the functions.
flags
flags
is an optional sequence of characters which control
output justification, numeric signs, decimal points, trailing
zeros, and octal and hex prefixes. The flag characters are
minus (-
), plus (+
), space ( ), zero (0
), sharp
(#
), and quote ('
). They can appear in any
combination, although not all flags can be used for all
conversion specification types.
'
|
A POSIX extension to the C standard. However, this
implementation presently treats it as a no-op, which
is the default behavior for the C locale, anyway. (If
it did what it is supposed to, when |
-
| The result of the conversion is left justified, and the right is padded with blanks. If you do not use this flag, the result is right justified, and padded on the left. |
+
|
The result of a signed conversion (as
determined by |
" " (space)
|
If the first character of a signed conversion
specification is not a sign, or if a signed
conversion results in no characters, the
result will begin with a space. If the space
( ) flag and the plus ( |
0
|
If the
Note that |
#
|
The result is to be converted to an
alternative form, according to the |
The alternative form output with the # flag depends on the type
character:
o
| Increases precision to force the first digit of the result to be a zero. |
x
|
A non-zero result will have a |
X
|
A non-zero result will have a |
a, A, e, E, f, or F
| The result will always contain a decimal point even if no digits follow the point. (Normally, a decimal point appears only if a digit follows it.) Trailing zeros are removed. |
g or G
| The result will always contain a decimal point even if no digits follow the point. Trailing zeros are not removed. |
all others
| Undefined. |
width
width
is an optional minimum field width. You can
either specify it directly as a decimal integer, or
indirectly by using instead an asterisk (*
), in
which case an int
argument is used as the field
width. If positional arguments are used, then the
width must also be specified positionally as *m$
,
with m as a decimal integer. Negative field widths
are treated as specifying the minus (-
) flag for
left justfication, along with a positive field width.
The resulting format may be wider than the specified
width.
prec
prec
is an optional field; if present, it is
introduced with `.
' (a period). You can specify
the precision either directly as a decimal integer or
indirectly by using an asterisk (*
), in which case
an int
argument is used as the precision. If
positional arguments are used, then the precision must
also be specified positionally as *m$
, with m as a
decimal integer. Supplying a negative precision is
equivalent to omitting the precision. If only a
period is specified the precision is zero. The effect
depends on the conversion type
.
d, i, o, u, x, or X
| Minimum number of digits to appear. If no precision is given, defaults to 1. |
a or A
| Number of digits to appear after the decimal point. If no precision is given, the precision defaults to the minimum needed for an exact representation. |
e, E, f or F
| Number of digits to appear after the decimal point. If no precision is given, the precision defaults to 6. |
g or G
| Maximum number of significant digits. A precision of 0 is treated the same as a precision of 1. If no precision is given, the precision defaults to 6. |
s or S
| Maximum number of characters to print from the string. If no precision is given, the entire string is printed. |
all others
| undefined. |
size
size
is an optional modifier that changes the data
type that the corresponding argument has. Behavior is
unspecified if a size is given that does not match the
type
.
hh
|
With
With |
h
|
With
With |
l
|
With
With
With
With
With |
ll
|
With
With |
j
|
With
With |
z
|
With
With |
t
|
With
With |
L
|
With |
type
type
specifies what kind of conversion printf
performs. Here is a table of these:
%
|
Prints the percent character ( |
c
|
Prints |
C
|
Short for |
s
|
Prints the elements of a pointer to |
S
|
Short for |
d or i
|
Prints a signed decimal integer; takes an
|
D
|
Newlib extension, short for |
o
|
Prints an unsigned octal integer; takes an
|
O
|
Newlib extension, short for |
u
|
Prints an unsigned decimal integer; takes an
|
U
|
Newlib extension, short for |
x
|
Prints an unsigned hexadecimal integer (using
|
X
|
Like |
f
|
Prints a signed value of the form
If the value is infinite, the result is
|
F
|
Like |
e
|
Prints a signed value of the form
|
E
|
Like |
g
|
Prints a signed value in either |
G
|
Like |
a
|
Prints a signed value of the form
|
A
|
Like |
n
|
Takes a pointer to |
p
|
Takes a pointer to |
m
|
Prints the output of |
_printf_r
, _fprintf_r
, _asprintf_r
,
_sprintf_r
, _snprintf_r
, _asnprintf_r
are simply
reentrant versions of the functions above.
On success, sprintf
and asprintf
return the number of bytes in
the output string, except the concluding NUL
is not counted.
snprintf
returns the number of bytes that would be in the output
string, except the concluding NUL
is not counted. printf
and
fprintf
return the number of characters transmitted.
asnprintf
returns the original str
if there was enough room,
otherwise it returns an allocated string.
If an error occurs, the result of printf
, fprintf
,
snprintf
, and asprintf
is a negative value, and the result of
asnprintf
is NULL. No error returns occur for sprintf
. For
printf
and fprintf
, errno
may be set according to
fputc
. For asprintf
and asnprintf
, errno
may be set
to ENOMEM if allocation fails, and for snprintf
, errno
may be
set to EOVERFLOW if size
or the output length exceeds INT_MAX.
ANSI C requires printf
, fprintf
, sprintf
, and
snprintf
. asprintf
and asnprintf
are newlib extensions.
The ANSI C standard specifies that implementations must support at least formatted output of up to 509 characters. This implementation has no inherent limit.
Depending on how newlib was configured, not all format specifiers are supported.
Supporting OS subroutines required: close
, fstat
, isatty
,
lseek
, read
, sbrk
, write
.
sscanf — scan and format input
#include <stdio.h>
int scanf( | const char *restrict format, | |
...) ; |
int fscanf( | FILE *restrict fd, | |
const char *restrict format, | ||
...) ; |
int sscanf( | const char *restrict str, | |
const char *restrict format, | ||
...) ; |
int _scanf_r( | struct _reent *ptr, | |
const char *restrict format, | ||
...) ; |
int _fscanf_r( | struct _reent *ptr, | |
FILE *restrict fd, | ||
const char *restrict format, | ||
...) ; |
int _sscanf_r( | struct _reent *ptr, | |
const char *restrict str, | ||
const char *restrict format, | ||
...) ; |
scanf
scans a series of input fields from standard input,
one character at a time. Each field is interpreted according to
a format specifier passed to scanf
in the format string at
*
. format
scanf
stores the interpreted input from
each field at the address passed to it as the corresponding argument
following format
. You must supply the same number of
format specifiers and address arguments as there are input fields.
There must be sufficient address arguments for the given format specifiers; if not the results are unpredictable and likely disasterous. Excess address arguments are merely ignored.
scanf
often produces unexpected results if the input diverges from
an expected pattern. Since the combination of gets
or fgets
followed by sscanf
is safe and easy, that is the preferred way
to be certain that a program is synchronized with input at the end
of a line.
fscanf
and sscanf
are identical to scanf
, other than the
source of input: fscanf
reads from a file, and sscanf
from a string.
The routines _scanf_r
, _fscanf_r
, and _sscanf_r
are reentrant
versions of scanf
, fscanf
, and sscanf
that take an additional
first argument pointing to a reentrancy structure.
The string at *
is a character sequence composed
of zero or more directives. Directives are composed of
one or more whitespace characters, non-whitespace characters,
and format specifications.
format
Whitespace characters are blank (), tab (
\t
), or
newline (\n
).
When scanf
encounters a whitespace character in the format string
it will read (but not store) all consecutive whitespace characters
up to the next non-whitespace character in the input.
Non-whitespace characters are all other ASCII characters except the
percent sign (%
). When scanf
encounters a non-whitespace
character in the format string it will read, but not store
a matching non-whitespace character.
Format specifications tell scanf
to read and convert characters
from the input field into specific types of values, and store then
in the locations specified by the address arguments.
Trailing whitespace is left unread unless explicitly matched in the format string.
The format specifiers must begin with a percent sign (%
)
and have the following form:
%[*][width
][size
]type
Each format specification begins with the percent character (%
).
The other fields are:
*
an optional marker; if present, it suppresses interpretation and assignment of this input field.
width
an optional maximum field width: a decimal integer,
which controls the maximum number of characters that
will be read before converting the current input field. If the
input field has fewer than width
characters, scanf
reads all the characters in the field, and then
proceeds with the next field and its format specification.
If a whitespace or a non-convertable character occurs
before width
character are read, the characters up
to that character are read, converted, and stored.
Then scanf
proceeds to the next format specification.
size
h
, j
, l
, L
, t
, and z
are optional size
characters which override the default way that scanf
interprets the data type of the corresponding argument.
Modifier | Type(s) | |
---|---|---|
hh | d, i, o, u, x, n | convert input to char, store in char object |
h | d, i, o, u, x, n | convert input to short, store in short object |
h | D, I, O, U, X, e, f, c, s, p | no effect |
j | d, i, o, u, x, n | convert input to intmax_t, store in intmax_t object |
j | all others | no effect |
l | d, i, o, u, x, n | convert input to long, store in long object |
l | e, f, g | convert input to double, store in a double object |
l | D, I, O, U, X, c, s, p | no effect |
ll | d, i, o, u, x, n | convert to long long, store in long long object |
L | d, i, o, u, x, n | convert to long long, store in long long object |
L | e, f, g, E, G | convert to long double, store in long double object |
L | all others | no effect |
t | d, i, o, u, x, n | convert input to ptrdiff_t, store in ptrdiff_t object |
t | all others | no effect |
z | d, i, o, u, x, n | convert input to size_t, store in size_t object |
z | all others | no effect |
type
A character to specify what kind of conversion
scanf
performs. Here is a table of the conversion
characters:
%
|
No conversion is done; the percent character ( |
c
|
Scans one character. Corresponding |
s
|
Reads a character string into the array supplied.
Corresponding |
[ |
Reads a non-empty character string into memory
starting at |
d
|
Reads a decimal integer into the corresponding |
D
|
Reads a decimal integer into the corresponding
|
o
|
Reads an octal integer into the corresponding |
O
|
Reads an octal integer into the corresponding |
u
|
Reads an unsigned decimal integer into the corresponding
|
U
|
Reads an unsigned decimal integer into the corresponding |
x,X
|
Read a hexadecimal integer into the corresponding |
e, f, g
|
Read a floating-point number into the corresponding |
E, F, G
|
Read a floating-point number into the corresponding |
i
|
Reads a decimal, octal or hexadecimal integer into the
corresponding |
I
|
Reads a decimal, octal or hexadecimal integer into the
corresponding |
n
|
Stores the number of characters read in the corresponding
|
p
|
Stores a scanned pointer. ANSI C leaves the details
to each implementation; this implementation treats
|
A pattern
of characters surrounded by square brackets can be used
instead of the s
type character. pattern
is a set of
characters which define a search set of possible characters making up
the scanf
input field. If the first character in the brackets is a
caret (^
), the search set is inverted to include all ASCII characters
except those between the brackets. There is also a range facility
which you can use as a shortcut. %[0-9]
matches all decimal digits.
The hyphen must not be the first or last character in the set.
The character prior to the hyphen must be lexically less than the
character after it.
Here are some pattern
examples:
%[abcd]
|
matches strings containing only |
%[^abcd]
|
matches strings containing any characters except |
%[A-DW-Z]
|
matches strings containing |
%[z-a]
|
matches the characters |
Floating point numbers (for field types e
, f
, g
, E
,
F
, G
) must correspond to the following general form:
[+/-] ddddd[.]ddd [E|e[+|-]ddd]
where objects inclosed in square brackets are optional, and ddd
represents decimal, octal, or hexadecimal digits.
scanf
returns the number of input fields successfully
scanned, converted and stored; the return value does
not include scanned fields which were not stored.
If scanf
attempts to read at end-of-file, the return
value is EOF
.
If no fields were stored, the return value is 0
.
scanf
might stop scanning a particular field before
reaching the normal field end character, or may
terminate entirely.
scanf
stops scanning and storing the current field
and moves to the next input field (if any)
in any of the following situations:
The assignment suppressing character (*
) appears
after the %
in the format specification; the current
input field is scanned but not stored.
width
characters have been read (width
is a
width specification, a positive decimal integer).
The next character read cannot be converted
under the the current format (for example,
if a Z
is read when the format is decimal).
The next character in the input field does not appear in the search set (or does appear in the inverted search set).
When scanf
stops scanning the current input field for one of
these reasons, the next character is considered unread and
used as the first character of the following input field, or the
first character in a subsequent read operation on the input.
scanf
will terminate under the following circumstances:
The next character in the input field conflicts with a corresponding non-whitespace character in the format string.
The next character in the input field is EOF
.
The format string has been exhausted.
When the format string contains a character sequence that is
not part of a format specification, the same character
sequence must appear in the input; scanf
will
scan but not store the matched characters. If a
conflict occurs, the first conflicting character remains in the input
as if it had never been read.
stdio_ext — access internals of FILE structure
#include <stdio.h>
#include <stdio_ext.h>
size_t __fbufsize( | FILE *fp) ; |
size_t __fpending( | FILE *fp) ; |
int __flbf( | FILE *fp) ; |
int __freadable( | FILE *fp) ; |
int __fwritable( | FILE *fp) ; |
int __freading( | FILE *fp) ; |
int __fwriting( | FILE *fp) ; |
__fbufsize
returns the number of bytes in the buffer of stream fp
.
__fpending
returns the number of bytes in the output buffer of stream fp
.
__flbf
returns nonzero if stream fp
is line-buffered, and 0
if not.
__freadable
returns nonzero if stream fp
may be read, and 0
if not.
__fwritable
returns nonzero if stream fp
may be written, and 0
if not.
__freading
returns nonzero if stream fp
if the last operation on
it was a read, or if it read-only, and 0
if not.
__fwriting
returns nonzero if stream fp
if the last operation on
it was a write, or if it write-only, and 0
if not.
swprintf — wide character format output
#include <wchar.h>
int wprintf( | const wchar_t *format, | |
...) ; |
int fwprintf( | FILE *__restrict fd, | |
const wchar_t *__restrict format, | ||
...) ; |
int swprintf( | wchar_t *__restrict str, | |
size_t size, | ||
const wchar_t *__restrict format, | ||
...) ; |
int _wprintf_r( | struct _reent *ptr, | |
const wchar_t *format, | ||
...) ; |
int _fwprintf_r( | struct _reent *ptr, | |
FILE *fd, | ||
const wchar_t *format, | ||
...) ; |
int _swprintf_r( | struct _reent *ptr, | |
wchar_t *str, | ||
size_t size, | ||
const wchar_t *format, | ||
...) ; |
wprintf
accepts a series of arguments, applies to each a
format specifier from *
, and writes the
formatted data to format
stdout
, without a terminating NUL
wide character. The behavior of wprintf
is undefined if there
are not enough arguments for the format or if any argument is not the
right type for the corresponding conversion specifier. wprintf
returns when it reaches the end of the format string. If there are
more arguments than the format requires, excess arguments are
ignored.
fwprintf
is like wprintf
, except that output is directed
to the stream fd
rather than stdout
.
swprintf
is like wprintf
, except that output is directed
to the buffer str
with a terminating wide NUL
, and the
resulting string length is limited to at most size
wide characters,
including the terminating NUL
. It is considered an error if the
output (including the terminating wide-NULL
) does not fit into
size
wide characters. (This error behavior is not the same as for
snprintf
, which swprintf
is otherwise completely analogous to.
While snprintf
allows the needed size to be known simply by giving
size
=0, swprintf
does not, giving an error instead.)
For swprintf
the behavior is undefined if the output
*
overlaps with one of the arguments. Behavior is also
undefined if the argument for str
%n
within *
overlaps another argument.
format
format
is a pointer to a wide character string containing two
types of objects: ordinary characters (other than %
),
which are copied unchanged to the output, and conversion
specifications, each of which is introduced by %
. (To
include %
in the output, use %%
in the format string.)
A conversion specification has the following form:
%[pos
][flags
][width
][.prec
][size
]type
The fields of the conversion specification have the following meanings:
pos
Conversions normally consume arguments in the order that they
are presented. However, it is possible to consume arguments
out of order, and reuse an argument for more than one
conversion specification (although the behavior is undefined
if the same argument is requested with different types), by
specifying pos
, which is a decimal integer followed by
'$'. The integer must be between 1 and <NL_ARGMAX> from
limits.h, and if argument %n$
is requested, all earlier
arguments must be requested somewhere within format
. If
positional parameters are used, then all conversion
specifications except for %%
must specify a position.
This positional parameters method is a POSIX extension to the C
standard definition for the functions.
flags
flags
is an optional sequence of characters which control
output justification, numeric signs, decimal points, trailing
zeros, and octal and hex prefixes. The flag characters are
minus (-
), plus (+
), space ( ), zero (0
), sharp
(#
), and quote ('
). They can appear in any
combination, although not all flags can be used for all
conversion specification types.
'
|
A POSIX extension to the C standard. However, this
implementation presently treats it as a no-op, which
is the default behavior for the C locale, anyway. (If
it did what it is supposed to, when |
-
| The result of the conversion is left justified, and the right is padded with blanks. If you do not use this flag, the result is right justified, and padded on the left. |
+
|
The result of a signed conversion (as
determined by |
" " (space)
|
If the first character of a signed conversion
specification is not a sign, or if a signed
conversion results in no characters, the
result will begin with a space. If the space
( ) flag and the plus ( |
0
|
If the
Note that |
#
|
The result is to be converted to an
alternative form, according to the |
The alternative form output with the # flag depends on the type
character:
o
| Increases precision to force the first digit of the result to be a zero. |
x
|
A non-zero result will have a |
X
|
A non-zero result will have a |
a, A, e, E, f, or F
| The result will always contain a decimal point even if no digits follow the point. (Normally, a decimal point appears only if a digit follows it.) Trailing zeros are removed. |
g or G
| The result will always contain a decimal point even if no digits follow the point. Trailing zeros are not removed. |
all others
| Undefined. |
width
width
is an optional minimum field width. You can
either specify it directly as a decimal integer, or
indirectly by using instead an asterisk (*
), in
which case an int
argument is used as the field
width. If positional arguments are used, then the
width must also be specified positionally as *m$
,
with m as a decimal integer. Negative field widths
are treated as specifying the minus (-
) flag for
left justfication, along with a positive field width.
The resulting format may be wider than the specified
width.
prec
prec
is an optional field; if present, it is
introduced with `.
' (a period). You can specify
the precision either directly as a decimal integer or
indirectly by using an asterisk (*
), in which case
an int
argument is used as the precision. If
positional arguments are used, then the precision must
also be specified positionally as *m$
, with m as a
decimal integer. Supplying a negative precision is
equivalent to omitting the precision. If only a
period is specified the precision is zero. The effect
depends on the conversion type
.
d, i, o, u, x, or X
| Minimum number of digits to appear. If no precision is given, defaults to 1. |
a or A
| Number of digits to appear after the decimal point. If no precision is given, the precision defaults to the minimum needed for an exact representation. |
e, E, f or F
| Number of digits to appear after the decimal point. If no precision is given, the precision defaults to 6. |
g or G
| Maximum number of significant digits. A precision of 0 is treated the same as a precision of 1. If no precision is given, the precision defaults to 6. |
s or S
| Maximum number of characters to print from the string. If no precision is given, the entire string is printed. |
all others
| undefined. |
size
size
is an optional modifier that changes the data
type that the corresponding argument has. Behavior is
unspecified if a size is given that does not match the
type
.
hh
|
With
With |
h
|
With
With |
l
|
With
With
With
With
With |
ll
|
With
With |
j
|
With
With |
z
|
With
With |
t
|
With
With |
L
|
With |
type
type
specifies what kind of conversion wprintf
performs. Here is a table of these:
%
|
Prints the percent character ( |
c
|
If no |
C
|
Short for |
s
|
If no
If an |
S
|
Short for |
d or i
|
Prints a signed decimal integer; takes an
|
o
|
Prints an unsigned octal integer; takes an
|
u
|
Prints an unsigned decimal integer; takes an
|
x
|
Prints an unsigned hexadecimal integer (using
|
X
|
Like |
f
|
Prints a signed value of the form
If the value is infinite, the result is
|
F
|
Like |
e
|
Prints a signed value of the form
|
E
|
Like |
g
|
Prints a signed value in either |
G
|
Like |
a
|
Prints a signed value of the form
|
A
|
Like |
n
|
Takes a pointer to |
p
|
Takes a pointer to |
m
|
Prints the output of |
_wprintf_r
, _fwprintf_r
, _swprintf_r
, are simply
reentrant versions of the functions above.
On success, swprintf
return the number of wide characters in
the output string, except the concluding NUL
is not counted.
wprintf
and fwprintf
return the number of characters transmitted.
If an error occurs, the result of wprintf
, fwprintf
, and
swprintf
is a negative value. For wprintf
and fwprintf
,
errno
may be set according to fputwc
. For swprintf
, errno
may be set to EOVERFLOW if size
is greater than INT_MAX / sizeof (wchar_t),
or when the output does not fit into size
wide characters (including the
terminating wide NULL
).
swscanf — scan and format wide character input
#include <stdio.h>
int wscanf( | const wchar_t *__restrict format, | |
...) ; |
int fwscanf( | FILE *__restrict fd, | |
const wchar_t *__restrict format, | ||
...) ; |
int swscanf( | const wchar_t *__restrict str, | |
const wchar_t *__restrict format, | ||
...) ; |
int _wscanf_r( | struct _reent *ptr, | |
const wchar_t *format, | ||
...) ; |
int _fwscanf_r( | struct _reent *ptr, | |
FILE *fd, | ||
const wchar_t *format, | ||
...) ; |
int _swscanf_r( | struct _reent *ptr, | |
const wchar_t *str, | ||
const wchar_t *format, | ||
...) ; |
wscanf
scans a series of input fields from standard input,
one wide character at a time. Each field is interpreted according to
a format specifier passed to wscanf
in the format string at
*
. format
wscanf
stores the interpreted input from
each field at the address passed to it as the corresponding argument
following format
. You must supply the same number of
format specifiers and address arguments as there are input fields.
There must be sufficient address arguments for the given format specifiers; if not the results are unpredictable and likely disasterous. Excess address arguments are merely ignored.
wscanf
often produces unexpected results if the input diverges from
an expected pattern. Since the combination of gets
or fgets
followed by swscanf
is safe and easy, that is the preferred way
to be certain that a program is synchronized with input at the end
of a line.
fwscanf
and swscanf
are identical to wscanf
, other than the
source of input: fwscanf
reads from a file, and swscanf
from a string.
The routines _wscanf_r
, _fwscanf_r
, and _swscanf_r
are reentrant
versions of wscanf
, fwscanf
, and swscanf
that take an additional
first argument pointing to a reentrancy structure.
The string at *
is a wide character sequence composed
of zero or more directives. Directives are composed of
one or more whitespace characters, non-whitespace characters,
and format specifications.
format
Whitespace characters are blank (), tab (
\t
), or
newline (\n
).
When wscanf
encounters a whitespace character in the format string
it will read (but not store) all consecutive whitespace characters
up to the next non-whitespace character in the input.
Non-whitespace characters are all other ASCII characters except the
percent sign (%
). When wscanf
encounters a non-whitespace
character in the format string it will read, but not store
a matching non-whitespace character.
Format specifications tell wscanf
to read and convert characters
from the input field into specific types of values, and store then
in the locations specified by the address arguments.
Trailing whitespace is left unread unless explicitly matched in the format string.
The format specifiers must begin with a percent sign (%
)
and have the following form:
%[*][width
][size
]type
Each format specification begins with the percent character (%
).
The other fields are:
*
an optional marker; if present, it suppresses interpretation and assignment of this input field.
width
an optional maximum field width: a decimal integer,
which controls the maximum number of characters that
will be read before converting the current input field. If the
input field has fewer than width
characters, wscanf
reads all the characters in the field, and then
proceeds with the next field and its format specification.
If a whitespace or a non-convertable wide character occurs
before width
character are read, the characters up
to that character are read, converted, and stored.
Then wscanf
proceeds to the next format specification.
size
h
, j
, l
, L
, t
, and z
are optional size
characters which override the default way that wscanf
interprets the data type of the corresponding argument.
Modifier | Type(s) | |
---|---|---|
hh | d, i, o, u, x, n | convert input to char, store in char object |
h | d, i, o, u, x, n | convert input to short, store in short object |
h | e, f, c, s, p | no effect |
j | d, i, o, u, x, n | convert input to intmax_t, store in intmax_t object |
j | all others | no effect |
l | d, i, o, u, x, n | convert input to long, store in long object |
l | e, f, g | convert input to double, store in a double object |
l | c, s, [ | the input is stored in a wchar_t object |
l | p | no effect |
ll | d, i, o, u, x, n | convert to long long, store in long long object |
L | d, i, o, u, x, n | convert to long long, store in long long object |
L | e, f, g, E, G | convert to long double, store in long double object |
L | all others | no effect |
t | d, i, o, u, x, n | convert input to ptrdiff_t, store in ptrdiff_t object |
t | all others | no effect |
z | d, i, o, u, x, n | convert input to size_t, store in size_t object |
z | all others | no effect |
type
A character to specify what kind of conversion
wscanf
performs. Here is a table of the conversion
characters:
%
|
No conversion is done; the percent character ( |
c
|
Scans one wide character. Corresponding |
s
|
Reads a character string into the array supplied.
Corresponding |
[ |
Reads a non-empty character string into memory
starting at |
d
|
Reads a decimal integer into the corresponding |
o
|
Reads an octal integer into the corresponding |
u
|
Reads an unsigned decimal integer into the corresponding
|
x,X
|
Read a hexadecimal integer into the corresponding |
e, f, g
|
Read a floating-point number into the corresponding |
E, F, G
|
Read a floating-point number into the corresponding |
i
|
Reads a decimal, octal or hexadecimal integer into the
corresponding |
n
|
Stores the number of characters read in the corresponding
|
p
|
Stores a scanned pointer. ANSI C leaves the details
to each implementation; this implementation treats
|
A pattern
of characters surrounded by square brackets can be used
instead of the s
type character. pattern
is a set of
characters which define a search set of possible characters making up
the wscanf
input field. If the first character in the brackets is a
caret (^
), the search set is inverted to include all ASCII characters
except those between the brackets. There is no range facility as is
defined in the corresponding non-wide character scanf functions.
Ranges are not part of the POSIX standard.
Here are some pattern
examples:
%[abcd]
|
matches wide character strings containing only
|
%[^abcd]
|
matches wide character strings containing any characters except
|
%[A-DW-Z]
|
Note: No wide character ranges, so this expression matches wide
character strings containing |
Floating point numbers (for field types e
, f
, g
, E
,
F
, G
) must correspond to the following general form:
[+/-] ddddd[.]ddd [E|e[+|-]ddd]
where objects inclosed in square brackets are optional, and ddd
represents decimal, octal, or hexadecimal digits.
wscanf
returns the number of input fields successfully
scanned, converted and stored; the return value does
not include scanned fields which were not stored.
If wscanf
attempts to read at end-of-file, the return
value is EOF
.
If no fields were stored, the return value is 0
.
wscanf
might stop scanning a particular field before
reaching the normal field end character, or may
terminate entirely.
wscanf
stops scanning and storing the current field
and moves to the next input field (if any)
in any of the following situations:
The assignment suppressing character (*
) appears
after the %
in the format specification; the current
input field is scanned but not stored.
width
characters have been read (width
is a
width specification, a positive decimal integer).
The next wide character read cannot be converted
under the the current format (for example,
if a Z
is read when the format is decimal).
The next wide character in the input field does not appear in the search set (or does appear in the inverted search set).
When wscanf
stops scanning the current input field for one of
these reasons, the next character is considered unread and
used as the first character of the following input field, or the
first character in a subsequent read operation on the input.
wscanf
will terminate under the following circumstances:
The next wide character in the input field conflicts with a corresponding non-whitespace character in the format string.
The next wide character in the input field is WEOF
.
The format string has been exhausted.
When the format string contains a wide character sequence that is
not part of a format specification, the same wide character
sequence must appear in the input; wscanf
will
scan but not store the matched characters. If a
conflict occurs, the first conflicting wide character remains in the
input as if it had never been read.
tmpfile — create a temporary file
#include <stdio.h>
FILE *tmpfile( | void) ; |
FILE *_tmpfile_r( | struct _reent *reent) ; |
Create a temporary file (a file which will be deleted automatically),
using a name generated by tmpnam
. The temporary file is opened with
the mode "wb+"
, permitting you to read and write anywhere in it
as a binary file (without any data transformations the host system may
perform for text files).
The alternate function _tmpfile_r
is a reentrant version. The
argument reent
is a pointer to a reentrancy structure.
tmpnam — name for a temporary file
#include <stdio.h>
char *tmpnam( | char *s) ; |
char *tempnam( | char *dir, |
char *pfx) ; |
char *_tmpnam_r( | struct _reent *reent, |
char *s) ; |
char *_tempnam_r( | struct _reent *reent, |
char *dir, | |
char *pfx) ; |
Use either of these functions to generate a name for a temporary file.
The generated name is guaranteed to avoid collision with other files
(for up to TMP_MAX
calls of either function).
tmpnam
generates file names with the value of P_tmpdir
(defined in `stdio.h
') as the leading directory component of the path.
You can use the tmpnam
argument s
to specify a suitable area
of memory for the generated filename; otherwise, you can call
tmpnam(NULL)
to use an internal static buffer.
tempnam
allows you more control over the generated filename: you
can use the argument dir
to specify the path to a directory for
temporary files, and you can use the argument pfx
to specify a
prefix for the base filename.
If dir
is NULL
, tempnam
will attempt to use the value of
environment variable TMPDIR
instead; if there is no such value,
tempnam
uses the value of P_tmpdir
(defined in `stdio.h
').
If you don't need any particular prefix to the basename of temporary
files, you can pass NULL
as the pfx
argument to tempnam
.
_tmpnam_r
and _tempnam_r
are reentrant versions of tmpnam
and tempnam
respectively. The extra argument reent
is a
pointer to a reentrancy structure.
The generated filenames are suitable for temporary files, but do not in themselves make files temporary. Files with these names must still be explicitly removed when you no longer want them.
If you supply your own data area s
for tmpnam
, you must ensure
that it has room for at least L_tmpnam
elements of type char
.
ungetc — push data back into a stream
#include <stdio.h>
int ungetc( | int c, |
FILE *stream) ; |
int _ungetc_r( | struct _reent *reent, |
int c, | |
FILE *stream) ; |
ungetc
is used to return bytes back to stream
to be read again.
If c
is EOF, the stream is unchanged. Otherwise, the unsigned
char c
is put back on the stream, and subsequent reads will see
the bytes pushed back in reverse order. Pushed byes are lost if the
stream is repositioned, such as by fseek
, fsetpos
, or
rewind
.
The underlying file is not changed, but it is possible to push back something different than what was originally read. Ungetting a character will clear the end-of-stream marker, and decrement the file position indicator. Pushing back beyond the beginning of a file gives unspecified behavior.
The alternate function _ungetc_r
is a reentrant version. The
extra argument reent
is a pointer to a reentrancy structure.
ungetwc — push wide character data back into a stream
#include <stdio.h>
#include <wchar.h>
wint_t ungetwc( | wint_t wc, |
FILE *stream) ; |
wint_t _ungetwc_r( | struct _reent *reent, |
wint_t wc, | |
FILE *stream) ; |
ungetwc
is used to return wide characters back to stream
to be
read again. If wc
is WEOF, the stream is unchanged. Otherwise, the
wide character wc
is put back on the stream, and subsequent reads will see
the wide chars pushed back in reverse order. Pushed wide chars are lost if the
stream is repositioned, such as by fseek
, fsetpos
, or
rewind
.
The underlying file is not changed, but it is possible to push back something different than what was originally read. Ungetting a character will clear the end-of-stream marker, and decrement the file position indicator. Pushing back beyond the beginning of a file gives unspecified behavior.
The alternate function _ungetwc_r
is a reentrant version. The
extra argument reent
is a pointer to a reentrancy structure.
vfprintf — format argument list
#include <stdio.h>
#include <stdarg.h>
int vprintf( | const char *fmt, |
va_list list) ; |
int vfprintf( | FILE *fp, |
const char *fmt, | |
va_list list) ; |
int vsprintf( | char *str, |
const char *fmt, | |
va_list list) ; |
int vsnprintf( | char *str, |
size_t size, | |
const char *fmt, | |
va_list list) ; |
int vasprintf( | char **strp, |
const char *fmt, | |
va_list list) ; |
char *vasnprintf( | char *str, |
size_t *size, | |
const char *fmt, | |
va_list list) ; |
int _vprintf_r( | struct _reent *reent, |
const char *fmt, | |
va_list list) ; |
int _vfprintf_r( | struct _reent *reent, |
FILE *fp, | |
const char *fmt, | |
va_list list) ; |
int _vsprintf_r( | struct _reent *reent, |
char *str, | |
const char *fmt, | |
va_list list) ; |
int _vasprintf_r( | struct _reent *reent, |
char **str, | |
const char *fmt, | |
va_list list) ; |
int _vsnprintf_r( | struct _reent *reent, |
char *str, | |
size_t size, | |
const char *fmt, | |
va_list list) ; |
char *_vasnprintf_r( | struct _reent *reent, |
char *str, | |
size_t *size, | |
const char *fmt, | |
va_list list) ; |
vprintf
, vfprintf
, vasprintf
, vsprintf
, vsnprintf
,
and vasnprintf
are (respectively) variants of printf
,
fprintf
, asprintf
, sprintf
, snprintf
, and
asnprintf
. They differ only in allowing their caller to pass the
variable argument list as a va_list
object (initialized by
va_start
) rather than directly accepting a variable number of
arguments. The caller is responsible for calling va_end
.
_vprintf_r
, _vfprintf_r
, _vasprintf_r
, _vsprintf_r
,
_vsnprintf_r
, and _vasnprintf_r
are reentrant versions of the
above.
vfscanf — format argument list
#include <stdio.h>
#include <stdarg.h>
int vscanf( | const char *fmt, |
va_list list) ; |
int vfscanf( | FILE *fp, |
const char *fmt, | |
va_list list) ; |
int vsscanf( | const char *str, |
const char *fmt, | |
va_list list) ; |
int _vscanf_r( | struct _reent *reent, |
const char *fmt, | |
va_list list) ; |
int _vfscanf_r( | struct _reent *reent, |
FILE *fp, | |
const char *fmt, | |
va_list list) ; |
int _vsscanf_r( | struct _reent *reent, |
const char *str, | |
const char *fmt, | |
va_list list) ; |
vscanf
, vfscanf
, and vsscanf
are (respectively) variants
of scanf
, fscanf
, and sscanf
. They differ only in
allowing their caller to pass the variable argument list as a
va_list
object (initialized by va_start
) rather than
directly accepting a variable number of arguments.
The return values are consistent with the corresponding functions:
vscanf
returns the number of input fields successfully scanned,
converted, and stored; the return value does not include scanned
fields which were not stored.
If vscanf
attempts to read at end-of-file, the return value
is EOF
.
If no fields were stored, the return value is 0
.
The routines _vscanf_r
, _vfscanf_f
, and _vsscanf_r
are
reentrant versions which take an additional first parameter which points to the
reentrancy structure.
vfwprintf — wide character format argument list
#include <stdio.h>
#include <stdarg.h>
#include <wchar.h>
int vwprintf( | const wchar_t *__restrict fmt, |
va_list list) ; |
int vfwprintf( | FILE *__restrict fp, |
const wchar_t *__restrict fmt, | |
va_list list) ; |
int vswprintf( | wchar_t * __restrict str, |
size_t size, | |
const wchar_t *__ restrict fmt, | |
va_list list) ; |
int _vwprintf_r( | struct _reent *reent, |
const wchar_t *fmt, | |
va_list list) ; |
int _vfwprintf_r( | struct _reent *reent, |
FILE *fp, | |
const wchar_t *fmt, | |
va_list list) ; |
int _vswprintf_r( | struct _reent *reent, |
wchar_t *str, | |
size_t size, | |
const wchar_t *fmt, | |
va_list list) ; |
vwprintf
, vfwprintf
and vswprintf
are (respectively) variants
of wprintf
, fwprintf
and swprintf
. They differ only in allowing
their caller to pass the variable argument list as a va_list
object
(initialized by va_start
) rather than directly accepting a variable
number of arguments. The caller is responsible for calling va_end
.
_vwprintf_r
, _vfwprintf_r
and _vswprintf_r
are reentrant
versions of the above.
vfwscanf — scan and format argument list from wide character input
#include <stdio.h>
#include <stdarg.h>
int vwscanf( | const wchar_t *__restrict fmt, |
va_list list) ; |
int vfwscanf( | FILE *__restrict fp, |
const wchar_t *__restrict fmt, | |
va_list list) ; |
int vswscanf( | const wchar_t *__restrict str, |
const wchar_t *__restrict fmt, | |
va_list list) ; |
int _vwscanf( | struct _reent *reent, |
const wchar_t *fmt, | |
va_list list) ; |
int _vfwscanf( | struct _reent *reent, |
FILE *fp, | |
const wchar_t *fmt, | |
va_list list) ; |
int _vswscanf( | struct _reent *reent, |
const wchar_t *str, | |
const wchar_t *fmt, | |
va_list list) ; |
vwscanf
, vfwscanf
, and vswscanf
are (respectively) variants
of wscanf
, fwscanf
, and swscanf
. They differ only in
allowing their caller to pass the variable argument list as a
va_list
object (initialized by va_start
) rather than
directly accepting a variable number of arguments.
The return values are consistent with the corresponding functions:
vwscanf
returns the number of input fields successfully scanned,
converted, and stored; the return value does not include scanned
fields which were not stored.
If vwscanf
attempts to read at end-of-file, the return value
is EOF
.
If no fields were stored, the return value is 0
.
The routines _vwscanf
, _vfwscanf
, and _vswscanf
are
reentrant versions which take an additional first parameter which points
to the reentrancy structure.
viprintf — format argument list (integer only)
#include <stdio.h>
#include <stdarg.h>
int viprintf( | const char *fmt, |
va_list list) ; |
int vfiprintf( | FILE *fp, |
const char *fmt, | |
va_list list) ; |
int vsiprintf( | char *str, |
const char *fmt, | |
va_list list) ; |
int vsniprintf( | char *str, |
size_t size, | |
const char *fmt, | |
va_list list) ; |
int vasiprintf( | char **strp, |
const char *fmt, | |
va_list list) ; |
char *vasniprintf( | char *str, |
size_t *size, | |
const char *fmt, | |
va_list list) ; |
int _viprintf_r( | struct _reent *reent, |
const char *fmt, | |
va_list list) ; |
int _vfiprintf_r( | struct _reent *reent, |
FILE *fp, | |
const char *fmt, | |
va_list list) ; |
int _vsiprintf_r( | struct _reent *reent, |
char *str, | |
const char *fmt, | |
va_list list) ; |
int _vsniprintf_r( | struct _reent *reent, |
char *str, | |
size_t size, | |
const char *fmt, | |
va_list list) ; |
int _vasiprintf_r( | struct _reent *reent, |
char **str, | |
const char *fmt, | |
va_list list) ; |
char *_vasniprintf_r( | struct _reent *reent, |
char *str, | |
size_t *size, | |
const char *fmt, | |
va_list list) ; |
viprintf
, vfiprintf
, vasiprintf
, vsiprintf
,
vsniprintf
, and vasniprintf
are (respectively) variants of
iprintf
, fiprintf
, asiprintf
, siprintf
, sniprintf
,
and asniprintf
. They differ only in allowing their caller to pass
the variable argument list as a va_list
object (initialized by
va_start
) rather than directly accepting a variable number of
arguments. The caller is responsible for calling va_end
.
_viprintf_r
, _vfiprintf_r
, _vasiprintf_r
,
_vsiprintf_r
, _vsniprintf_r
, and _vasniprintf_r
are
reentrant versions of the above.
viscanf — format argument list
#include <stdio.h>
#include <stdarg.h>
int viscanf( | const char *fmt, |
va_list list) ; |
int vfiscanf( | FILE *fp, |
const char *fmt, | |
va_list list) ; |
int vsiscanf( | const char *str, |
const char *fmt, | |
va_list list) ; |
int _viscanf_r( | struct _reent *reent, |
const char *fmt, | |
va_list list) ; |
int _vfiscanf_r( | struct _reent *reent, |
FILE *fp, | |
const char *fmt, | |
va_list list) ; |
int _vsiscanf_r( | struct _reent *reent, |
const char *str, | |
const char *fmt, | |
va_list list) ; |
viscanf
, vfiscanf
, and vsiscanf
are (respectively) variants
of iscanf
, fiscanf
, and siscanf
. They differ only in
allowing their caller to pass the variable argument list as a
va_list
object (initialized by va_start
) rather than
directly accepting a variable number of arguments.
The return values are consistent with the corresponding functions:
viscanf
returns the number of input fields successfully scanned,
converted, and stored; the return value does not include scanned
fields which were not stored.
If viscanf
attempts to read at end-of-file, the return value
is EOF
.
If no fields were stored, the return value is 0
.
The routines _viscanf_r
, _vfiscanf_f
, and _vsiscanf_r
are
reentrant versions which take an additional first parameter which points to the
reentrancy structure.
Table of Contents
This chapter comprises additional functions to manage large files which are potentially larger than 2GB.
The underlying facilities for input and output depend on the host system, but these functions provide a uniform interface.
The corresponding declarations are in stdio.h
.
fdopen64 — turn open large file into a stream
#include <stdio.h>
FILE *fdopen64( | int fd, |
const char *mode) ; |
FILE *_fdopen64_r( | void *reent, |
int fd, | |
const char *mode) ; |
fopen64 — open a large file
#include <stdio.h>
FILE *fopen64( | const char *file, |
const char *mode) ; |
FILE *_fopen64_r( | void *reent, |
const char *file, | |
const char *mode) ; |
fopen64
is identical to fopen
except it opens a large file that
is potentially >2GB in size. See fopen
for further details.
freopen64 — open a large file using an existing file descriptor
#include <stdio.h>
FILE *freopen64( | const char *file, |
const char *mode, | |
FILE *fp) ; |
FILE *_freopen64_r( | struct _reent *ptr, |
const char *file, | |
const char *mode, | |
FILE *fp) ; |
Use this variant of fopen64
if you wish to specify a particular file
descriptor fp
(notably stdin
, stdout
, or stderr
) for
the file.
If fp
was associated with another file or stream, freopen64
closes that other file or stream (but ignores any errors while closing
it).
file
and mode
are used just as in fopen
.
If file
is NULL
, the underlying stream is modified rather than
closed. The file cannot be given a more permissive access mode (for
example, a mode
of "w" will fail on a read-only file descriptor),
but can change status such as append or binary mode. If modification
is not possible, failure occurs.
ftello64 — return position in a stream or file
#include <stdio.h>
_off64_t ftello64( | FILE *fp) ; |
_off64_t _ftello64_r( | struct _reent *ptr, |
FILE *fp) ; |
Objects of type FILE
can have a ``position'' that records how much
of the file your program has already read. Many of the stdio
functions
depend on this position, and many change it as a side effect.
The result of ftello64
is the current position for a large file
identified by fp
. If you record this result, you can later
use it with fseeko64
to return the file to this
position. The difference between ftello
and ftello64
is that
ftello
returns off_t
and ftello64
is designed to work
for large files (>2GB) and returns _off64_t
.
In the current implementation, ftello64
simply uses a character
count to represent the file position; this is the same number that
would be recorded by fgetpos64
.
The function exists only if the __LARGE64_FILES flag is defined.
An error occurs if the fp
was not opened via fopen64
.
fseeko64 — set file position for large file
#include <stdio.h>
int fseeko64( | FILE *fp, |
_off64_t offset, | |
int whence) ; |
int _fseeko64_r( | struct _reent *ptr, |
FILE *fp, | |
_off64_t offset, | |
int whence) ; |
Objects of type FILE
can have a ``position'' that records how much
of the file your program has already read. Many of the stdio
functions
depend on this position, and many change it as a side effect.
You can use fseeko64
to set the position for the file identified by
fp
that was opened via fopen64
. The value of offset
determines
the new position, in one of three ways selected by the value of whence
(defined as macros in `stdio.h
'):
SEEK_SET
---offset
is the absolute file position (an offset
from the beginning of the file) desired. offset
must be positive.
SEEK_CUR
---offset
is relative to the current file position.
offset
can meaningfully be either positive or negative.
SEEK_END
---offset
is relative to the current end of file.
offset
can meaningfully be either positive (to increase the size
of the file) or negative.
See ftello64
to determine the current file position.
fgetpos64 — record position in a large stream or file
#include <stdio.h>
int fgetpos64( | FILE *fp, |
_fpos64_t *pos) ; |
int _fgetpos64_r( | struct _reent *ptr, |
FILE *fp, | |
_fpos64_t *pos) ; |
Objects of type FILE
can have a ``position'' that records how much
of the file your program has already read. Many of the stdio
functions
depend on this position, and many change it as a side effect.
You can use fgetpos64
to report on the current position for a file
identified by fp
that was opened by fopen64
; fgetpos
will write
a value representing that position at *
. Later, you can
use this value with pos
fsetpos64
to return the file to this
position.
In the current implementation, fgetpos64
simply uses a character
count to represent the file position; this is the same number that
would be returned by ftello64
.
fsetpos64 — restore position of a large stream or file
#include <stdio.h>
int fsetpos64( | FILE *fp, |
const _fpos64_t *pos) ; |
int _fsetpos64_r( | struct _reent *ptr, |
FILE *fp, | |
const _fpos64_t *pos) ; |
Objects of type FILE
can have a ``position'' that records how much
of the file your program has already read. Many of the stdio
functions
depend on this position, and many change it as a side effect.
You can use fsetpos64
to return the large file identified by fp
to a
previous position *
(after first recording it with pos
fgetpos64
).
See fseeko64
for a similar facility.
tmpfile64 — create a large temporary file
#include <stdio.h>
FILE *tmpfile64( | void) ; |
FILE *_tmpfile64_r( | void *reent) ; |
Create a large temporary file (a file which will be deleted automatically),
using a name generated by tmpnam
. The temporary file is opened with
the mode "wb+"
, permitting you to read and write anywhere in it
as a binary file (without any data transformations the host system may
perform for text files). The file may be larger than 2GB.
The alternate function _tmpfile64_r
is a reentrant version. The
argument reent
is a pointer to a reentrancy structure.
Both tmpfile64
and _tmpfile64_r
are only defined if __LARGE64_FILES
is defined.
Table of Contents
This chapter describes string-handling functions and functions for
managing areas of memory. The corresponding declarations are in
string.h
.
bcmp — compare two memory areas
#include <strings.h>
int bcmp( | const void *s1, |
const void *s2, | |
size_t n) ; |
This function compares not more than n
bytes of the
object pointed to by s1
with the object pointed to by s2
.
This function is identical to memcmp
.
bcopy — copy memory regions
#include <strings.h>
void bcopy( | const void *in, |
void *out, | |
size_t n) ; |
bzero — initialize memory to zero
#include <strings.h>
void bzero( | void *b, |
size_t length) ; |
index — search for character in string
#include <strings.h>
char * index( | const char *string, |
int c) ; |
This function finds the first occurence of c
(converted to
a char) in the string pointed to by string
(including the
terminating null character).
This function is identical to strchr
.
memccpy — copy memory regions with end-token check
#include <string.h>
void* memccpy( | void *restrict out, |
const void *restrict in, | |
int endchar, | |
size_t n) ; |
This function copies up to n
bytes from the memory region
pointed to by in
to the memory region pointed to by
out
. If a byte matching the endchar
is encountered,
the byte is copied and copying stops.
If the regions overlap, the behavior is undefined.
memchr — find character in memory
#include <string.h>
void *memchr( | const void *src, |
int c, | |
size_t length) ; |
This function searches memory starting at *
for the
character src
c
. The search only ends with the first
occurrence of c
, or after length
characters; in
particular, NUL
does not terminate the search.
memcmp — compare two memory areas
#include <string.h>
int memcmp( | const void *s1, |
const void *s2, | |
size_t n) ; |
This function compares not more than n
characters of the
object pointed to by s1
with the object pointed to by s2
.
memcpy — copy memory regions
#include <string.h>
void* memcpy( | void *restrict out, |
const void *restrict in, | |
size_t n) ; |
memmem — find memory segment
#include <string.h>
char *memmem( | const void *s1, |
size_t l1, | |
const void *s2, | |
size_t l2) ; |
Locates the first occurrence in the memory region pointed to
by s1
with length l1
of the sequence of bytes pointed
to by s2
of length l2
. If you already know the
lengths of your haystack and needle, memmem
can be much
faster than strstr
.
memmove — move possibly overlapping memory
#include <string.h>
void *memmove( | void *dst, |
const void *src, | |
size_t length) ; |
mempcpy — copy memory regions and return end pointer
#include <string.h>
void* mempcpy( | void *out, |
const void *in, | |
size_t n) ; |
memrchr — reverse search for character in memory
#include <string.h>
void *memrchr( | const void *src, |
int c, | |
size_t length) ; |
This function searches memory starting at length
bytes
beyond *
backwards for the character src
c
.
The search only ends with the first occurrence of c
; in
particular, NUL
does not terminate the search.
memset — set an area of memory
#include <string.h>
void *memset( | void *dst, |
int c, | |
size_t length) ; |
rawmemchr — find character in memory
#include <string.h>
void *rawmemchr( | const void *src, |
int c) ; |
This function searches memory starting at *
for the
character src
c
. The search only ends with the first occurrence
of c
; in particular, NUL
does not terminate the search.
No bounds checking is performed, so this function should only
be used when it is certain that the character c
will be found.
rindex — reverse search for character in string
#include <string.h>
char * rindex( | const char *string, |
int c) ; |
This function finds the last occurence of c
(converted to
a char) in the string pointed to by string
(including the
terminating null character).
This function is identical to strrchr
.
stpcpy — copy string returning a pointer to its end
#include <string.h>
char *stpcpy( | char *restrict dst, |
const char *restrict src) ; |
stpcpy
copies the string pointed to by src
(including the terminating null character) to the array
pointed to by dst
.
stpncpy — counted copy string returning a pointer to its end
#include <string.h>
char *stpncpy( | char *restrict dst, |
const char *restrict src, | |
size_t length) ; |
stpncpy
copies not more than length
characters from the
the string pointed to by src
(including the terminating
null character) to the array pointed to by dst
. If the
string pointed to by src
is shorter than length
characters, null characters are appended to the destination
array until a total of length
characters have been
written.
strcasecmp — case-insensitive character string compare
#include <strings.h>
int strcasecmp( | const char *a, |
const char *b) ; |
strcasestr — case-insensitive character string search
#include <string.h>
char *strcasestr( | const char *s, |
const char *find) ; |
strcasestr
searchs the string s
for
the first occurrence of the sequence find
. strcasestr
is identical to strstr
except the search is
case-insensitive.
strcat — concatenate strings
#include <string.h>
char *strcat( | char *restrict dst, |
const char *restrict src) ; |
strchr — search for character in string
#include <string.h>
char * strchr( | const char *string, |
int c) ; |
This function finds the first occurence of c
(converted to
a char) in the string pointed to by string
(including the
terminating null character).
strchrnul — search for character in string
#include <string.h>
char * strchrnul( | const char *string, |
int c) ; |
This function finds the first occurence of c
(converted to
a char) in the string pointed to by string
(including the
terminating null character).
strcmp — character string compare
#include <string.h>
int strcmp( | const char *a, |
const char *b) ; |
strcoll — locale-specific character string compare
#include <string.h>
int strcoll( | const char *stra, |
const char * strb) ; |
strcoll
compares the string pointed to by stra
to
the string pointed to by strb
, using an interpretation
appropriate to the current LC_COLLATE
state.
strcpy — copy string
#include <string.h>
char *strcpy( | char *dst, |
const char *src) ; |
strcspn — count characters not in string
size_t strcspn( | const char *s1, |
const char *s2) ; |
strerror — convert error number to string
#include <string.h>
char *strerror( | int errnum) ; |
char *_strerror_r( | struct _reent ptr, |
int errnum, | |
int internal, | |
int *error) ; |
strerror
converts the error number errnum
into a
string. The value of errnum
is usually a copy of errno
.
If errnum
is not a known error number, the result points to an
empty string.
This implementation of strerror
prints out the following strings
for each of the values defined in `errno.h
':
0
| Success |
E2BIG
| Arg list too long |
EACCES
| Permission denied |
EADDRINUSE
| Address already in use |
EADDRNOTAVAIL
| Address not available |
EADV
| Advertise error |
EAFNOSUPPORT
| Address family not supported by protocol family |
EAGAIN
| No more processes |
EALREADY
| Socket already connected |
EBADF
| Bad file number |
EBADMSG
| Bad message |
EBUSY
| Device or resource busy |
ECANCELED
| Operation canceled |
ECHILD
| No children |
ECOMM
| Communication error |
ECONNABORTED
| Software caused connection abort |
ECONNREFUSED
| Connection refused |
ECONNRESET
| Connection reset by peer |
EDEADLK
| Deadlock |
EDESTADDRREQ
| Destination address required |
EEXIST
| File exists |
EDOM
| Mathematics argument out of domain of function |
EFAULT
| Bad address |
EFBIG
| File too large |
EHOSTDOWN
| Host is down |
EHOSTUNREACH
| Host is unreachable |
EIDRM
| Identifier removed |
EILSEQ
| Illegal byte sequence |
EINPROGRESS
| Connection already in progress |
EINTR
| Interrupted system call |
EINVAL
| Invalid argument |
EIO
| I/O error |
EISCONN
| Socket is already connected |
EISDIR
| Is a directory |
ELIBACC
| Cannot access a needed shared library |
ELIBBAD
| Accessing a corrupted shared library |
ELIBEXEC
| Cannot exec a shared library directly |
ELIBMAX
| Attempting to link in more shared libraries than system limit |
ELIBSCN
|
|
EMFILE
| File descriptor value too large |
EMLINK
| Too many links |
EMSGSIZE
| Message too long |
EMULTIHOP
| Multihop attempted |
ENAMETOOLONG
| File or path name too long |
ENETDOWN
| Network interface is not configured |
ENETRESET
| Connection aborted by network |
ENETUNREACH
| Network is unreachable |
ENFILE
| Too many open files in system |
ENOBUFS
| No buffer space available |
ENODATA
| No data |
ENODEV
| No such device |
ENOENT
| No such file or directory |
ENOEXEC
| Exec format error |
ENOLCK
| No lock |
ENOLINK
| Virtual circuit is gone |
ENOMEM
| Not enough space |
ENOMSG
| No message of desired type |
ENONET
| Machine is not on the network |
ENOPKG
| No package |
ENOPROTOOPT
| Protocol not available |
ENOSPC
| No space left on device |
ENOSR
| No stream resources |
ENOSTR
| Not a stream |
ENOSYS
| Function not implemented |
ENOTBLK
| Block device required |
ENOTCONN
| Socket is not connected |
ENOTDIR
| Not a directory |
ENOTEMPTY
| Directory not empty |
ENOTRECOVERABLE
| State not recoverable |
ENOTSOCK
| Socket operation on non-socket |
ENOTSUP
| Not supported |
ENOTTY
| Not a character device |
ENXIO
| No such device or address |
EOPNOTSUPP
| Operation not supported on socket |
EOVERFLOW
| Value too large for defined data type |
EOWNERDEAD
| Previous owner died |
EPERM
| Not owner |
EPIPE
| Broken pipe |
EPROTO
| Protocol error |
EPROTOTYPE
| Protocol wrong type for socket |
EPROTONOSUPPORT
| Unknown protocol |
ERANGE
| Result too large |
EREMOTE
| Resource is remote |
EROFS
| Read-only file system |
ESHUTDOWN
| Can't send after socket shutdown |
ESOCKTNOSUPPORT
| Socket type not supported |
ESPIPE
| Illegal seek |
ESRCH
| No such process |
ESRMNT
| Srmount error |
ESTRPIPE
| Strings pipe error |
ETIME
| Stream ioctl timeout |
ETIMEDOUT
| Connection timed out |
ETXTBSY
| Text file busy |
EWOULDBLOCK
| Operation would block (usually same as EAGAIN) |
EXDEV
| Cross-device link |
_strerror_r
is a reentrant version of the above.
ANSI C requires strerror
, but does not specify the strings used
for each error number.
Although this implementation of strerror
is reentrant (depending
on _user_strerror
), ANSI C declares that subsequent calls to
strerror
may overwrite the result string; therefore portable
code cannot depend on the reentrancy of this subroutine.
Although this implementation of strerror
guarantees a non-null
result with a NUL-terminator, some implementations return NULL
on failure. Although POSIX allows strerror
to set errno
to EINVAL on failure, this implementation does not do so (unless
you provide _user_strerror
).
POSIX recommends that unknown errnum
result in a message
including that value, however it is not a requirement and this
implementation does not provide that information (unless you
provide _user_strerror
).
This implementation of strerror
provides for user-defined
extensibility. errno.h
defines __ELASTERROR
, which can be
used as a base for user-defined error values. If the user supplies a
routine named _user_strerror
, and errnum
passed to
strerror
does not match any of the supported values,
_user_strerror
is called with three arguments. The first is of
type int
, and is the errnum
value unknown to strerror
.
The second is of type int
, and matches the internal
argument
of _strerror_r
; this should be zero if called from strerror
and non-zero if called from any other function; _user_strerror
can
use this information to satisfy the POSIX rule that no other
standardized function can overwrite a static buffer reused by
strerror
. The third is of type int *
, and matches the
error
argument of _strerror_r
; if a non-zero value is stored
into that location (usually EINVAL
), then strerror
will set
errno
to that value, and the XPG variant of strerror_r
will
return that value instead of zero or ERANGE
. _user_strerror
returns a char *
value; returning NULL
implies that the user
function did not choose to handle errnum
. The default
_user_strerror
returns NULL
for all input values. Note that
_user_sterror
must be thread-safe, and only denote errors via the
third argument rather than modifying errno
, if strerror
and
strerror_r
are are to comply with POSIX.
strerror
requires no supporting OS subroutines.
strerror_r — convert error number to string and copy to buffer
#include <string.h>
#ifdef _GNU_SOURCE
char *strerror_r( | int errnum, |
char *buffer, | |
size_t n) ; |
#else
int strerror_r( | int errnum, |
char *buffer, | |
size_t n) ; |
#endif
strerror_r
converts the error number errnum
into a
string and copies the result into the supplied buffer
for
a length up to n
, including the NUL terminator. The value of
errnum
is usually a copy of errno
. If errnum
is not a known
error number, the result is the empty string.
See strerror
for how strings are mapped to errnum
.
There are two variants: the GNU version always returns a NUL-terminated
string, which is buffer
if all went well, but which is another
pointer if n
was too small (leaving buffer
untouched). If the
return is not buffer
, your application must not modify that string.
The POSIX version returns 0 on success, EINVAL
if errnum
was not
recognized, and ERANGE
if n
was too small. The variant chosen
depends on macros that you define before inclusion of string.h
.
strerror_r
with a char *
result is a GNU extension.
strerror_r
with an int
result is required by POSIX 2001.
This function is compliant only if _user_strerror
is not provided,
or if it is thread-safe and uses separate storage according to whether
the second argument of that function is non-zero. For more details
on _user_strerror
, see the strerror
documentation.
POSIX states that the contents of buf
are unspecified on error,
although this implementation guarantees a NUL-terminated string for
all except n
of 0.
POSIX recommends that unknown errnum
result in a message including
that value, however it is not a requirement and this implementation
provides only an empty string (unless you provide _user_strerror
).
POSIX also recommends that unknown errnum
fail with EINVAL even
when providing such a message, however it is not a requirement and
this implementation will return success if _user_strerror
provided
a non-empty alternate string without assigning into its third argument.
strerror_r
requires no supporting OS subroutines.
strlen — character string length
#include <string.h>
size_t strlen( | const char *str) ; |
strncasecmp — case-insensitive character string compare
#include <strings.h>
int strncasecmp( | const char *a, |
const char * b, | |
size_t length) ; |
strncasecmp
compares up to length
characters
from the string at a
to the string at b
in a
case-insensitive manner.
strncat — concatenate strings
#include <string.h>
char *strncat( | char *restrict dst, |
const char *restrict src, | |
size_t length) ; |
strncat
appends not more than length
characters from
the string pointed to by src
(including the terminating
null character) to the end of the string pointed to by
dst
. The initial character of src
overwrites the null
character at the end of dst
. A terminating null character
is always appended to the result
strncmp — character string compare
#include <string.h>
int strncmp( | const char *a, |
const char * b, | |
size_t length) ; |
strncpy — counted copy string
#include <string.h>
char *strncpy( | char *restrict dst, |
const char *restrict src, | |
size_t length) ; |
strncpy
copies not more than length
characters from the
the string pointed to by src
(including the terminating
null character) to the array pointed to by dst
. If the
string pointed to by src
is shorter than length
characters, null characters are appended to the destination
array until a total of length
characters have been
written.
strnlen — character string length
#include <string.h>
size_t strnlen( | const char *str, |
size_t n) ; |
strpbrk — find characters in string
#include <string.h>
char *strpbrk( | const char *s1, |
const char *s2) ; |
This function locates the first occurence in the string
pointed to by s1
of any character in string pointed to by
s2
(excluding the terminating null character).
strrchr — reverse search for character in string
#include <string.h>
char * strrchr( | const char *string, |
int c) ; |
This function finds the last occurence of c
(converted to
a char) in the string pointed to by string
(including the
terminating null character).
strsignal — convert signal number to string
#include <string.h>
char *strsignal( | int signal) ; |
strspn — find initial match
#include <string.h>
size_t strspn( | const char *s1, |
const char *s2) ; |
strstr — find string segment
#include <string.h>
char *strstr( | const char *s1, |
const char *s2) ; |
Locates the first occurrence in the string pointed to by s1
of
the sequence of characters in the string pointed to by s2
(excluding the terminating null character).
strtok — get next token from a string
#include <string.h>
char *strtok( | char *restrict source, |
const char *restrict delimiters) ; |
char *strtok_r( | char *restrict source, |
const char *restrict delimiters, | |
char **lasts) ; |
char *strsep( | char **source_ptr, |
const char *delimiters) ; |
The strtok
function is used to isolate sequential tokens in a
null-terminated string, *
. These tokens are delimited
in the string by at least one of the characters in source
*
.
The first time that delimiters
strtok
is called, *
should be
specified; subsequent calls, wishing to obtain further tokens from
the same string, should pass a null pointer instead. The separator
string, source
*
, must be supplied each time and may
change between calls.
delimiters
The strtok
function returns a pointer to the beginning of each
subsequent token in the string, after replacing the separator
character itself with a null character. When no more tokens remain,
a null pointer is returned.
The strtok_r
function has the same behavior as strtok
, except
a pointer to placeholder *
must be supplied by the caller.
lasts
The strsep
function is similar in behavior to strtok
, except
a pointer to the string pointer must be supplied
and
the function does not skip leading delimiters. When the string starts
with a delimiter, the delimiter is changed to the null character and
the empty string is returned. Like source_ptr
strtok_r
and strtok
, the
*
is updated to the next character following the
last delimiter found or NULL if the end of string is reached with
no more delimiters.
source_ptr
strtok
, strtok_r
, and strsep
all return a pointer to the
next token, or NULL
if no more tokens can be found. For
strsep
, a token may be the empty string.
strxfrm — transform string
#include <string.h>
size_t strxfrm( | char *restrict s1, |
const char *restrict s2, | |
size_t n) ; |
This 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 the two transformed strings, it returns
a value greater than, equal to, or less than zero,
correspoinding to the result of a 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
may be a null pointer. If
copying takes place between objects that overlap, the behavior
is undefined.
With a C locale, this function just copies.
swab — swap adjacent bytes
#include <unistd.h>
void swab( | const void *in, |
void *out, | |
ssize_t n) ; |
wcscasecmp — case-insensitive wide character string compare
#include <wchar.h>
int wcscasecmp( | const wchar_t *a, |
const wchar_t *b) ; |
wcscasecmp
compares the wide character string at a
to
the wide character string at b
in a case-insensitive manner.
wcsdup — wide character string duplicate
#include <wchar.h>
wchar_t *wcsdup( | const wchar_t *str) ; |
#include <wchar.h>
wchar_t *_wcsdup_r( | struct _reent *ptr, |
const wchar_t *str) ; |
wcsdup
allocates a new wide character string using malloc
,
and copies the content of the argument str
into the newly
allocated string, thus making a copy of str
.
wcsncasecmp — case-insensitive wide character string compare
#include <wchar.h>
int wcsncasecmp( | const wchar_t *a, |
const wchar_t * b, | |
size_t length) ; |
wcsncasecmp
compares up to length
wide characters
from the string at a
to the string at b
in a
case-insensitive manner.
Table of Contents
This chapter describes wide-character string-handling functions and
managing areas of memory containing wide characters. The corresponding
declarations are in wchar.h
.
wmemchr — find a wide character in memory
#include <wchar.h>
wchar_t *wmemchr( | const wchar_t *s, |
wchar_t c, | |
size_t n) ; |
The wmemchr
function locates the first occurrence of c
in the
initial n
wide characters of the object pointed to be s
. This
function is not affected by locale and all wchar_t values are treated
identically. The null wide character and wchar_t values not
corresponding to valid characters are not treated specially.
If n
is zero, s
must be a valid pointer and the function
behaves as if no valid occurrence of c
is found.
wmemcmp — compare wide characters in memory
#include <wchar.h>
int wmemcmp( | const wchar_t *s1, |
const wchar_t *s2, | |
size_t n) ; |
The wmemcmp
function compares the first n
wide characters of the
object pointed to by s1
to the first n
wide characters of the
object pointed to by s2
. This function is not affected by locale
and all wchar_t values are treated identically. The null wide character
and wchar_t values not corresponding to valid characters are not treated
specially.
If n
is zero, s1
and s2
must be a valid pointers and the
function behaves as if the two objects compare equal.
wmemcpy — copy wide characters in memory
#include <wchar.h>
wchar_t *wmemcpy( | wchar_t *__restrict d, |
const wchar_t *__restrict s, | |
size_t n) ; |
The wmemcpy
function copies n
wide characters from the object
pointed to by s
to the object pointed to be d
. This function
is not affected by locale and all wchar_t values are treated
identically. The null wide character and wchar_t values not
corresponding to valid characters are not treated specially.
If n
is zero, d
and s
must be a valid pointers, and the
function copies zero wide characters.
wmemmove — copy wide characters in memory with overlapping areas
#include <wchar.h>
wchar_t *wmemmove( | wchar_t *d, |
const wchar_t *s, | |
size_t n) ; |
The wmemmove
function copies n
wide characters from the object
pointed to by s
to the object pointed to by d
. Copying takes
place as if the n
wide characters from the object pointed to by
s
are first copied into a temporary array of n
wide characters
that does not overlap the objects pointed to by d
or s
, and then
the n
wide characters from the temporary array are copied into the
object pointed to by d
.
This function is not affected by locale and all wchar_t values are treated identically. The null wide character and wchar_t values not corresponding to valid characters are not treated specially.
If n
is zero, d
and s
must be a valid pointers, and the
function copies zero wide characters.
wmemset — set wide characters in memory
#include <wchar.h>
wchar_t *wmemset( | wchar_t *s, |
wchar_t c, | |
size_t n) ; |
The wmemset
function copies the value of c
into each of the
first n
wide characters of the object pointed to by s
. This
function is not affected by locale and all wchar_t values are treated
identically. The null wide character and wchar_t values not
corresponding to valid characters are not treated specially.
If n
is zero, s
must be a valid pointer and the function
copies zero wide characters.
wcscat — concatenate two wide-character strings
#include <wchar.h>
wchar_t *wcscat( | wchar_t *__restrict s1, |
const wchar_t *__restrict s2) ; |
The wcscat
function appends a copy of the wide-character string
pointed to by s2
(including the terminating null wide-character
code) to the end of the wide-character string pointed to by s1
.
The initial wide-character code of s2
overwrites the null
wide-character code at the end of s1
. If copying takes place between
objects that overlap, the behaviour is undefined.
wcschr — wide-character string scanning operation
#include <wchar.h>
wchar_t *wcschr( | const wchar_t *s, |
wchar_t c) ; |
The wcschr
function locates the first occurrence of c
in the
wide-character string pointed to by s
. The value of c
must be a
character representable as a type wchar_t and must be a wide-character
code corresponding to a valid character in the current locale.
The terminating null wide-character string.
wcscmp — compare two wide-character strings
#include <wchar.h>
int wcscmp( | const wchar_t *s1, |
*s2) ; |
The wcscmp
function compares the wide-character string pointed to
by s1
to the wide-character string pointed to by s2
.
The sign of a non-zero return value is determined by the sign of the difference between the values of the first pair of wide-character codes that differ in the objects being compared.
wcscoll — locale-specific wide-character string compare
#include <wchar.h>
int wcscoll( | const wchar_t *stra, |
const wchar_t * strb) ; |
wcscoll
compares the wide-character string pointed to by
stra
to the wide-character string pointed to by strb
,
using an interpretation appropriate to the current LC_COLLATE
state.
The current implementation of wcscoll
simply uses wcscmp
and does not support any language-specific sorting.
wcscpy — copy a wide-character string
#include <wchar.h>
wchar_t *wcscpy( | wchar_t *__restrict s1, |
const wchar_t *__restrict s2) ; |
wcpcpy — copy a wide-character string returning a pointer to its end
#include <wchar.h>
wchar_t *wcpcpy( | wchar_t *s1, |
const wchar_t *s2) ; |
The wcpcpy
function copies the wide-character string pointed to by
s2
(including the terminating null wide-character code) into the
array pointed to by s1
. If copying takes place between objects that
overlap, the behaviour is undefined.
wcscspn — get length of a complementary wide substring
#include <wchar.h>
size_t wcscspn( | const wchar_t *s, |
wchar_t *set) ; |
The wcscspn
function computes the length of the maximum initial
segment of the wide-character string pointed to by s
which consists
entirely of wide-character codes not from the wide-character string
pointed to by set
.
wcsftime — convert date and time to a formatted wide-character string
#include <time.h>
#include <wchar.h>
size_t wcsftime( | wchar_t *s, |
size_t maxsize, | |
const wchar_t *format, | |
const struct tm *timp) ; |
wcsftime
is equivalent to strftime
, except that:
The argument s points to the initial element of an array of wide characters into which the generated output is to be placed.
The argument maxsize indicates the limiting number of wide characters.
The argument format is a wide-character string and the conversion specifiers are replaced by corresponding sequences of wide characters.
The return value indicates the number of wide characters.
(The difference in all of the above being wide characters versus regular
characters.)
See strftime
for the details of the format specifiers.
When the formatted time takes up no more than maxsize
wide characters,
the result is the length of the formatted wide string. Otherwise, if the
formatting operation was abandoned due to lack of room, the result is
0
, and the wide-character string starting at s
corresponds to just those
parts of *
that could be completely filled in within the
format
maxsize
limit.
C99 and POSIX require wcsftime
, but do not specify the contents of
*
when the formatted string would require more than
s
maxsize
characters. Unrecognized specifiers and fields of
timp
that are out of range cause undefined results. Since some
formats expand to 0 bytes, it is wise to set *
to a nonzero
value beforehand to distinguish between failure and an empty string.
This implementation does not support s
s
being NULL, nor overlapping
s
and format
.
wcsftime
requires no supporting OS subroutines.
wcslcat — concatenate wide-character strings to specified length
#include <wchar.h>
size_t wcslcat( | wchar_t *dst, |
const wchar_t *src, | |
size_t siz) ; |
The wcslcat
function appends wide characters from src
to
end of the dst
wide-character string so that the resultant
wide-character string is not more than siz
wide characters
including the terminating null wide-character code. A terminating
null wide character is always added unless siz
is 0. Thus,
the maximum number of wide characters that can be appended from
src
is siz
- 1. If copying takes place between objects
that overlap, the behaviour is undefined.
wcslcpy — copy a wide-character string to specified length
#include <wchar.h>
size_t wcslcpy( | wchar_t *dst, |
const wchar_t *src, | |
size_t siz) ; |
wcslcpy
copies wide characters from src
to dst
such that up to siz
- 1 characters are copied. A
terminating null is appended to the result, unless siz
is zero.
wcslen — get wide-character string length
#include <wchar.h>
size_t wcslen( | const wchar_t *s) ; |
The wcslen
function computes the number of wide-character codes
in the wide-character string to which s
points, not including the
terminating null wide-character code.
wcsncat — concatenate part of two wide-character strings
#include <wchar.h>
wchar_t *wcsncat( | wchar_t *__restrict s1, |
const wchar_t *__restrict s2, | |
size_t n) ; |
The wcsncat
function appends not more than n
wide-character
codes (a null wide-character code and wide-character codes that follow
it are not appended) from the array pointed to by s2
to the end of
the wide-character string pointed to by s1
. The initial
wide-character code of s2
overwrites the null wide-character code
at the end of s1
.
A terminating null wide-character code is always appended to the result.
If copying takes place between objects that overlap, the behaviour is
undefined.
wcsncmp — compare part of two wide-character strings
#include <wchar.h>
int wcsncmp( | const wchar_t *s1, |
const wchar_t *s2, | |
size_t n) ; |
The wcsncmp
function compares not more than n
wide-character
codes (wide-character codes that follow a null wide-character code are
not compared) from the array pointed to by s1
to the array pointed
to by s2
.
The sign of a non-zero return value is determined by the sign of the difference between the values of the first pair of wide-character codes that differ in the objects being compared.
wcsncpy — copy part of a wide-character string
#include <wchar.h>
wchar_t *wcsncpy( | wchar_t *__restrict s1, |
const wchar_t *__restrict s2, | |
size_t n) ; |
The wcsncpy
function copies not more than n
wide-character codes
(wide-character codes that follow a null wide-character code are not
copied) from the array pointed to by s2
to the array pointed to
by s1
. If copying takes place between objects that overlap, the
behaviour is undefined. Note that if s1
contains more than n
wide characters before its terminating null, the result is not
null-terminated.
If the array pointed to by s2
is a wide-character string that is
shorter than n
wide-character codes, null wide-character codes are
appended to the copy in the array pointed to by s1
, until n
wide-character codes in all are written.
wcpncpy — copy part of a wide-character string returning a pointer to its end
#include <wchar.h>
wchar_t *wcpncpy( | wchar_t *__restrict s1, |
const wchar_t *__restrict s2, | |
size_t n) ; |
The wcpncpy
function copies not more than n wide-character codes
(wide-character codes that follow a null wide-character code are not
copied) from the array pointed to by s2
to the array pointed to
by s1
. If copying takes place between objects that overlap, the
behaviour is undefined.
If the array pointed to by s2
is a wide-character string that is
shorter than n
wide-character codes, null wide-character codes are
appended to the copy in the array pointed to by s1
, until n
wide-character codes in all are written.
wcsnlen — get fixed-size wide-character string length
#include <wchar.h>
size_t wcsnlen( | const wchar_t *s, |
size_t maxlen) ; |
The wcsnlen
function computes the number of wide-character codes
in the wide-character string pointed to by s
not including the
terminating L'\0' wide character but at most maxlen
wide
characters.
wcspbrk — -scan wide-character string for a wide-character code
#include <wchar.h>
wchar_t *wcspbrk( | const wchar_t *s, |
const wchar_t *set) ; |
The wcspbrk
function locates the first occurrence in the
wide-character string pointed to by s
of any wide-character code
from the wide-character string pointed to by set
.
wcsrchr — wide-character string scanning operation
#include <wchar.h>
wchar_t *wcsrchr( | const wchar_t *s, |
wchar_t c) ; |
The wcsrchr
function locates the last occurrence of c
in the
wide-character string pointed to by s
. The value of c
must be a
character representable as a type wchar_t and must be a wide-character
code corresponding to a valid character in the current locale.
The terminating null wide-character code is considered to be part of
the wide-character string.
wcsspn — get length of a wide substring
#include <wchar.h>
size_t wcsspn( | const wchar_t *s, |
const wchar_t *set) ; |
The wcsspn
function computes the length of the maximum initial
segment of the wide-character string pointed to by s
which consists
entirely of wide-character codes from the wide-character string
pointed to by set
.
wcsstr — find a wide-character substring
#include <wchar.h>
wchar_t *wcsstr( | const wchar_t *__restrict big, |
const wchar_t *__restrict little) ; |
The wcsstr
function locates the first occurrence in the
wide-character string pointed to by big
of the sequence of
wide characters (excluding the terminating null wide character) in the
wide-character string pointed to by little
.
wcstok — get next token from a string
#include <wchar.h>
wchar_t *wcstok( | wchar_t *__restrict source, |
const wchar_t *__restrict delimiters, | |
wchar_t **__restrict lasts) ; |
The wcstok
function is the wide-character equivalent of the
strtok_r
function (which in turn is the same as the strtok
function with an added argument to make it thread-safe).
The wcstok
function is used to isolate (one at a time)
sequential tokens in a null-terminated wide-character string,
*
. A token is defined as a substring not containing
any wide-characters from source
*
.
delimiters
The first time that wcstok
is called, *
should
be specified with the wide-character string to be searched, and
source
*
--but not lasts
lasts
, which must be non-NULL--may be
random; subsequent calls, wishing to obtain further tokens from
the same string, should pass a null pointer for *
instead but must supply source
*
unchanged from the last
call. The separator wide-character string, lasts
*
,
must be supplied each time and may change between calls.
A pointer to placeholder delimiters
*
must be supplied by
the caller, and is set each time as needed to save the state
by lasts
wcstok
. Every call to wcstok
with *
== source
NULL
must pass the value of *
as last set
by lasts
wcstok
.
The wcstok
function returns a pointer to the beginning of each
subsequent token in the string, after replacing the separator
wide-character itself with a null wide-character. When no more tokens
remain, a null pointer is returned.
wcstok
returns a pointer to the first wide character of a token, or
NULL
if there is no token.
wcswidth — number of column positions of a wide-character string
#include <wchar.h>
int wcswidth( | const wchar_t *pwcs, |
size_t n) ; |
The wcswidth
function shall determine the number of column
positions required for n
wide-character codes (or fewer than n
wide-character codes if a null wide-character code is encountered
before n
wide-character codes are exhausted) in the string pointed
to by pwcs
.
The wcswidth
function either shall return 0 (if pwcs
points to a
null wide-character code), or return the number of column positions
to be occupied by the wide-character string pointed to by pwcs
, or
return -1 (if any of the first n
wide-character codes in the
wide-character string pointed to by pwcs
is not a printable
wide-character code).
wcsxfrm — locale-specific wide-character string transformation
#include <wchar.h>
int wcsxfrm( | wchar_t *__restrict stra, |
const wchar_t *__restrict strb, | |
size_t n) ; |
wcsxfrm
transforms the wide-character string pointed to by
strb
to the wide-character string pointed to by stra
,
Comparing two transformed wide strings with wcscmp
should return
the same result as comparing the original strings with wcscoll
.
No more than n
wide characters are transformed, including the
trailing null character.
If n
is 0, stra
may be a NULL pointer.
The current implementation of wcsxfrm
simply uses wcslcpy
and does not support any language-specific transformations.
wcwidth — number of column positions of a wide-character code
#include <wchar.h>
int wcwidth( | const wchar_t wc) ; |
The wcwidth
function shall determine the number of column
positions required for the wide character wc
. The application
shall ensure that the value of wc
is a character representable
as a wchar_t, and is a wide-character code corresponding to a
valid character in the current locale.
Table of Contents
A signal is an event that interrupts the normal flow of control
in your program. Your operating environment normally defines the full
set of signals available (see sys/signal.h
), as well as the
default means of dealing with them---typically, either printing an
error message and aborting your program, or ignoring the signal.
All systems support at least the following signals:
SIGABRT |
Abnormal termination of a program; raised by the abort function.
|
SIGFPE | A domain error in arithmetic, such as overflow, or division by zero. |
SIGILL | Attempt to execute as a function data that is not executable. |
SIGINT | Interrupt; an interactive attention signal. |
SIGSEGV | An attempt to access a memory location that is not available. |
SIGTERM | A request that your program end execution. |
Two functions are available for dealing with asynchronous signals---one to allow your program to send signals to itself (this is called raising a signal), and one to specify subroutines (called handlers to handle particular signals that you anticipate may occur---whether raised by your own program or the operating environment.
To support these functions, signal.h
defines three macros:
SIG_DFL
|
Used with the signal function in place of a pointer to a
handler subroutine, to select the operating environment's default
handling of a signal.
|
SIG_IGN
|
Used with the signal function in place of a pointer to a
handler, to ignore a particular signal.
|
SIG_ERR
|
Returned by the signal function in place of a pointer to a
handler, to indicate that your request to set up a handler could not
be honored for some reason.
|
signal.h
also defines an integral type, sig_atomic_t
.
This type is not used in any function declarations; it exists only to
allow your signal handlers to declare a static storage location where
they may store a signal value. (Static storage is not otherwise
reliable from signal handlers.)
psignal — print a signal message on standard error
#include <stdio.h>
void psignal( | int signal, |
const char *prefix) ; |
Use psignal
to print (on standard error) a signal message
corresponding to the value of the signal number signal
.
Unless you use NULL
as the value of the argument prefix
, the
signal message will begin with the string at prefix
, followed by a
colon and a space (:
). The remainder of the signal message is one
of the strings described for strsignal
.
raise — send a signal
#include <signal.h>
int raise( | int sig) ; |
int _raise_r( | void *reent, |
int sig) ; |
Send the signal sig
(one of the macros from `sys/signal.h
').
This interrupts your program's normal flow of execution, and allows a signal
handler (if you've defined one, using signal
) to take control.
The alternate function _raise_r
is a reentrant version. The extra
argument reent
is a pointer to a reentrancy structure.
signal — specify handler subroutine for a signal
#include <signal.h>
void
( | *signal(int sig, |
void(*func)(int))) (int) ; |
void
( | *_signal_r(void *reent, |
int sig, | |
void(*func)(int))) (int) ; |
signal
provides a simple signal-handling implementation for embedded
targets.
signal
allows you to request changed treatment for a particular
signal sig
. You can use one of the predefined macros SIG_DFL
(select system default handling) or SIG_IGN
(ignore this signal)
as the value of func
; otherwise, func
is a function pointer
that identifies a subroutine in your program as the handler for this signal.
Some of the execution environment for signal handlers is
unpredictable; notably, the only library function required to work
correctly from within a signal handler is signal
itself, and
only when used to redefine the handler for the current signal value.
Static storage is likewise unreliable for signal handlers, with one
exception: if you declare a static storage location as `volatile
sig_atomic_t
', then you may use that location in a signal handler to
store signal values.
If your signal handler terminates using return
(or implicit
return), your program's execution continues at the point
where it was when the signal was raised (whether by your program
itself, or by an external event). Signal handlers can also
use functions such as exit
and abort
to avoid returning.
The alternate function _signal_r
is the reentrant version.
The extra argument reent
is a pointer to a reentrancy structure.
Table of Contents
This chapter groups functions used either for reporting on time (elapsed, current, or compute time) or to perform calculations based on time.
The header file time.h
defines three types. clock_t
and
time_t
are both used for representations of time particularly
suitable for arithmetic. (In this implementation, quantities of type
clock_t
have the highest resolution possible on your machine,
and quantities of type time_t
resolve to seconds.) size_t
is also defined if necessary for quantities representing sizes.
time.h
also defines the structure tm
for the traditional
representation of Gregorian calendar time as a series of numbers, with
the following fields:
tm_sec
| Seconds, between 0 and 60 inclusive (60 allows for leap seconds). |
tm_min
| Minutes, between 0 and 59 inclusive. |
tm_hour
| Hours, between 0 and 23 inclusive. |
tm_mday
| Day of the month, between 1 and 31 inclusive. |
tm_mon
| Month, between 0 (January) and 11 (December). |
tm_year
| Year (since 1900), can be negative for earlier years. |
tm_wday
| Day of week, between 0 (Sunday) and 6 (Saturday). |
tm_yday
| Number of days elapsed since last January 1, between 0 and 365 inclusive. |
tm_isdst
| Daylight Savings Time flag: positive means DST in effect, zero means DST not in effect, negative means no information about DST is available. Although for mktime(), negative means that it should decide if DST is in effect or not. |
asctime — format time as string
#include <time.h>
char *asctime( | const struct tm *clock) ; |
char *_asctime_r( | const struct tm *clock, |
char *buf) ; |
clock — cumulative processor time
#include <time.h>
clock_t clock( | void) ; |
Calculates the best available approximation of the cumulative amount
of time used by your program since it started. To convert the result
into seconds, divide by the macro CLOCKS_PER_SEC
.
ctime — convert time to local and format as string
#include <time.h>
char *ctime( | const time_t *clock) ; |
char *ctime_r( | const time_t *clock, |
char *buf) ; |
difftime — subtract two times
#include <time.h>
double difftime( | time_t tim1, |
time_t tim2) ; |
gmtime — convert time to UTC traditional form
#include <time.h>
struct tm *gmtime( | const time_t *clock) ; |
struct tm *gmtime_r( | const time_t *clock, |
struct tm *res) ; |
gmtime
takes the time at clock
representing the number
of elapsed seconds since 00:00:00 on January 1, 1970, Universal
Coordinated Time (UTC, also known in some countries as GMT,
Greenwich Mean time) and converts it to a struct tm
representation.
gmtime
constructs the traditional time representation in static
storage; each call to gmtime
or localtime
will overwrite the
information generated by previous calls to either function.
localtime — convert time to local representation
#include <time.h>
struct tm *localtime( | time_t *clock) ; |
struct tm *localtime_r( | time_t *clock, |
struct tm *res) ; |
localtime
converts the time at clock
into local time, then
converts its representation from the arithmetic representation to the
traditional representation defined by struct tm
.
localtime
constructs the traditional time representation in static
storage; each call to gmtime
or localtime
will overwrite the
information generated by previous calls to either function.
mktime
is the inverse of localtime
.
mktime — convert time to arithmetic representation
#include <time.h>
time_t mktime( | struct tm *timp) ; |
mktime
assumes the time at timp
is a local time, and converts
its representation from the traditional representation defined by
struct tm
into a representation suitable for arithmetic.
localtime
is the inverse of mktime
.
strftime — convert date and time to a formatted string
#include <time.h>
size_t strftime( | char *restrict s, |
size_t maxsize, | |
const char *restrict format, | |
const struct tm *restrict timp) ; |
strftime
converts a struct tm
representation of the time (at
timp
) into a null-terminated string, starting at s
and occupying
no more than maxsize
characters.
You control the format of the output using the string at format
.
*
can contain two kinds of specifications: text to be
copied literally into the formatted string, and time conversion
specifications. Time conversion specifications are two- and
three-character sequences beginning with `format
%
' (use `%%
' to
include a percent sign in the output). Each defined conversion
specification selects only the specified field(s) of calendar time
data from *
, and converts it to a string in one of the
following ways:
timp
%a
|
The abbreviated weekday name according to the current locale. [tm_wday] |
%A
|
The full weekday name according to the current locale.
In the default "C" locale, one of ` |
%b
|
The abbreviated month name according to the current locale. [tm_mon] |
%B
|
The full month name according to the current locale.
In the default "C" locale, one of ` |
%c
|
The preferred date and time representation for the current locale. [tm_sec, tm_min, tm_hour, tm_mday, tm_mon, tm_year, tm_wday] |
%C
|
The century, that is, the year divided by 100 then truncated. For
4-digit years, the result is zero-padded and exactly two characters;
but for other years, there may a negative sign or more digits. In
this way, ` |
%d
|
The day of the month, formatted with two digits (from ` |
%D
|
A string representing the date, in the form ` |
%e
|
The day of the month, formatted with leading space if single digit
(from ` |
%E
|
In some locales, the E modifier selects alternative representations of
certain modifiers |
%F
|
A string representing the ISO 8601:2000 date format, in the form
` |
%g
|
The last two digits of the week-based year, see specifier %G (from
` |
%G
|
The week-based year. In the ISO 8601:2000 calendar, week 1 of the year includes January 4th, and begin on Mondays. Therefore, if January 1st, 2nd, or 3rd falls on a Sunday, that day and earlier belong to the last week of the previous year; and if December 29th, 30th, or 31st falls on Monday, that day and later belong to week 1 of the next year. For consistency with %Y, it always has at least four characters. Example: "%G" for Saturday 2nd January 1999 gives "1998", and for Tuesday 30th December 1997 gives "1998". [tm_year, tm_wday, tm_yday] |
%h
|
Synonym for "%b". [tm_mon] |
%H
|
The hour (on a 24-hour clock), formatted with two digits (from
` |
%I
|
The hour (on a 12-hour clock), formatted with two digits (from
` |
%j
|
The count of days in the year, formatted with three digits
(from ` |
%k
|
The hour (on a 24-hour clock), formatted with leading space if single
digit (from ` |
%l
|
The hour (on a 12-hour clock), formatted with leading space if single
digit (from ` |
%m
|
The month number, formatted with two digits (from ` |
%M
|
The minute, formatted with two digits (from ` |
%n
|
A newline character (` |
%O
|
In some locales, the O modifier selects alternative digit characters
for certain modifiers |
%p
|
Either ` |
%P
|
Same as ' |
%r
|
Replaced by the time in a.m. and p.m. notation. In the "C" locale this is equivalent to "%I:%M:%S %p". In locales which don't define a.m./p.m. notations, the result is an empty string. [tm_sec, tm_min, tm_hour] |
%R
|
The 24-hour time, to the minute. Equivalent to "%H:%M". [tm_min, tm_hour] |
%s
|
The time elapsed, in seconds, since the start of the Unix epoch at 1970-01-01 00:00:00 UTC. |
%S
|
The second, formatted with two digits (from ` |
%t
|
A tab character (` |
%T
|
The 24-hour time, to the second. Equivalent to "%H:%M:%S". [tm_sec, tm_min, tm_hour] |
%u
|
The weekday as a number, 1-based from Monday (from ` |
%U
|
The week number, where weeks start on Sunday, week 1 contains the first
Sunday in a year, and earlier days are in week 0. Formatted with two
digits (from ` |
%V
|
The week number, where weeks start on Monday, week 1 contains January 4th,
and earlier days are in the previous year. Formatted with two digits
(from ` |
%w
|
The weekday as a number, 0-based from Sunday (from ` |
%W
|
The week number, where weeks start on Monday, week 1 contains the first
Monday in a year, and earlier days are in week 0. Formatted with two
digits (from ` |
%x
|
Replaced by the preferred date representation in the current locale. In the "C" locale this is equivalent to "%m/%d/%y". [tm_mon, tm_mday, tm_year] |
%X
|
Replaced by the preferred time representation in the current locale. In the "C" locale this is equivalent to "%H:%M:%S". [tm_sec, tm_min, tm_hour] |
%y
|
The last two digits of the year (from ` |
%Y
|
The full year, equivalent to |
%z
|
The offset from UTC. The format consists of a sign (negative is west of Greewich), two characters for hour, then two characters for minutes (-hhmm or +hhmm). If tm_isdst is negative, the offset is unknown and no output is generated; if it is zero, the offset is the standard offset for the current time zone; and if it is positive, the offset is the daylight savings offset for the current timezone. The offset is determined from the TZ environment variable, as if by calling tzset(). [tm_isdst] |
%Z
|
The time zone name. If tm_isdst is negative, no output is generated. Otherwise, the time zone name is based on the TZ environment variable, as if by calling tzset(). [tm_isdst] |
%%
|
A single character, ` |
When the formatted time takes up no more than maxsize
characters,
the result is the length of the formatted string. Otherwise, if the
formatting operation was abandoned due to lack of room, the result is
0
, and the string starting at s
corresponds to just those
parts of *
that could be completely filled in within the
format
maxsize
limit.
ANSI C requires strftime
, but does not specify the contents of
*
when the formatted string would require more than
s
maxsize
characters. Unrecognized specifiers and fields of
timp
that are out of range cause undefined results. Since some
formats expand to 0 bytes, it is wise to set *
to a nonzero
value beforehand to distinguish between failure and an empty string.
This implementation does not support s
s
being NULL, nor overlapping
s
and format
.
strftime
requires no supporting OS subroutines.
time — get current calendar time (as single number)
#include <time.h>
time_t time( | time_t *t) ; |
time
looks up the best available representation of the current
time and returns it, encoded as a time_t
. It stores the same
value at t
unless the argument is NULL
.
__tz_lock — lock time zone global variables
#include "local.h"
void __tz_lock( | void) ; |
void __tz_unlock( | void) ; |
The tzset
facility functions call these functions when they need to
ensure the values of global variables. The version of these routines
supplied in the library use the lock API defined in sys/lock.h. If multiple
threads of execution can call the time functions and give up scheduling in
the middle, then you you need to define your own versions of these functions
in order to safely lock the time zone variables during a call. If you do
not, the results of localtime
, mktime
, ctime
, and strftime
are undefined.
The lock __tz_lock
may not be called recursively; that is,
a call __tz_lock
will always lock all subsequent __tz_lock
calls
until the corresponding __tz_unlock
call on the same thread is made.
tzset — set timezone characteristics from TZ environment variable
#include <time.h>
void tzset( | void) ; |
void _tzset_r( | struct _reent *reent_ptr) ; |
tzset
examines the TZ environment variable and sets up the three
external variables: _timezone
, _daylight
, and tzname
. The
value of _timezone
shall be the offset from the current time zone
to GMT. The value of _daylight
shall be 0 if there is no daylight
savings time for the current time zone, otherwise it will be non-zero.
The tzname
array has two entries: the first is the name of the
standard time zone, the second is the name of the daylight-savings time
zone.
The TZ environment variable is expected to be in the following POSIX format:
stdoffset1[dst[offset2][,start[/time1],end[/time2]]]
where: std is the name of the standard time-zone (minimum 3 chars) offset1 is the value to add to local time to arrive at Universal time it has the form: hh[:mm[:ss]] dst is the name of the alternate (daylight-savings) time-zone (min 3 chars) offset2 is the value to add to local time to arrive at Universal time it has the same format as the std offset start is the day that the alternate time-zone starts time1 is the optional time that the alternate time-zone starts (this is in local time and defaults to 02:00:00 if not specified) end is the day that the alternate time-zone ends time2 is the time that the alternate time-zone ends (it is in local time and defaults to 02:00:00 if not specified)
Note that there is no white-space padding between fields. Also note that if TZ is null, the default is Universal GMT which has no daylight-savings time. If TZ is empty, the default EST5EDT is used.
The function _tzset_r
is identical to tzset
only it is reentrant
and is used for applications that use multiple threads.
Table of Contents
A locale is the name for a collection of parameters (affecting
collating sequences and formatting conventions) that may be different
depending on location or culture. The "C"
locale is the only
one defined in the ANSI C standard.
This is a minimal implementation, supporting only the required "C"
value for locale; strings representing other locales are not
honored. (""
is also accepted; it represents the default locale
for an implementation, here equivalent to "C"
).
locale.h
defines the structure lconv
to collect the
information on a locale, with the following fields:
char *decimal_point
|
The decimal point character used to format ``ordinary'' numbers (all
numbers except those referring to amounts of money). "." in the
C locale.
|
char *thousands_sep
|
The character (if any) used to separate groups of digits, when
formatting ordinary numbers.
"" in the C locale.
|
char *grouping
|
Specifications for how many digits to group (if any grouping is done at
all) when formatting ordinary numbers. The numeric value of each
character in the string represents the number of digits for the next
group, and a value of 0 (that is, the string's trailing
NULL ) means to continue grouping digits using the last value
specified. Use CHAR_MAX to indicate that no further grouping is
desired. "" in the C locale.
|
char *int_curr_symbol
|
The international currency symbol (first three characters), if any, and
the character used to separate it from numbers.
"" in the C locale.
|
char *currency_symbol
|
The local currency symbol, if any.
"" in the C locale.
|
char *mon_decimal_point
|
The symbol used to delimit fractions in amounts of money.
"" in the C locale.
|
char *mon_thousands_sep
|
Similar to thousands_sep , but used for amounts of money.
"" in the C locale.
|
char *mon_grouping
|
Similar to grouping , but used for amounts of money.
"" in the C locale.
|
char *positive_sign
|
A string to flag positive amounts of money when formatting.
"" in the C locale.
|
char *negative_sign
|
A string to flag negative amounts of money when formatting.
"" in the C locale.
|
char int_frac_digits
|
The number of digits to display when formatting amounts of money to
international conventions.
CHAR_MAX (the largest number representable as a char ) in
the C locale.
|
char frac_digits
|
The number of digits to display when formatting amounts of money to
local conventions.
CHAR_MAX in the C locale.
|
char p_cs_precedes
| 1 indicates the local currency symbol is used before a
positive or zero formatted amount of money; 0 indicates
the currency symbol is placed after the formatted number.
CHAR_MAX in the C locale.
|
char p_sep_by_space
| 1 indicates the local currency symbol must be separated from
positive or zero numbers by a space; 0 indicates that it
is immediately adjacent to numbers.
CHAR_MAX in the C locale.
|
char n_cs_precedes
| 1 indicates the local currency symbol is used before a
negative formatted amount of money; 0 indicates
the currency symbol is placed after the formatted number.
CHAR_MAX in the C locale.
|
char n_sep_by_space
| 1 indicates the local currency symbol must be separated from
negative numbers by a space; 0 indicates that it
is immediately adjacent to numbers.
CHAR_MAX in the C locale.
|
char p_sign_posn
|
Controls the position of the positive sign for
numbers representing money. 0 means parentheses surround the
number; 1 means the sign is placed before both the number and the
currency symbol; 2 means the sign is placed after both the number
and the currency symbol; 3 means the sign is placed just before
the currency symbol; and 4 means the sign is placed just after
the currency symbol.
CHAR_MAX in the C locale.
|
char n_sign_posn
|
Controls the position of the negative sign for numbers
representing money, using the same rules as p_sign_posn .
CHAR_MAX in the C locale.
|
setlocale — select or query locale
#include <locale.h>
char *setlocale( | int category, |
const char *locale) ; |
lconv *localeconv( | void) ; |
char *_setlocale_r( | void *reent, |
int category, | |
const char *locale) ; |
lconv *_localeconv_r( | void *reent) ; |
setlocale
is the facility defined by ANSI C to condition the
execution environment for international collating and formatting
information; localeconv
reports on the settings of the current
locale.
This is a minimal implementation, supporting only the required "POSIX"
and "C"
values for locale
; strings representing other locales are not
honored unless _MB_CAPABLE is defined.
If _MB_CAPABLE is defined, POSIX locale strings are allowed, following the form
language[_TERRITORY][.charset][@modifier]
"language"
is a two character string per ISO 639, or, if not available
for a given language, a three character string per ISO 639-3.
"TERRITORY"
is a country code per ISO 3166. For "charset"
and
"modifier"
see below.
Additionally to the POSIX specifier, the following extension is supported
for backward compatibility with older implementations using newlib:
"C-charset"
.
Instead of "C-"
, you can also specify "C."
. Both variations allow
to specify language neutral locales while using other charsets than ASCII,
for instance "C.UTF-8"
, which keeps all settings as in the C locale,
but uses the UTF-8 charset.
The following charsets are recognized:
"UTF-8"
, "JIS"
, "EUCJP"
, "SJIS"
, "KOI8-R"
, "KOI8-U"
,
"GEORGIAN-PS"
, "PT154"
, "TIS-620"
, "ISO-8859-x"
with
1 <= x <= 16, or "CPxxx"
with xxx in [437, 720, 737, 775, 850, 852, 855,
857, 858, 862, 866, 874, 932, 1125, 1250, 1251, 1252, 1253, 1254, 1255, 1256,
1257, 1258].
Charsets are case insensitive. For instance, "EUCJP"
and "eucJP"
are equivalent. Charset names with dashes can also be written without
dashes, as in "UTF8"
, "iso88591"
or "koi8r"
. "EUCJP"
and
"EUCKR"
are also recognized with dash, "EUC-JP"
and "EUC-KR"
.
Full support for all of the above charsets requires that newlib has been
build with multibyte support and support for all ISO and Windows Codepage.
Otherwise all singlebyte charsets are simply mapped to ASCII. Right now,
only newlib for Cygwin is built with full charset support by default.
Under Cygwin, this implementation additionally supports the charsets
"GBK"
, "GB2312"
, "eucCN"
, "eucKR"
, and "Big5"
. Cygwin
does not support "JIS"
.
Cygwin additionally supports locales from the file /usr/share/locale/locale.alias.
(""
is also accepted; if given, the settings are read from the
corresponding LC_* environment variables and $LANG according to POSIX rules.)
This implementation also supports the modifier "cjknarrow"
, which
affects how the functions wcwidth
and wcswidth
handle characters
from the "CJK Ambiguous Width" category of characters described at
http://www.unicode.org/reports/tr11/#Ambiguous. These characters have a width
of 1 for singlebyte charsets and a width of 2 for multibyte charsets
other than UTF-8. For UTF-8, their width depends on the language specifier:
it is 2 for "zh"
(Chinese), "ja"
(Japanese), and "ko"
(Korean),
and 1 for everything else. Specifying "cjknarrow"
forces a width of 1,
independent of charset and language.
If you use NULL
as the locale
argument, setlocale
returns a
pointer to the string representing the current locale. The acceptable
values for category
are defined in `locale.h
' as macros
beginning with "LC_"
.
localeconv
returns a pointer to a structure (also defined in
`locale.h
') describing the locale-specific conventions currently
in effect.
_localeconv_r
and _setlocale_r
are reentrant versions of
localeconv
and setlocale
respectively. The extra argument
reent
is a pointer to a reentrancy structure.
A successful call to setlocale
returns a pointer to a string
associated with the specified category for the new locale. The string
returned by setlocale
is such that a subsequent call using that
string will restore that category (or all categories in case of LC_ALL),
to that state. The application shall not modify the string returned
which may be overwritten by a subsequent call to setlocale
.
On error, setlocale
returns NULL
.
localeconv
returns a pointer to a structure of type lconv
,
which describes the formatting and collating conventions in effect (in
this implementation, always those of the C locale).
Reentrancy is a characteristic of library functions which allows multiple processes to use the same address space with assurance that the values stored in those spaces will remain constant between calls. The Red Hat newlib implementation of the library functions ensures that whenever possible, these library functions are reentrant. However, there are some functions that can not be trivially made reentrant. Hooks have been provided to allow you to use these functions in a fully reentrant fashion.
These hooks use the structure _reent
defined in reent.h
.
A variable defined as struct _reent
is called a reentrancy structure.
All functions which must manipulate global information are
available in two versions. The first version has the usual name, and
uses a single global instance of the reentrancy structure. The second
has a different name, normally formed by prepending _
and
appending _r
, and takes a pointer to the particular reentrancy
structure to use.
For example, the function fopen
takes two arguments, file
and mode
, and uses the global reentrancy structure. The function
_fopen_r
takes the arguments, struct_reent
, which is a
pointer to an instance of the reentrancy structure, file
and mode
.
There are two versions of struct _reent
, a normal one and one
for small memory systems, controlled by the _REENT_SMALL
definition from the (automatically included) <sys/config.h>
.
Each function which uses the global reentrancy structure uses the global
variable _impure_ptr
, which points to a reentrancy structure.
This means that you have two ways to achieve reentrancy. Both require
that each thread of execution control initialize a unique global
variable of type struct _reent
:
Use the reentrant versions of the library functions, after initializing a global reentrancy structure for each process. Use the pointer to this structure as the extra argument for all library functions.
Ensure that each thread of execution control has a pointer to its own
unique reentrancy structure in the global variable _impure_ptr
,
and call the standard library subroutines.
The following functions are provided in both reentrant and non-reentrant versions.
Equivalent for errno variable: _errno_r
Locale functions: _localeconv_r _setlocale_r
Equivalents for stdio variables: _stdin_r _stdout_r _stderr_r
Stdio functions: _fdopen_r _perror_r _tempnam_r _fopen_r _putchar_r _tmpnam_r _getchar_r _puts_r _tmpfile_r _gets_r _remove_r _vfprintf_r _iprintf_r _rename_r _vsnprintf_r _mkstemp_r _snprintf_r _vsprintf_r _mktemp_t _sprintf_r
Signal functions: _init_signal_r _signal_r _kill_r __sigtramp_r _raise_r
Stdlib functions: _calloc_r _mblen_r _setenv_r _dtoa_r _mbstowcs_r _srand_r _free_r _mbtowc_r _strtod_r _getenv_r _memalign_r _strtol_r _mallinfo_r _mstats_r _strtoul_r _malloc_r _putenv_r _system_r _malloc_r _rand_r _wcstombs_r _malloc_stats_r _realloc_r _wctomb_r
String functions: _strdup_r _strtok_r
System functions: _close_r _link_r _unlink_r _execve_r _lseek_r _wait_r _fcntl_r _open_r _write_r _fork_r _read_r _fstat_r _sbrk_r _gettimeofday_r _stat_r _getpid_r _times_r
Additional 64-bit I/O System functions: _fstat64_r _lseek64_r _open64_r
Time function: _asctime_r
Table of Contents
This chapter describes miscellaneous routines not covered elsewhere.
unctrl — get printable representation of a character
#include <unctrl.h>
char *unctrl( | int c) ; |
int unctrllen( | int c) ; |
unctrl
is a macro which returns the printable representation of c
as a string.
unctrllen
is a macro which returns the length of the printable
representation of c
.
Table of Contents
This chapter groups several utility functions specified by POSIX, but not by C. Each function documents which header to use.
popen — tie a stream to a command string
#include <stdio.h>
FILE *popen( | const char *s, |
const char *mode) ; |
int pclose( | FILE *f) ; |
Use popen
to create a stream to a child process executing a
command string *
as processed by s
/bin/sh
on your system.
The argument mode
must start with either `r
', where the stream
reads from the child's stdout
, or `w
', where the stream writes
to the child's stdin
. As an extension, mode
may also contain
`e
' to set the close-on-exec bit of the parent's file descriptor.
The stream created by popen
must be closed by pclose
to avoid
resource leaks.
Streams created by prior calls to popen
are not visible in
subsequent popen
children, regardless of the close-on-exec bit.
Use ``system(NULL)
'' to test whether your system has /bin/sh
available.
popen
returns a file stream opened with the specified mode
,
or NULL
if a child process could not be created. pclose
returns -1 if the stream was not created by popen
or if the
application used wait
or similar to steal the status; otherwise
it returns the exit status of the child which can be interpreted
in the same manner as a status obtained by waitpid
.
posix_spawn — spawn a process
#include <spawn.h>
int posix_spawn( | pid_t *pid, |
const char *path, | |
const posix_spawn_file_actions_t *file_actions, | |
const posix_spawnattr_t *attrp, | |
char *const argv, | |
char *const envp) ; |
int posix_spawnp( | pid_t *pid, |
const char *file, | |
const posix_spawn_file_actions_t *file_actions, | |
const posix_spawnattr_t *attrp, | |
char *const argv, | |
char *const envp) ; |
Use posix_spawn
and posix_spawnp
to create a new child process
from the specified process image file. argc
is the argument count
and argv
is an array of argument strings passed to the new program.
envp
is an array of stings, which are passed as environment to the
new program.
The path
argument to posix_spawn
identifies the new process
image file to execute. The file
argument to posix_spawnp
is
used to construct a pathname that identifies the new process image
file by duplicating the actions of the shell in searching for an
executable file if the specified filename does not contain a `/
'
character. The file
is sought in the colon-separated list of
directory pathnames specified in the PATH
environment variable.
The file descriptors remain open across posix_spawn
and
posix_spawnp
except for those marked as close-on-exec. The open
file descriptors in the child process can be modified by the spawn file
actions object pointed to by file_actions
.
The spawn attributes object type pointed to by attrp
argument
may contain any of the attributes defined in spawn.h
.
posix_spawn
and posix_spawnp
return the process ID of the newly
spawned child process in the variable pointed by a non-NULL *
argument and zero as the function return value upon successful
completion. Otherwise, pid
posix_spawn
and posix_spawnp
return an
error number as the function return value to indicate the error; the
value stored into the variable pointed to by a non-NULL *
argument is unspecified.
pid
Table of Contents
The C subroutine library depends on a handful of subroutine calls for operating system services. If you use the C library on a system that complies with the POSIX.1 standard (also known as IEEE 1003.1), most of these subroutines are supplied with your operating system.
If some of these subroutines are not provided with your system—in the
extreme case, if you are developing software for a “bare board”
system, without an OS—you will at least need to provide do-nothing
stubs (or subroutines with minimal functionality) to allow your programs to
link with the subroutines in libc.a
.
This is the complete set of system definitions (primarily subroutines)
required; the examples shown implement the minimal functionality required
to allow libc
to link, and fail gracefully where OS services
are not available.
Graceful failure is permitted by returning an error code. A minor
complication arises here: the C library must be compatible with
development environments that supply fully functional versions of these
subroutines. Such environments usually return error codes in a global
errno
. However, the Red Hat newlib C library provides a
macro definition for errno
in the header
file errno.h
, as part of its support for reentrant
routines (see Chapter 10, Reentrancy).
The bridge between these two interpretations
of errno
is straightforward: the C library routines with OS
interface calls capture the errno
values returned globally,
and record them in the appropriate field of the reentrancy structure (so
that you can query them using the errno
macro from
errno.h
).
This mechanism becomes visible when you write stub routines for OS
interfaces. You must include errno.h
, then disable the macro,
like this:
#include <errno.h> #undef errno extern int errno;
The examples in this chapter include this treatment of errno
.
_exit
|
Exit a program without cleaning up files. If your system doesn't
provide this, it is best to avoid linking with subroutines that
require it ( |
close
|
Close a file. Minimal implementation: int close(int file) { return -1; } |
environ
|
A pointer to a list of environment variables and their values. For a minimal environment, this empty list is adequate: char *__env[1] = { 0 }; char **environ = __env; |
execve
|
Transfer control to a new process. Minimal implementation (for a system without processes): #include <errno.h> #undef errno extern int errno; int execve(char *name, char **argv, char **env) { errno = ENOMEM; return -1; } |
fork
|
Create a new process. Minimal implementation (for a system without processes): #include <errno.h> #undef errno extern int errno; int fork(void) { errno = EAGAIN; return -1; } |
fstat
|
Status of an open file. For consistency with other minimal
implementations in these examples, all files are regarded as
character special devices. The #include <sys/stat.h> int fstat(int file, struct stat *st) { st->st_mode = S_IFCHR; return 0; } |
getpid
|
Process-ID; this is sometimes used to generate strings unlikely to conflict with other processes. Minimal implementation, for a system without processes: int getpid(void) { return 1; } |
isatty
|
Query whether output stream is a terminal. For consistency with the
other minimal implementations, which only support output to
int isatty(int file) { return 1; } |
kill
|
Send a signal. Minimal implementation: #include <errno.h> #undef errno extern int errno; int kill(int pid, int sig) { errno = EINVAL; return -1; } |
link
|
Establish a new name for an existing file. Minimal implementation: #include <errno.h> #undef errno extern int errno; int link(char *old, char *new) { errno = EMLINK; return -1; } |
lseek
|
Set position in a file. Minimal implementation: int lseek(int file, int ptr, int dir) { return 0; } |
open
|
Open a file. Minimal implementation: int open(const char *name, int flags, int mode) { return -1; } |
read
|
Read from a file. Minimal implementation: int read(int file, char *ptr, int len) { return 0; } |
sbrk
|
Increase program data space. As
caddr_t sbrk(int incr) {
extern char _end; /* Defined by the linker */
static char *heap_end;
char *prev_heap_end;
if (heap_end == 0) {
heap_end = &_end;
}
prev_heap_end = heap_end;
if (heap_end + incr > stack_ptr) {
write (1, "Heap and stack collision\n", 25);
abort ();
}
heap_end += incr;
return (caddr_t) prev_heap_end;
}
|
stat
|
Status of a file (by name). Minimal implementation: int stat(char *file, struct stat *st) { st->st_mode = S_IFCHR; return 0; } |
times
|
Timing information for current process. Minimal implementation: int times(struct tms *buf) { return -1; } |
unlink
|
Remove a file's directory entry. Minimal implementation: #include <errno.h> #undef errno extern int errno; int unlink(char *name) { errno = ENOENT; return -1; } |
wait
|
Wait for a child process. Minimal implementation: #include <errno.h> #undef errno extern int errno; int wait(int *status) { errno = ECHILD; return -1; } |
write
|
Write to a file. int write(int file, char *ptr, int len) { int todo; for (todo = 0; todo < len; todo++) { outbyte (*ptr++); } return len; } |
Since the system subroutines are used by other library routines that
require reentrancy, libc.a
provides cover routines
(for example, the reentrant version of fork
is
_fork_r
). These cover routines are consistent with the other
reentrant subroutines in this library, and achieve reentrancy by using a
reserved global data block (see Chapter 10, Reentrancy).
_close_r — Reentrant version of close
#include <reent.h>
int _close_r( | struct _reent *ptr, |
int fd) ; |
_execve_r — Reentrant version of execve
#include <reent.h>
int _execve_r( | struct _reent *ptr, |
const char *name, | |
char *const argv[], | |
char *const env[]) ; |
_wait_r — Reentrant version of wait
#include <reent.h>
int _wait_r( | struct _reent *ptr, |
int *status) ; |
_fstat_r — Reentrant version of fstat
#include <reent.h>
int _fstat_r( | struct _reent *ptr, |
int fd, | |
struct stat *pstat) ; |
_link_r — Reentrant version of link
#include <reent.h>
int _link_r( | struct _reent *ptr, |
const char *old, | |
const char *new) ; |
_lseek_r — Reentrant version of lseek
#include <reent.h>
off_t _lseek_r( | struct _reent *ptr, |
int fd, | |
off_t pos, | |
int whence) ; |
_open_r — Reentrant version of open
#include <reent.h>
int _open_r( | struct _reent *ptr, |
const char *file, | |
int flags, | |
int mode) ; |
_read_r — Reentrant version of read
#include <reent.h>
_ssize_t _read_r( | struct _reent *ptr, |
int fd, | |
void *buf, | |
size_t cnt) ; |
_sbrk_r — Reentrant version of sbrk
#include <reent.h>
void *_sbrk_r( | struct _reent *ptr, |
ptrdiff_t incr) ; |
_kill_r — Reentrant version of kill
#include <reent.h>
int _kill_r( | struct _reent *ptr, |
int pid, | |
int sig) ; |
_getpid_r — Reentrant version of getpid
#include <reent.h>
int _getpid_r( | struct _reent *ptr) ; |
_stat_r — Reentrant version of stat
#include <reent.h>
int _stat_r( | struct _reent *ptr, |
const char *file, | |
struct stat *pstat) ; |
_times_r — Reentrant version of times
#include <reent.h>
#include <sys/times.h>
clock_t _times_r( | struct _reent *ptr, |
struct tms *ptms) ; |
Table of Contents
The printf
family of functions is defined to accept a
variable number of arguments, rather than a fixed argument list. You can
define your own functions with a variable argument list, by using macro
definitions from either stdarg.h
(for compatibility
with ANSI C) or from varargs.h
(for compatibility
with a popular convention prior to ANSI C).
In ANSI C, a function has a variable number of arguments when its
parameter list ends in an ellipsis (...
). The parameter
list must also include at least one explicitly named argument; that
argument is used to initialize the variable list data structure.
ANSI C defines three macros (va_start
, va_arg
,
and va_end
) to operate on variable argument lists.
stdarg.h
also defines a special type to represent
variable argument lists: this type is called va_list
.
va_start — Initialize variable argument list
#include <stdarg.h>
void va_start( | va_list ap, |
rightmost
) ; |
Use va_start
to initialize the variable argument list
ap
, so that va_arg
can extract
values from it. rightmost
is the name of the
last explicit argument in the parameter list (the argument
immediately preceding the ellipsis ...
that flags
variable arguments in an ANSI C function header). You can only use
va_start
in a function declared using this ellipsis notation
(not, for example, in one of its subfunctions).
va_arg — Extract a value from argument list
#include <stdarg.h>
type va_args( | va_list ap, |
type
) ; |
va_arg
returns the next unprocessed value from a
variable argument list ap
(which you must
previously create with va_start
). Specify the type for
the value as the second parameter to the macro, type
.
You may pass a va_list
object ap
to
a subfunction, and use va_arg
from the subfunction
rather than from the function actually declared with an ellipsis in
the header; however, in that case you may only
use va_arg
from the subfunction. ANSI C does not
permit extracting successive values from a single variable-argument
list from different levels of the calling stack.
There is no mechanism for testing whether there is actually a next argument available; you might instead pass an argument count (or some other data that implies an argument count) as one of the fixed arguments in your function call.
If your C compiler predates ANSI C, you may still be able to use
variable argument lists using the macros from the
varargs.h
header file. These macros resemble their
ANSI counterparts, but have important differences in usage. In
particular, since traditional C has no declaration mechanism for
variable argument lists, two additional macros are provided simply for
the purpose of defining functions with variable argument lists.
As with stdarg.h
, the type va_list
is
used to hold a data structure representing a variable argument list.
va_alist, va_dcl — Declare variable arguments
#include <varargs.h>
function
( |
va_alist
) ; |
va_dcl
va_start (traditional) — Initialize variable argument list
#include <varargs.h>
va_start
( | va_list ap) ; |
va_arg (traditional) — Extract a value from argument list
#include <varargs.h>
type va_arg( | va_list ap, |
type
) ; |