8503 lines
296 KiB
Plaintext
8503 lines
296 KiB
Plaintext
This is
|
||
/home/xpgcust/tree/RI-2019.1/ib/p4root/Xtensa/SWConfig/../Target-libs/newlib/newlib/libc/libc.info,
|
||
produced by makeinfo version 4.8 from
|
||
/home/xpgcust/tree/RI-2019.1/ib/p4root/Xtensa/SWConfig/../Target-libs/newlib/newlib/libc/libc.texinfo.
|
||
|
||
10/2018
|
||
|
||
This file documents the ANSI C library, version 2.20.0 for Xtensa(R)
|
||
Tools Version 14.2.
|
||
|
||
Copyright (C) 1992, 1993, 1994-2012 Red Hat, Inc. Copyright (C)
|
||
1999-2012 Tensilica, 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.
|
||
|
||
This publication is provided "AS IS." Tensilica, Inc. (hereafter
|
||
"Tensilica") does not make any warranty of any kind, either expressed
|
||
or implied, including, but not limited to, the implied warranties of
|
||
merchantability and fitness for a particular purpose. Information in
|
||
this document is provided solely to enable system and software
|
||
developers to use Tensilica(R) processors. Unless specifically set
|
||
forth herein, there are no express or implied patent, copyright or any
|
||
other intellectual property rights or licenses granted hereunder to
|
||
design or fabricate Tensilica integrated circuits or integrated
|
||
circuits based on the information in this document. Tensilica does not
|
||
warrant that the contents of this publication, whether individually or
|
||
as one or more groups, meets your requirements or that the publication
|
||
is error-free. This publication could include technical inaccuracies
|
||
or typographical errors. Changes may be made to the information
|
||
herein, and these changes may be incorporated in new editions of this
|
||
publication.
|
||
|
||
The following terms are trademarks or registered trademarks of
|
||
Tensilica, Inc.: FLIX, OSKit, Sea of Processors, Tensilica, Vectra,
|
||
Xplorer, XPRES, and Xtensa. All other trademarks and registered
|
||
trademarks are the property of their respective companies.
|
||
|
||
|
||
File: libc.info, Node: Top, Next: Revisions, Up: (dir)
|
||
|
||
The Red Hat newlib C Library
|
||
****************************
|
||
|
||
* Menu:
|
||
|
||
|
||
* Revisions::
|
||
* Introduction::
|
||
|
||
* Stdlib::
|
||
* Ctype::
|
||
* Stdio::
|
||
|
||
* Strings::
|
||
* Wchar strings::
|
||
|
||
* Signals::
|
||
|
||
* Timefns::
|
||
* Locale::
|
||
* Reentrancy::
|
||
|
||
* Misc::
|
||
|
||
* Xtensa::
|
||
|
||
* Syscalls::
|
||
* Arglists::
|
||
|
||
* Library Index::
|
||
|
||
|
||
File: libc.info, Node: Revisions, Next: Introduction, Prev: Top, Up: Top
|
||
|
||
Changes from Previous Versions
|
||
******************************
|
||
|
||
Tensilica newlib C library has been upgraded from version 1.19.0 to
|
||
version 2.0.0.
|
||
|
||
|
||
File: libc.info, Node: Introduction, Next: Stdlib, Prev: Revisions, Up: Top
|
||
|
||
1 Introduction
|
||
**************
|
||
|
||
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. *Note Syscalls::, for a description of the
|
||
relevant operating system calls.
|
||
|
||
|
||
File: libc.info, Node: Stdlib, Next: Ctype, Prev: Introduction, Up: Top
|
||
|
||
2 Standard Utility Functions (`stdlib.h')
|
||
*****************************************
|
||
|
||
This chapter groups utility functions useful in a variety of programs.
|
||
The corresponding declarations are in the header file `stdlib.h'.
|
||
|
||
* Menu:
|
||
|
||
* _Exit:: End program execution without cleaning up
|
||
* a64l:: String to long long
|
||
* abort:: Abnormal termination of a program
|
||
* abs:: Integer absolute value (magnitude)
|
||
* assert:: Macro for Debugging Diagnostics
|
||
* atexit:: Request execution of functions at program exit
|
||
* atof:: String to double or float
|
||
* atoi:: String to integer
|
||
* atoll:: String to long long
|
||
* bsearch:: Binary search
|
||
* calloc:: Allocate space for arrays
|
||
* div:: Divide two integers
|
||
* ecvtbuf:: Double or float to string of digits
|
||
* ecvt:: Double or float to string of digits (malloc result)
|
||
* __env_lock:: Lock environment list for getenv and setenv
|
||
* gvcvt:: Format double or float as string
|
||
* exit:: End program execution
|
||
* getenv:: Look up environment variable
|
||
* labs:: Long integer absolute value (magnitude)
|
||
* ldiv:: Divide two long integers
|
||
* llabs:: Long long integer absolute value (magnitude)
|
||
* lldiv:: Divide two long long integers
|
||
* malloc:: Allocate and manage memory (malloc, realloc, free)
|
||
* mallinfo:: Get information about allocated memory
|
||
* __malloc_lock:: Lock memory pool for malloc and free
|
||
* mbsrtowcs:: Convert a character string to a wide-character string
|
||
* mbstowcs:: Minimal multibyte string to wide string converter
|
||
* mblen:: Minimal multibyte length
|
||
* mbtowc:: Minimal multibyte to wide character converter
|
||
* on_exit:: Request execution of functions at program exit
|
||
* qsort:: Array sort
|
||
* rand:: Pseudo-random numbers
|
||
* rand48:: Uniformly distributed pseudo-random numbers
|
||
* strtod:: String to double or float
|
||
* strtol:: String to long
|
||
* strtoll:: String to long long
|
||
* strtoul:: String to unsigned long
|
||
* strtoull:: String to unsigned long long
|
||
* wcsrtombs:: Convert a wide-character string to a character string
|
||
* wcstod:: Wide string to double or float
|
||
* wcstol:: Wide string to long
|
||
* wcstoll:: Wide string to long long
|
||
* wcstoul:: Wide string to unsigned long
|
||
* wcstoull:: Wide string to unsigned long long
|
||
* system:: Execute command string
|
||
* wcstombs:: Minimal wide string to multibyte string converter
|
||
* wctomb:: Minimal wide character to multibyte converter
|
||
|
||
|
||
File: libc.info, Node: _Exit, Next: a64l, Up: Stdlib
|
||
|
||
2.1 `_Exit'--end program execution with no cleanup processing
|
||
=============================================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
void _Exit(int CODE);
|
||
*Description*
|
||
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'.
|
||
|
||
*Returns*
|
||
`_Exit' does not return to its caller.
|
||
|
||
*Portability*
|
||
`_Exit' is defined by the C99 standard.
|
||
|
||
Supporting OS subroutines required: `_exit'.
|
||
|
||
|
||
File: libc.info, Node: a64l, Next: abort, Prev: _Exit, Up: Stdlib
|
||
|
||
2.2 `a64l', `l64a'--convert between radix-64 ASCII string and long
|
||
==================================================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
long a64l(const char *INPUT);
|
||
char *l64a(long INPUT);
|
||
*Description*
|
||
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.
|
||
|
||
*Returns*
|
||
`l64a' returns a null-terminated string of 0 to 6 characters. `a64l'
|
||
returns the 32-bit translated value from the input character string.
|
||
|
||
*Portability*
|
||
`l64a' and `a64l' are non-ANSI and are defined by the Single Unix
|
||
Specification.
|
||
|
||
Supporting OS subroutines required: None.
|
||
|
||
|
||
File: libc.info, Node: abort, Next: abs, Prev: a64l, Up: Stdlib
|
||
|
||
2.3 `abort'--abnormal termination of a program
|
||
==============================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
void abort(void);
|
||
*Description*
|
||
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).
|
||
|
||
*Returns*
|
||
`abort' does not return to its caller.
|
||
|
||
*Portability*
|
||
ANSI C requires `abort'.
|
||
|
||
Supporting OS subroutines required: `_exit' and optionally, `write'.
|
||
|
||
|
||
File: libc.info, Node: abs, Next: assert, Prev: abort, Up: Stdlib
|
||
|
||
2.4 `abs'--integer absolute value (magnitude)
|
||
=============================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
int abs(int I);
|
||
*Description*
|
||
`abs' returns the absolute value of I (also called the magnitude of I).
|
||
That is, if I is negative, the result is the opposite of I, but if I
|
||
is nonnegative the result is I.
|
||
|
||
The similar function `labs' uses and returns `long' rather than
|
||
`int' values.
|
||
|
||
*Returns*
|
||
The result is a nonnegative integer.
|
||
|
||
*Portability*
|
||
`abs' is ANSI.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: assert, Next: atexit, Prev: abs, Up: Stdlib
|
||
|
||
2.5 `assert'--macro for debugging diagnostics
|
||
=============================================
|
||
|
||
*Synopsis*
|
||
#include <assert.h>
|
||
void assert(int EXPRESSION);
|
||
*Description*
|
||
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, file FILENAME, line LINENO, 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))
|
||
|
||
*Returns*
|
||
`assert' does not return a value.
|
||
|
||
*Portability*
|
||
The `assert' macro is required by ANSI, as is the behavior when
|
||
`NDEBUG' is defined.
|
||
|
||
Supporting OS subroutines required (only if enabled): `close',
|
||
`fstat', `getpid', `isatty', `kill', `lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: atexit, Next: atof, Prev: assert, Up: Stdlib
|
||
|
||
2.6 `atexit'--request execution of functions at program exit
|
||
============================================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
int atexit (void (*FUNCTION)(void));
|
||
*Description*
|
||
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.
|
||
|
||
*Returns*
|
||
`atexit' returns `0' if it succeeds in enrolling your function, `-1' if
|
||
it fails (possible only if no space was available for `malloc' to
|
||
extend the list of functions).
|
||
|
||
*Portability*
|
||
`atexit' is required by the ANSI standard, which also specifies that
|
||
implementations must support enrolling at least 32 functions.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: atof, Next: atoi, Prev: atexit, Up: Stdlib
|
||
|
||
2.7 `atof', `atoff'--string to double or float
|
||
==============================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
double atof(const char *S);
|
||
float atoff(const char *S);
|
||
*Description*
|
||
`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(S)' is implemented as `strtod(S, NULL)'. `atoff(S)' is
|
||
implemented as `strtof(S, NULL)'.
|
||
|
||
*Returns*
|
||
`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'.
|
||
|
||
*Portability*
|
||
`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'.
|
||
|
||
|
||
File: libc.info, Node: atoi, Next: atoll, Prev: atof, Up: Stdlib
|
||
|
||
2.8 `atoi', `atol'--string to integer
|
||
=====================================
|
||
|
||
*Synopsis*
|
||
#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);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
The functions return the converted value, if any. If no conversion was
|
||
made, `0' is returned.
|
||
|
||
*Portability*
|
||
`atoi', `atol' are ANSI.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: atoll, Next: bsearch, Prev: atoi, Up: Stdlib
|
||
|
||
2.9 `atoll'--convert a string to a long long integer
|
||
====================================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
long long atoll(const char *STR);
|
||
long long _atoll_r(struct _reent *PTR, const char *STR);
|
||
*Description*
|
||
The function `atoll' converts the initial portion of the string pointed
|
||
to by `*STR' to a type `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.
|
||
|
||
*Returns*
|
||
The converted value.
|
||
|
||
*Portability*
|
||
`atoll' is ISO 9899 (C99) and POSIX 1003.1-2001 compatable.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: bsearch, Next: calloc, Prev: atoll, Up: Stdlib
|
||
|
||
2.10 `bsearch'--binary search
|
||
=============================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
void *bsearch(const void *KEY, const void *BASE,
|
||
size_t NMEMB, size_t SIZE,
|
||
int (*COMPAR)(const void *, const void *));
|
||
*Description*
|
||
`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 `(*COMPAR)' 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).
|
||
|
||
*Returns*
|
||
Returns a pointer to an element of ARRAY that matches KEY. If more
|
||
than one matching element is available, the result may point to any of
|
||
them.
|
||
|
||
*Portability*
|
||
`bsearch' is ANSI.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: calloc, Next: div, Prev: bsearch, Up: Stdlib
|
||
|
||
2.11 `calloc'--allocate space for arrays
|
||
========================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
void *calloc(size_t N, size_t S);
|
||
void *_calloc_r(void *REENT, size_t N, size_t S);
|
||
*Description*
|
||
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.
|
||
|
||
*Returns*
|
||
If successful, a pointer to the newly allocated space.
|
||
|
||
If unsuccessful, `NULL'.
|
||
|
||
*Portability*
|
||
`calloc' is ANSI.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: div, Next: ecvtbuf, Prev: calloc, Up: Stdlib
|
||
|
||
2.12 `div'--divide two integers
|
||
===============================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
div_t div(int N, int D);
|
||
*Description*
|
||
Divide N/D, returning quotient and remainder as two integers in a
|
||
structure `div_t'.
|
||
|
||
*Returns*
|
||
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 ``R = div(N,D);'' then N equals ``R.rem +
|
||
D*R.quot''.
|
||
|
||
To divide `long' rather than `int' values, use the similar function
|
||
`ldiv'.
|
||
|
||
*Portability*
|
||
`div' is ANSI.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: ecvt, Next: __env_lock, Prev: ecvtbuf, Up: Stdlib
|
||
|
||
2.13 `ecvt', `ecvtf', `fcvt', `fcvtf'--double or float to string
|
||
================================================================
|
||
|
||
*Synopsis*
|
||
#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);
|
||
*Description*
|
||
`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 `*DECPT', and the sign of
|
||
the number in `*SGN'. After formatting a number, `*DECPT' contains the
|
||
number of digits to the left of the decimal point. `*SGN' contains `0'
|
||
if the number is positive, and `1' if it is negative.
|
||
|
||
*Returns*
|
||
All four functions return a pointer to the new string containing a
|
||
character representation of VAL.
|
||
|
||
*Portability*
|
||
None of these functions are ANSI C.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: gvcvt, Next: exit, Prev: __env_lock, Up: Stdlib
|
||
|
||
2.14 `gvcvt', `gcvtf'--format double or float as string
|
||
=======================================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
|
||
char *gcvt(double VAL, int PRECISION, char *BUF);
|
||
char *gcvtf(float VAL, int PRECISION, char *BUF);
|
||
*Description*
|
||
`gcvt' writes a fully formatted number as a null-terminated string in
|
||
the buffer `*BUF'. `gdvtf' produces corresponding character
|
||
representations of `float' numbers.
|
||
|
||
`gcvt' uses the same rules as the `printf' format
|
||
``%.PRECISIONg''--only negative values are signed (with ``-''), and
|
||
either exponential or ordinary decimal-fraction format is chosen
|
||
depending on the number of significant digits (specified by PRECISION).
|
||
|
||
*Returns*
|
||
The result is a pointer to the formatted representation of VAL (the
|
||
same as the argument BUF).
|
||
|
||
*Portability*
|
||
Neither function is ANSI C.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: ecvtbuf, Next: ecvt, Prev: div, Up: Stdlib
|
||
|
||
2.15 `ecvtbuf', `fcvtbuf'--double or float to string
|
||
====================================================
|
||
|
||
*Synopsis*
|
||
#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);
|
||
*Description*
|
||
`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 `*DECPT', and
|
||
the sign of the number in `*SGN'. After formatting a number, `*DECPT'
|
||
contains the number of digits to the left of the decimal point. `*SGN'
|
||
contains `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.
|
||
|
||
*Returns*
|
||
Both functions return a pointer to BUF, the string containing a
|
||
character representation of VAL.
|
||
|
||
*Portability*
|
||
Neither function is ANSI C.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: __env_lock, Next: gvcvt, Prev: ecvt, Up: Stdlib
|
||
|
||
2.16 `__env_lock', `__env_unlock'--lock environ variable
|
||
========================================================
|
||
|
||
*Synopsis*
|
||
#include <envlock.h>
|
||
void __env_lock (struct _reent *REENT);
|
||
void __env_unlock (struct _reent *REENT);
|
||
*Description*
|
||
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.
|
||
|
||
|
||
File: libc.info, Node: exit, Next: getenv, Prev: gvcvt, Up: Stdlib
|
||
|
||
2.17 `exit'--end program execution
|
||
==================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
void exit(int CODE);
|
||
*Description*
|
||
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.
|
||
|
||
*Returns*
|
||
`exit' does not return to its caller.
|
||
|
||
*Portability*
|
||
ANSI C requires `exit', and specifies that `EXIT_SUCCESS' and
|
||
`EXIT_FAILURE' must be defined.
|
||
|
||
Supporting OS subroutines required: `_exit'.
|
||
|
||
|
||
File: libc.info, Node: getenv, Next: labs, Prev: exit, Up: Stdlib
|
||
|
||
2.18 `getenv'--look up environment variable
|
||
===========================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
char *getenv(const char *NAME);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
A pointer to the (string) value of the environment variable, or `NULL'
|
||
if there is no such environment variable.
|
||
|
||
*Portability*
|
||
`getenv' is ANSI, but the rules for properly forming names of
|
||
environment variables vary from one system to another.
|
||
|
||
`getenv' requires a global pointer `environ'.
|
||
|
||
|
||
File: libc.info, Node: labs, Next: ldiv, Prev: getenv, Up: Stdlib
|
||
|
||
2.19 `labs'--long integer absolute value
|
||
========================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
long labs(long I);
|
||
*Description*
|
||
`labs' returns the absolute value of I (also called the magnitude of
|
||
I). That is, if I is negative, the result is the opposite of I, but if
|
||
I is nonnegative the result is I.
|
||
|
||
The similar function `abs' uses and returns `int' rather than `long'
|
||
values.
|
||
|
||
*Returns*
|
||
The result is a nonnegative long integer.
|
||
|
||
*Portability*
|
||
`labs' is ANSI.
|
||
|
||
No supporting OS subroutine calls are required.
|
||
|
||
|
||
File: libc.info, Node: ldiv, Next: llabs, Prev: labs, Up: Stdlib
|
||
|
||
2.20 `ldiv'--divide two long integers
|
||
=====================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
ldiv_t ldiv(long N, long D);
|
||
*Description*
|
||
Divide N/D, returning quotient and remainder as two long integers in a
|
||
structure `ldiv_t'.
|
||
|
||
*Returns*
|
||
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 ``R = ldiv(N,D);'' then N equals ``R.rem
|
||
+ D*R.quot''.
|
||
|
||
To divide `int' rather than `long' values, use the similar function
|
||
`div'.
|
||
|
||
*Portability*
|
||
`ldiv' is ANSI.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: llabs, Next: lldiv, Prev: ldiv, Up: Stdlib
|
||
|
||
2.21 `llabs'--compute the absolute value of an long long integer.
|
||
=================================================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
long long llabs(long long j);
|
||
*Description*
|
||
The `llabs' function computes the absolute value of the long long
|
||
integer argument J (also called the magnitude of J).
|
||
|
||
The similar function `labs' uses and returns `long' rather than
|
||
`long long' values.
|
||
|
||
*Returns*
|
||
A nonnegative long long integer.
|
||
|
||
*Portability*
|
||
`llabs' is ISO 9899 (C99) compatable.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: lldiv, Next: malloc, Prev: llabs, Up: Stdlib
|
||
|
||
2.22 `lldiv'--divide two long long integers
|
||
===========================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
lldiv_t lldiv(long long N, long long D);
|
||
*Description*
|
||
Divide N/D, returning quotient and remainder as two long long integers
|
||
in a structure `lldiv_t'.
|
||
|
||
*Returns*
|
||
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 ``R = ldiv(N,D);'' then N equals ``R.rem
|
||
+ D*R.quot''.
|
||
|
||
To divide `long' rather than `long long' values, use the similar
|
||
function `ldiv'.
|
||
|
||
*Portability*
|
||
`lldiv' is ISO 9899 (C99) compatable.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: malloc, Next: mallinfo, Prev: lldiv, Up: Stdlib
|
||
|
||
2.23 `malloc', `realloc', `free'--manage memory
|
||
===============================================
|
||
|
||
*Synopsis*
|
||
#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);
|
||
*Description*
|
||
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. *Note Stubs::.
|
||
|
||
*Returns*
|
||
`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(APTR,0)'' (which has the same effect as ``free(APTR)'').
|
||
You should always check the result of `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.
|
||
|
||
*Portability*
|
||
`malloc', `realloc', and `free' are specified by the ANSI C standard,
|
||
but other conforming implementations of `malloc' may behave differently
|
||
when NBYTES is zero.
|
||
|
||
`memalign' is part of SVR4.
|
||
|
||
`malloc_usable_size' is not portable.
|
||
|
||
Supporting OS subroutines required: `sbrk'.
|
||
|
||
File: libc.info, Node: mallinfo, Next: __malloc_lock, Prev: malloc, Up: Stdlib
|
||
|
||
2.24 `mallinfo', `malloc_stats', `mallopt'--malloc support
|
||
==========================================================
|
||
|
||
*Synopsis*
|
||
#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);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
`mallinfo' returns a mallinfo structure. The structure is defined in
|
||
malloc.h.
|
||
|
||
`malloc_stats' does not return a result.
|
||
|
||
`mallopt' returns zero if the parameter could not be set, or
|
||
non-zero if it could be set.
|
||
|
||
*Portability*
|
||
`mallinfo' and `mallopt' are provided by SVR4, but `mallopt' takes
|
||
different parameters on different systems. `malloc_stats' is not
|
||
portable.
|
||
|
||
|
||
File: libc.info, Node: __malloc_lock, Next: mbsrtowcs, Prev: mallinfo, Up: Stdlib
|
||
|
||
2.25 `__malloc_lock', `__malloc_unlock'--lock malloc pool
|
||
=========================================================
|
||
|
||
*Synopsis*
|
||
#include <malloc.h>
|
||
void __malloc_lock (struct _reent *REENT);
|
||
void __malloc_unlock (struct _reent *REENT);
|
||
*Description*
|
||
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.
|
||
|
||
|
||
File: libc.info, Node: mblen, Next: mbtowc, Prev: mbstowcs, Up: Stdlib
|
||
|
||
2.26 `mblen'--minimal multibyte length function
|
||
===============================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
int mblen(const char *S, size_t N);
|
||
*Description*
|
||
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.
|
||
|
||
*Returns*
|
||
This implementation of `mblen' returns `0' if S is `NULL' or the empty
|
||
string; it returns `1' if not _MB_CAPABLE or the character is a
|
||
single-byte character; it returns `-1' if the multi-byte character is
|
||
invalid; otherwise it returns the number of bytes in the multibyte
|
||
character.
|
||
|
||
*Portability*
|
||
`mblen' is required in the ANSI C standard. However, the precise
|
||
effects vary with the locale.
|
||
|
||
`mblen' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: mbsrtowcs, Next: mbstowcs, Prev: __malloc_lock, Up: Stdlib
|
||
|
||
2.27 `mbsrtowcs', `mbsnrtowcs'--convert a character string to a wide-character string
|
||
=====================================================================================
|
||
|
||
*Synopsis*
|
||
#include <wchar.h>
|
||
size_t mbsrtowcs(wchar_t *DST, const char **SRC, size_t LEN,
|
||
mbstate_t *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 *DST, const char **SRC,
|
||
size_t NMS, size_t LEN, mbstate_t *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);
|
||
*Description*
|
||
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.
|
||
|
||
*Returns*
|
||
The `mbsrtowcs' and `mbsnrtowcs' functions return the number of wide
|
||
characters stored in the array pointed to by DST if successful,
|
||
otherwise it returns (size_t)-1.
|
||
|
||
*Portability*
|
||
`mbsrtowcs' is defined by the C99 standard. `mbsnrtowcs' is defined by
|
||
the POSIX.1-2008 standard.
|
||
|
||
|
||
File: libc.info, Node: mbstowcs, Next: mblen, Prev: mbsrtowcs, Up: Stdlib
|
||
|
||
2.28 `mbstowcs'--minimal multibyte string to wide char converter
|
||
================================================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
int mbstowcs(wchar_t *PWC, const char *S, size_t N);
|
||
*Description*
|
||
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.
|
||
|
||
*Returns*
|
||
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.
|
||
|
||
*Portability*
|
||
`mbstowcs' is required in the ANSI C standard. However, the precise
|
||
effects vary with the locale.
|
||
|
||
`mbstowcs' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: mbtowc, Next: on_exit, Prev: mblen, Up: Stdlib
|
||
|
||
2.29 `mbtowc'--minimal multibyte to wide char converter
|
||
=======================================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
int mbtowc(wchar_t *PWC, const char *S, size_t N);
|
||
*Description*
|
||
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 `*S' to
|
||
`*PWC', unless 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.
|
||
|
||
*Returns*
|
||
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.
|
||
|
||
*Portability*
|
||
`mbtowc' is required in the ANSI C standard. However, the precise
|
||
effects vary with the locale.
|
||
|
||
`mbtowc' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: on_exit, Next: qsort, Prev: mbtowc, Up: Stdlib
|
||
|
||
2.30 `on_exit'--request execution of function with argument at program exit
|
||
===========================================================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
int on_exit (void (*FUNCTION)(int, void *), void *ARG);
|
||
*Description*
|
||
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.
|
||
|
||
*Returns*
|
||
`on_exit' returns `0' if it succeeds in enrolling your function, `-1'
|
||
if it fails (possible only if no space was available for `malloc' to
|
||
extend the list of functions).
|
||
|
||
*Portability*
|
||
`on_exit' is a non-standard glibc extension
|
||
|
||
Supporting OS subroutines required: None
|
||
|
||
|
||
File: libc.info, Node: qsort, Next: rand, Prev: on_exit, Up: Stdlib
|
||
|
||
2.31 `qsort'--sort an array
|
||
===========================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
void qsort(void *BASE, size_t NMEMB, size_t SIZE,
|
||
int (*COMPAR)(const void *, const void *) );
|
||
*Description*
|
||
`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 `(*COMPAR)' 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).
|
||
|
||
The array is sorted in place; that is, when `qsort' returns, the
|
||
array elements beginning at BASE have been reordered.
|
||
|
||
*Returns*
|
||
`qsort' does not return a result.
|
||
|
||
*Portability*
|
||
`qsort' is required by ANSI (without specifying the sorting algorithm).
|
||
|
||
|
||
File: libc.info, Node: rand, Next: rand48, Prev: qsort, Up: Stdlib
|
||
|
||
2.32 `rand', `srand'--pseudo-random numbers
|
||
===========================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
int rand(void);
|
||
void srand(unsigned int SEED);
|
||
int rand_r(unsigned int *SEED);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
`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.
|
||
|
||
*Portability*
|
||
`rand' is required by ANSI, but the algorithm for pseudo-random number
|
||
generation is not specified; therefore, even if you use the same random
|
||
seed, you cannot expect the same sequence of results on two different
|
||
systems.
|
||
|
||
`rand' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: rand48, Next: strtod, Prev: rand, Up: Stdlib
|
||
|
||
2.33 `rand48', `drand48', `erand48', `lrand48', `nrand48', `mrand48', `jrand48', `srand48', `seed48', `lcong48'--pseudo-random number generators and initialization routines
|
||
============================================================================================================================================================================
|
||
|
||
*Synopsis*
|
||
#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]);
|
||
*Description*
|
||
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'.
|
||
|
||
*Portability*
|
||
SUS requires these functions.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: strtod, Next: strtol, Prev: rand48, Up: Stdlib
|
||
|
||
2.34 `strtod', `strtof'--string to double or float
|
||
==================================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
double strtod(const char *STR, char **TAIL);
|
||
float strtof(const char *STR, char **TAIL);
|
||
|
||
double _strtod_r(void *REENT,
|
||
const char *STR, char **TAIL);
|
||
*Description*
|
||
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 `*TAIL'.
|
||
Otherwise, the substring is converted, and a pointer to the final string
|
||
(which will contain at least the terminating null character of STR) is
|
||
stored in `*TAIL'. If you want no assignment to `*TAIL', pass a null
|
||
pointer as 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.
|
||
|
||
*Returns*
|
||
`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'.
|
||
|
||
|
||
File: libc.info, Node: strtol, Next: strtoll, Prev: strtod, Up: Stdlib
|
||
|
||
2.35 `strtol'--string to long
|
||
=============================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
long strtol(const char *S, char **PTR,int BASE);
|
||
|
||
long _strtol_r(void *REENT,
|
||
const char *S, char **PTR,int BASE);
|
||
*Description*
|
||
The function `strtol' converts the string `*S' to a `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.
|
||
|
||
*Returns*
|
||
`strtol' returns the converted value, if any. If no conversion was
|
||
made, 0 is returned.
|
||
|
||
`strtol' returns `LONG_MAX' or `LONG_MIN' if the magnitude of the
|
||
converted value is too large, and sets `errno' to `ERANGE'.
|
||
|
||
*Portability*
|
||
`strtol' is ANSI.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: strtoll, Next: strtoul, Prev: strtol, Up: Stdlib
|
||
|
||
2.36 `strtoll'--string to long long
|
||
===================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
long long strtoll(const char *S, char **PTR,int BASE);
|
||
|
||
long long _strtoll_r(void *REENT,
|
||
const char *S, char **PTR,int BASE);
|
||
*Description*
|
||
The function `strtoll' converts the string `*S' to a `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.
|
||
|
||
*Returns*
|
||
`strtoll' returns the converted value, if any. If no conversion was
|
||
made, 0 is returned.
|
||
|
||
`strtoll' returns `LONG_LONG_MAX' or `LONG_LONG_MIN' if the
|
||
magnitude of the converted value is too large, and sets `errno' to
|
||
`ERANGE'.
|
||
|
||
*Portability*
|
||
`strtoll' is ANSI.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: strtoul, Next: strtoull, Prev: strtoll, Up: Stdlib
|
||
|
||
2.37 `strtoul'--string to unsigned long
|
||
=======================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
unsigned long strtoul(const char *S, char **PTR,
|
||
int BASE);
|
||
|
||
unsigned long _strtoul_r(void *REENT, const char *S,
|
||
char **PTR, int BASE);
|
||
*Description*
|
||
The function `strtoul' converts the string `*S' to an `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.
|
||
|
||
*Returns*
|
||
`strtoul' returns the converted value, if any. If no conversion was
|
||
made, `0' is returned.
|
||
|
||
`strtoul' returns `ULONG_MAX' if the magnitude of the converted
|
||
value is too large, and sets `errno' to `ERANGE'.
|
||
|
||
*Portability*
|
||
`strtoul' is ANSI.
|
||
|
||
`strtoul' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: strtoull, Next: wcsrtombs, Prev: strtoul, Up: Stdlib
|
||
|
||
2.38 `strtoull'--string to unsigned long long
|
||
=============================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
unsigned long long strtoull(const char *S, char **PTR,
|
||
int BASE);
|
||
|
||
unsigned long long _strtoull_r(void *REENT, const char *S,
|
||
char **PTR, int BASE);
|
||
*Description*
|
||
The function `strtoull' converts the string `*S' to an `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.
|
||
|
||
*Returns*
|
||
`strtoull' returns the converted value, if any. If no conversion was
|
||
made, `0' is returned.
|
||
|
||
`strtoull' returns `ULONG_LONG_MAX' if the magnitude of the converted
|
||
value is too large, and sets `errno' to `ERANGE'.
|
||
|
||
*Portability*
|
||
`strtoull' is ANSI.
|
||
|
||
`strtoull' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: wcsrtombs, Next: wcstod, Prev: strtoull, Up: Stdlib
|
||
|
||
2.39 `wcsrtombs', `wcsnrtombs'--convert a wide-character string to a character string
|
||
=====================================================================================
|
||
|
||
*Synopsis*
|
||
#include <wchar.h>
|
||
size_t wcsrtombs(char *DST, const wchar_t **SRC, size_t LEN,
|
||
mbstate_t *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 *DST, const wchar_t **SRC,
|
||
size_t NWC, size_t LEN, mbstate_t *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);
|
||
*Description*
|
||
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.
|
||
|
||
*Returns*
|
||
The `wcsrtombs' and `wcsnrtombs' functions return the number of bytes
|
||
stored in the array pointed to by DST (not including any terminating
|
||
null), if successful, otherwise it returns (size_t)-1.
|
||
|
||
*Portability*
|
||
`wcsrtombs' is defined by C99 standard. `wcsnrtombs' is defined by the
|
||
POSIX.1-2008 standard.
|
||
|
||
|
||
File: libc.info, Node: wcstod, Next: wcstol, Prev: wcsrtombs, Up: Stdlib
|
||
|
||
2.40 `wcstod', `wcstof'--wide char string to double or float
|
||
============================================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
double wcstod(const wchar_t *STR, wchar_t **TAIL);
|
||
float wcstof(const wchar_t *STR, wchar_t **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);
|
||
*Description*
|
||
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 `*TAIL'.
|
||
Otherwise, the substring is converted, and a pointer to the final string
|
||
(which will contain at least the terminating null character of STR) is
|
||
stored in `*TAIL'. If you want no assignment to `*TAIL', pass a null
|
||
pointer as 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.
|
||
|
||
*Returns*
|
||
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'.
|
||
|
||
|
||
File: libc.info, Node: wcstol, Next: wcstoll, Prev: wcstod, Up: Stdlib
|
||
|
||
2.41 `wcstol'--wide string to long
|
||
==================================
|
||
|
||
*Synopsis*
|
||
#include <wchar.h>
|
||
long wcstol(const wchar_t *S, wchar_t **PTR,int BASE);
|
||
|
||
long _wcstol_r(void *REENT,
|
||
const wchar_t *S, wchar_t **PTR,int BASE);
|
||
*Description*
|
||
The function `wcstol' converts the wide string `*S' to a `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.
|
||
|
||
*Returns*
|
||
`wcstol' returns the converted value, if any. If no conversion was
|
||
made, 0 is returned.
|
||
|
||
`wcstol' returns `LONG_MAX' or `LONG_MIN' if the magnitude of the
|
||
converted value is too large, and sets `errno' to `ERANGE'.
|
||
|
||
*Portability*
|
||
`wcstol' is ANSI.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: wcstoll, Next: wcstoul, Prev: wcstol, Up: Stdlib
|
||
|
||
2.42 `wcstoll'--wide string to long long
|
||
========================================
|
||
|
||
*Synopsis*
|
||
#include <wchar.h>
|
||
long long wcstoll(const wchar_t *S, wchar_t **PTR,int BASE);
|
||
|
||
long long _wcstoll_r(void *REENT,
|
||
const wchar_t *S, wchar_t **PTR,int BASE);
|
||
*Description*
|
||
The function `wcstoll' converts the wide string `*S' to a `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.
|
||
|
||
*Returns*
|
||
`wcstoll' returns the converted value, if any. If no conversion was
|
||
made, 0 is returned.
|
||
|
||
`wcstoll' returns `LONG_LONG_MAX' or `LONG_LONG_MIN' if the
|
||
magnitude of the converted value is too large, and sets `errno' to
|
||
`ERANGE'.
|
||
|
||
*Portability*
|
||
`wcstoll' is ANSI.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: wcstoul, Next: wcstoull, Prev: wcstoll, Up: Stdlib
|
||
|
||
2.43 `wcstoul'--wide string to unsigned long
|
||
============================================
|
||
|
||
*Synopsis*
|
||
#include <wchar.h>
|
||
unsigned long wcstoul(const wchar_t *S, wchar_t **PTR,
|
||
int BASE);
|
||
|
||
unsigned long _wcstoul_r(void *REENT, const wchar_t *S,
|
||
wchar_t **PTR, int BASE);
|
||
*Description*
|
||
The function `wcstoul' converts the wide string `*S' to an `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.
|
||
|
||
*Returns*
|
||
`wcstoul' returns the converted value, if any. If no conversion was
|
||
made, `0' is returned.
|
||
|
||
`wcstoul' returns `ULONG_MAX' if the magnitude of the converted
|
||
value is too large, and sets `errno' to `ERANGE'.
|
||
|
||
*Portability*
|
||
`wcstoul' is ANSI.
|
||
|
||
`wcstoul' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: wcstoull, Next: system, Prev: wcstoul, Up: Stdlib
|
||
|
||
2.44 `wcstoull'--wide string to unsigned long long
|
||
==================================================
|
||
|
||
*Synopsis*
|
||
#include <wchar.h>
|
||
unsigned long long wcstoull(const wchar_t *S, wchar_t **PTR,
|
||
int BASE);
|
||
|
||
unsigned long long _wcstoull_r(void *REENT, const wchar_t *S,
|
||
wchar_t **PTR, int BASE);
|
||
*Description*
|
||
The function `wcstoull' converts the wide string `*S' to an `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.
|
||
|
||
*Returns*
|
||
`wcstoull' returns `0' and sets `errno' to `EINVAL' if the value of
|
||
BASE is not supported.
|
||
|
||
`wcstoull' returns the converted value, if any. If no conversion was
|
||
made, `0' is returned.
|
||
|
||
`wcstoull' returns `ULLONG_MAX' if the magnitude of the converted
|
||
value is too large, and sets `errno' to `ERANGE'.
|
||
|
||
*Portability*
|
||
`wcstoull' is ANSI.
|
||
|
||
`wcstoull' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: system, Next: wcstombs, Prev: wcstoull, Up: Stdlib
|
||
|
||
2.45 `system'--execute command string
|
||
=====================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
int system(char *S);
|
||
|
||
int _system_r(void *REENT, char *S);
|
||
*Description*
|
||
Use `system' to pass a command string `*S' to `/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.
|
||
|
||
*Returns*
|
||
`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'.
|
||
|
||
*Portability*
|
||
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'.
|
||
|
||
|
||
File: libc.info, Node: wcstombs, Next: wctomb, Prev: system, Up: Stdlib
|
||
|
||
2.46 `wcstombs'--minimal wide char string to multibyte string converter
|
||
=======================================================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
size_t wcstombs(char *S, const wchar_t *PWC, size_t N);
|
||
*Description*
|
||
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.
|
||
|
||
*Returns*
|
||
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.
|
||
|
||
*Portability*
|
||
`wcstombs' is required in the ANSI C standard. However, the precise
|
||
effects vary with the locale.
|
||
|
||
`wcstombs' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: wctomb, Prev: wcstombs, Up: Stdlib
|
||
|
||
2.47 `wctomb'--minimal wide char to multibyte converter
|
||
=======================================================
|
||
|
||
*Synopsis*
|
||
#include <stdlib.h>
|
||
int wctomb(char *S, wchar_t WCHAR);
|
||
*Description*
|
||
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 `*S' unless S is a null pointer or
|
||
_MB_CAPABLE is defined and WCHAR is invalid.
|
||
|
||
*Returns*
|
||
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.
|
||
|
||
*Portability*
|
||
`wctomb' is required in the ANSI C standard. However, the precise
|
||
effects vary with the locale.
|
||
|
||
`wctomb' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: Ctype, Next: Stdio, Prev: Stdlib, Up: Top
|
||
|
||
3 Character Type Macros and Functions (`ctype.h')
|
||
*************************************************
|
||
|
||
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.
|
||
|
||
* Menu:
|
||
|
||
* isalnum:: Alphanumeric character predicate
|
||
* isalpha:: Alphabetic character predicate
|
||
* isascii:: ASCII character predicate
|
||
* iscntrl:: Control character predicate
|
||
* isdigit:: Decimal digit predicate
|
||
* islower:: Lowercase character predicate
|
||
* isprint:: Printable character predicates (isprint, isgraph)
|
||
* ispunct:: Punctuation character predicate
|
||
* isspace:: Whitespace character predicate
|
||
* isupper:: Uppercase character predicate
|
||
* isxdigit:: Hexadecimal digit predicate
|
||
* toascii:: Force integers to ASCII range
|
||
* tolower:: Translate characters to lowercase
|
||
* toupper:: Translate characters to uppercase
|
||
* iswalnum:: Alphanumeric wide character predicate
|
||
* iswalpha:: Alphabetic wide character predicate
|
||
* iswblank:: Blank wide character predicate
|
||
* iswcntrl:: Control wide character predicate
|
||
* iswdigit:: Decimal digit wide character predicate
|
||
* iswgraph:: Graphic wide character predicate
|
||
* iswlower:: Lowercase wide character predicate
|
||
* iswprint:: Printable wide character predicate
|
||
* iswpunct:: Punctuation wide character predicate
|
||
* iswspace:: Whitespace wide character predicate
|
||
* iswupper:: Uppercase wide character predicate
|
||
* iswxdigit:: Hexadecimal digit wide character predicate
|
||
* iswctype:: Extensible wide-character test
|
||
* wctype:: Compute wide-character test type
|
||
* towlower:: Translate wide characters to lowercase
|
||
* towupper:: Translate wide characters to uppercase
|
||
* towctrans:: Extensible wide-character translation
|
||
* wctrans:: Compute wide-character translation type
|
||
|
||
|
||
File: libc.info, Node: isalnum, Next: isalpha, Up: Ctype
|
||
|
||
3.1 `isalnum'--alphanumeric character predicate
|
||
===============================================
|
||
|
||
*Synopsis*
|
||
#include <ctype.h>
|
||
int isalnum(int C);
|
||
*Description*
|
||
`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 for all
|
||
integer values.
|
||
|
||
You can use a compiled subroutine instead of the macro definition by
|
||
undefining the macro using ``#undef isalnum''.
|
||
|
||
*Returns*
|
||
`isalnum' returns non-zero if C is a letter (`a'-`z' or `A'-`Z') or a
|
||
digit (`0'-`9').
|
||
|
||
*Portability*
|
||
`isalnum' is ANSI C.
|
||
|
||
No OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: isalpha, Next: isascii, Prev: isalnum, Up: Ctype
|
||
|
||
3.2 `isalpha'--alphabetic character predicate
|
||
=============================================
|
||
|
||
*Synopsis*
|
||
#include <ctype.h>
|
||
int isalpha(int C);
|
||
*Description*
|
||
`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 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 isalpha''.
|
||
|
||
*Returns*
|
||
`isalpha' returns non-zero if C is a letter (`A'-`Z' or `a'-`z').
|
||
|
||
*Portability*
|
||
`isalpha' is ANSI C.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: isascii, Next: iscntrl, Prev: isalpha, Up: Ctype
|
||
|
||
3.3 `isascii'--ASCII character predicate
|
||
========================================
|
||
|
||
*Synopsis*
|
||
#include <ctype.h>
|
||
int isascii(int C);
|
||
*Description*
|
||
`isascii' is a macro which returns non-zero when C is an ASCII
|
||
character, and 0 otherwise. It is defined for all integer values.
|
||
|
||
You can use a compiled subroutine instead of the macro definition by
|
||
undefining the macro using ``#undef isascii''.
|
||
|
||
*Returns*
|
||
`isascii' returns non-zero if the low order byte of C is in the range 0
|
||
to 127 (`0x00'-`0x7F').
|
||
|
||
*Portability*
|
||
`isascii' is ANSI C.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: iscntrl, Next: isdigit, Prev: isascii, Up: Ctype
|
||
|
||
3.4 `iscntrl'--control character predicate
|
||
==========================================
|
||
|
||
*Synopsis*
|
||
#include <ctype.h>
|
||
int iscntrl(int C);
|
||
*Description*
|
||
`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 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 iscntrl''.
|
||
|
||
*Returns*
|
||
`iscntrl' returns non-zero if C is a delete character or ordinary
|
||
control character (`0x7F' or `0x00'-`0x1F').
|
||
|
||
*Portability*
|
||
`iscntrl' is ANSI C.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: isdigit, Next: islower, Prev: iscntrl, Up: Ctype
|
||
|
||
3.5 `isdigit'--decimal digit predicate
|
||
======================================
|
||
|
||
*Synopsis*
|
||
#include <ctype.h>
|
||
int isdigit(int C);
|
||
*Description*
|
||
`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 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 isdigit''.
|
||
|
||
*Returns*
|
||
`isdigit' returns non-zero if C is a decimal digit (`0'-`9').
|
||
|
||
*Portability*
|
||
`isdigit' is ANSI C.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: islower, Next: isprint, Prev: isdigit, Up: Ctype
|
||
|
||
3.6 `islower'--lowercase character predicate
|
||
============================================
|
||
|
||
*Synopsis*
|
||
#include <ctype.h>
|
||
int islower(int C);
|
||
*Description*
|
||
`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
|
||
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 islower''.
|
||
|
||
*Returns*
|
||
`islower' returns non-zero if C is a lowercase letter (`a'-`z').
|
||
|
||
*Portability*
|
||
`islower' is ANSI C.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: isprint, Next: ispunct, Prev: islower, Up: Ctype
|
||
|
||
3.7 `isprint', `isgraph'--printable character predicates
|
||
========================================================
|
||
|
||
*Synopsis*
|
||
#include <ctype.h>
|
||
int isprint(int C);
|
||
int isgraph(int C);
|
||
*Description*
|
||
`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 when
|
||
`isascii'(C) is true or C is EOF.
|
||
|
||
You can use a compiled subroutine instead of the macro definition by
|
||
undefining either macro using ``#undef isprint'' or ``#undef isgraph''.
|
||
|
||
*Returns*
|
||
`isprint' returns non-zero if C is a printing character,
|
||
(`0x20'-`0x7E'). `isgraph' behaves identically to `isprint', except
|
||
that the space character (`0x20') is excluded.
|
||
|
||
*Portability*
|
||
`isprint' and `isgraph' are ANSI C.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: ispunct, Next: isspace, Prev: isprint, Up: Ctype
|
||
|
||
3.8 `ispunct'--punctuation character predicate
|
||
==============================================
|
||
|
||
*Synopsis*
|
||
#include <ctype.h>
|
||
int ispunct(int C);
|
||
*Description*
|
||
`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 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 ispunct''.
|
||
|
||
*Returns*
|
||
`ispunct' returns non-zero if C is a printable punctuation character
|
||
(`isgraph(C) && !isalnum(C)').
|
||
|
||
*Portability*
|
||
`ispunct' is ANSI C.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: isspace, Next: isupper, Prev: ispunct, Up: Ctype
|
||
|
||
3.9 `isspace'--whitespace character predicate
|
||
=============================================
|
||
|
||
*Synopsis*
|
||
#include <ctype.h>
|
||
int isspace(int C);
|
||
*Description*
|
||
`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''.
|
||
|
||
*Returns*
|
||
`isspace' returns non-zero if C is a space, tab, carriage return, new
|
||
line, vertical tab, or formfeed (`0x09'-`0x0D', `0x20').
|
||
|
||
*Portability*
|
||
`isspace' is ANSI C.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: isupper, Next: isxdigit, Prev: isspace, Up: Ctype
|
||
|
||
3.10 `isupper'--uppercase character predicate
|
||
=============================================
|
||
|
||
*Synopsis*
|
||
#include <ctype.h>
|
||
int isupper(int C);
|
||
*Description*
|
||
`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''.
|
||
|
||
*Returns*
|
||
`isupper' returns non-zero if C is a uppercase letter (A-Z).
|
||
|
||
*Portability*
|
||
`isupper' is ANSI C.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: isxdigit, Next: toascii, Prev: isupper, Up: Ctype
|
||
|
||
3.11 `isxdigit'--hexadecimal digit predicate
|
||
============================================
|
||
|
||
*Synopsis*
|
||
#include <ctype.h>
|
||
int isxdigit(int C);
|
||
*Description*
|
||
`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 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 isxdigit''.
|
||
|
||
*Returns*
|
||
`isxdigit' returns non-zero if C is a hexadecimal digit (`0'-`9',
|
||
`a'-`f', or `A'-`F').
|
||
|
||
*Portability*
|
||
`isxdigit' is ANSI C.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: toascii, Next: tolower, Prev: isxdigit, Up: Ctype
|
||
|
||
3.12 `toascii'--force integers to ASCII range
|
||
=============================================
|
||
|
||
*Synopsis*
|
||
#include <ctype.h>
|
||
int toascii(int C);
|
||
*Description*
|
||
`toascii' is a macro which coerces integers to the ASCII range (0-127)
|
||
by zeroing any higher-order bits.
|
||
|
||
You can use a compiled subroutine instead of the macro definition by
|
||
undefining this macro using ``#undef toascii''.
|
||
|
||
*Returns*
|
||
`toascii' returns integers between 0 and 127.
|
||
|
||
*Portability*
|
||
`toascii' is not ANSI C.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: tolower, Next: toupper, Prev: toascii, Up: Ctype
|
||
|
||
3.13 `tolower'--translate characters to lowercase
|
||
=================================================
|
||
|
||
*Synopsis*
|
||
#include <ctype.h>
|
||
int tolower(int C);
|
||
int _tolower(int C);
|
||
*Description*
|
||
`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').
|
||
|
||
*Returns*
|
||
`tolower' returns the lowercase equivalent of C when it is a character
|
||
between `A' and `Z', and C otherwise.
|
||
|
||
`_tolower' returns the lowercase equivalent of C when it is a
|
||
character between `A' and `Z'. If C is not one of these characters,
|
||
the behaviour of `_tolower' is undefined.
|
||
|
||
*Portability*
|
||
`tolower' is ANSI C. `_tolower' is not recommended for portable
|
||
programs.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: toupper, Next: iswalnum, Prev: tolower, Up: Ctype
|
||
|
||
3.14 `toupper'--translate characters to uppercase
|
||
=================================================
|
||
|
||
*Synopsis*
|
||
#include <ctype.h>
|
||
int toupper(int C);
|
||
int _toupper(int C);
|
||
*Description*
|
||
`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').
|
||
|
||
*Returns*
|
||
`toupper' returns the uppercase equivalent of C when it is a character
|
||
between `a' and `z', and C otherwise.
|
||
|
||
`_toupper' returns the uppercase equivalent of C when it is a
|
||
character between `a' and `z'. If C is not one of these characters,
|
||
the behaviour of `_toupper' is undefined.
|
||
|
||
*Portability*
|
||
`toupper' is ANSI C. `_toupper' is not recommended for portable
|
||
programs.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: iswalnum, Next: iswalpha, Prev: toupper, Up: Ctype
|
||
|
||
3.15 `iswalnum'--alphanumeric wide character test
|
||
=================================================
|
||
|
||
*Synopsis*
|
||
#include <wctype.h>
|
||
int iswalnum(wint_t C);
|
||
*Description*
|
||
`iswalnum' is a function which classifies wide-character values that
|
||
are alphanumeric.
|
||
|
||
*Returns*
|
||
`iswalnum' returns non-zero if C is a alphanumeric wide character.
|
||
|
||
*Portability*
|
||
`iswalnum' is C99.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: iswalpha, Next: iswblank, Prev: iswalnum, Up: Ctype
|
||
|
||
3.16 `iswalpha'--alphabetic wide character test
|
||
===============================================
|
||
|
||
*Synopsis*
|
||
#include <wctype.h>
|
||
int iswalpha(wint_t C);
|
||
*Description*
|
||
`iswalpha' is a function which classifies wide-character values that
|
||
are alphabetic.
|
||
|
||
*Returns*
|
||
`iswalpha' returns non-zero if C is an alphabetic wide character.
|
||
|
||
*Portability*
|
||
`iswalpha' is C99.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: iswcntrl, Next: iswdigit, Prev: iswblank, Up: Ctype
|
||
|
||
3.17 `iswcntrl'--control wide character test
|
||
============================================
|
||
|
||
*Synopsis*
|
||
#include <wctype.h>
|
||
int iswcntrl(wint_t C);
|
||
*Description*
|
||
`iswcntrl' is a function which classifies wide-character values that
|
||
are categorized as control characters.
|
||
|
||
*Returns*
|
||
`iswcntrl' returns non-zero if C is a control wide character.
|
||
|
||
*Portability*
|
||
`iswcntrl' is C99.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: iswblank, Next: iswcntrl, Prev: iswalpha, Up: Ctype
|
||
|
||
3.18 `iswblank'--blank wide character test
|
||
==========================================
|
||
|
||
*Synopsis*
|
||
#include <wctype.h>
|
||
int iswblank(wint_t C);
|
||
*Description*
|
||
`iswblank' is a function which classifies wide-character values that
|
||
are categorized as blank.
|
||
|
||
*Returns*
|
||
`iswblank' returns non-zero if C is a blank wide character.
|
||
|
||
*Portability*
|
||
`iswblank' is C99.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: iswdigit, Next: iswgraph, Prev: iswcntrl, Up: Ctype
|
||
|
||
3.19 `iswdigit'--decimal digit wide character test
|
||
==================================================
|
||
|
||
*Synopsis*
|
||
#include <wctype.h>
|
||
int iswdigit(wint_t C);
|
||
*Description*
|
||
`iswdigit' is a function which classifies wide-character values that
|
||
are decimal digits.
|
||
|
||
*Returns*
|
||
`iswdigit' returns non-zero if C is a decimal digit wide character.
|
||
|
||
*Portability*
|
||
`iswdigit' is C99.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: iswgraph, Next: iswlower, Prev: iswdigit, Up: Ctype
|
||
|
||
3.20 `iswgraph'--graphic wide character test
|
||
============================================
|
||
|
||
*Synopsis*
|
||
#include <wctype.h>
|
||
int iswgraph(wint_t C);
|
||
*Description*
|
||
`iswgraph' is a function which classifies wide-character values that
|
||
are graphic.
|
||
|
||
*Returns*
|
||
`iswgraph' returns non-zero if C is a graphic wide character.
|
||
|
||
*Portability*
|
||
`iswgraph' is C99.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: iswlower, Next: iswprint, Prev: iswgraph, Up: Ctype
|
||
|
||
3.21 `iswlower'--lowercase wide character test
|
||
==============================================
|
||
|
||
*Synopsis*
|
||
#include <wctype.h>
|
||
int iswlower(wint_t C);
|
||
*Description*
|
||
`iswlower' is a function which classifies wide-character values that
|
||
have uppercase translations.
|
||
|
||
*Returns*
|
||
`iswlower' returns non-zero if C is a lowercase wide character.
|
||
|
||
*Portability*
|
||
`iswlower' is C99.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: iswprint, Next: iswpunct, Prev: iswlower, Up: Ctype
|
||
|
||
3.22 `iswprint'--printable wide character test
|
||
==============================================
|
||
|
||
*Synopsis*
|
||
#include <wctype.h>
|
||
int iswprint(wint_t C);
|
||
*Description*
|
||
`iswprint' is a function which classifies wide-character values that
|
||
are printable.
|
||
|
||
*Returns*
|
||
`iswprint' returns non-zero if C is a printable wide character.
|
||
|
||
*Portability*
|
||
`iswprint' is C99.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: iswpunct, Next: iswspace, Prev: iswprint, Up: Ctype
|
||
|
||
3.23 `iswpunct'--punctuation wide character test
|
||
================================================
|
||
|
||
*Synopsis*
|
||
#include <wctype.h>
|
||
int iswpunct(wint_t C);
|
||
*Description*
|
||
`iswpunct' is a function which classifies wide-character values that
|
||
are punctuation.
|
||
|
||
*Returns*
|
||
`iswpunct' returns non-zero if C is a punctuation wide character.
|
||
|
||
*Portability*
|
||
`iswpunct' is C99.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: iswspace, Next: iswupper, Prev: iswpunct, Up: Ctype
|
||
|
||
3.24 `iswspace'--whitespace wide character test
|
||
===============================================
|
||
|
||
*Synopsis*
|
||
#include <wctype.h>
|
||
int iswspace(wint_t C);
|
||
*Description*
|
||
`iswspace' is a function which classifies wide-character values that
|
||
are categorized as whitespace.
|
||
|
||
*Returns*
|
||
`iswspace' returns non-zero if C is a whitespace wide character.
|
||
|
||
*Portability*
|
||
`iswspace' is C99.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: iswupper, Next: iswxdigit, Prev: iswspace, Up: Ctype
|
||
|
||
3.25 `iswupper'--uppercase wide character test
|
||
==============================================
|
||
|
||
*Synopsis*
|
||
#include <wctype.h>
|
||
int iswupper(wint_t C);
|
||
*Description*
|
||
`iswupper' is a function which classifies wide-character values that
|
||
have uppercase translations.
|
||
|
||
*Returns*
|
||
`iswupper' returns non-zero if C is a uppercase wide character.
|
||
|
||
*Portability*
|
||
`iswupper' is C99.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: iswxdigit, Next: iswctype, Prev: iswupper, Up: Ctype
|
||
|
||
3.26 `iswxdigit'--hexadecimal digit wide character test
|
||
=======================================================
|
||
|
||
*Synopsis*
|
||
#include <wctype.h>
|
||
int iswxdigit(wint_t C);
|
||
*Description*
|
||
`iswxdigit' is a function which classifies wide character values that
|
||
are hexadecimal digits.
|
||
|
||
*Returns*
|
||
`iswxdigit' returns non-zero if C is a hexadecimal digit wide character.
|
||
|
||
*Portability*
|
||
`iswxdigit' is C99.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: iswctype, Next: wctype, Prev: iswxdigit, Up: Ctype
|
||
|
||
3.27 `iswctype'--extensible wide-character test
|
||
===============================================
|
||
|
||
*Synopsis*
|
||
#include <wctype.h>
|
||
int iswctype(wint_t C, wctype_t DESC);
|
||
*Description*
|
||
`iswctype' is a function which classifies wide-character values using
|
||
the wide-character test specified by DESC.
|
||
|
||
*Returns*
|
||
`iswctype' returns non-zero if and only if C matches the test specified
|
||
by DESC. If DESC is unknown, zero is returned.
|
||
|
||
*Portability*
|
||
`iswctype' is C99.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: wctype, Next: towlower, Prev: iswctype, Up: Ctype
|
||
|
||
3.28 `wctype'--get wide-character classification type
|
||
=====================================================
|
||
|
||
*Synopsis*
|
||
#include <wctype.h>
|
||
wctype_t wctype(const char *C);
|
||
*Description*
|
||
`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".
|
||
|
||
*Returns*
|
||
`wctype' returns 0 and sets `errno' to `EINVAL' if the given name is
|
||
invalid. Otherwise, it returns a valid non-zero wctype_t value.
|
||
|
||
*Portability*
|
||
`wctype' is C99.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: towlower, Next: towupper, Prev: wctype, Up: Ctype
|
||
|
||
3.29 `towlower'--translate wide characters to lowercase
|
||
=======================================================
|
||
|
||
*Synopsis*
|
||
#include <wctype.h>
|
||
wint_t towlower(wint_t C);
|
||
*Description*
|
||
`towlower' is a function which converts uppercase wide characters to
|
||
lowercase, leaving all other characters unchanged.
|
||
|
||
*Returns*
|
||
`towlower' returns the lowercase equivalent of C when it is a uppercase
|
||
wide character; otherwise, it returns the input character.
|
||
|
||
*Portability*
|
||
`towlower' is C99.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: towupper, Next: towctrans, Prev: towlower, Up: Ctype
|
||
|
||
3.30 `towupper'--translate wide characters to uppercase
|
||
=======================================================
|
||
|
||
*Synopsis*
|
||
#include <wctype.h>
|
||
wint_t towupper(wint_t C);
|
||
*Description*
|
||
`towupper' is a function which converts lowercase wide characters to
|
||
uppercase, leaving all other characters unchanged.
|
||
|
||
*Returns*
|
||
`towupper' returns the uppercase equivalent of C when it is a lowercase
|
||
wide character, otherwise, it returns the input character.
|
||
|
||
*Portability*
|
||
`towupper' is C99.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: towctrans, Next: wctrans, Prev: towupper, Up: Ctype
|
||
|
||
3.31 `towctrans'--extensible wide-character translation
|
||
=======================================================
|
||
|
||
*Synopsis*
|
||
#include <wctype.h>
|
||
wint_t towctrans(wint_t C, wctrans_t W);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
`towctrans' returns the translated equivalent of C when it is a valid
|
||
for the given translation, otherwise, it returns the input character.
|
||
When the translation type is invalid, `errno' is set `EINVAL'.
|
||
|
||
*Portability*
|
||
`towctrans' is C99.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: wctrans, Prev: towctrans, Up: Ctype
|
||
|
||
3.32 `wctrans'--get wide-character translation type
|
||
===================================================
|
||
|
||
*Synopsis*
|
||
#include <wctype.h>
|
||
wctrans_t wctrans(const char *C);
|
||
*Description*
|
||
`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".
|
||
|
||
*Returns*
|
||
`wctrans' returns 0 and sets `errno' to `EINVAL' if the given name is
|
||
invalid. Otherwise, it returns a valid non-zero wctrans_t value.
|
||
|
||
*Portability*
|
||
`wctrans' is C99.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: Stdio, Next: Strings, Prev: Ctype, Up: Top
|
||
|
||
4 Input and Output (`stdio.h')
|
||
******************************
|
||
|
||
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.
|
||
|
||
* Menu:
|
||
|
||
* clearerr:: Clear file or stream error indicator
|
||
* diprintf:: Print to a file descriptor (integer only)
|
||
* dprintf:: Print to a file descriptor
|
||
* fclose:: Close a file
|
||
* fcloseall:: Close all files
|
||
* fdopen:: Turn an open file into a stream
|
||
* feof:: Test for end of file
|
||
* ferror:: Test whether read/write error has occurred
|
||
* fflush:: Flush buffered file output
|
||
* fgetc:: Get a character from a file or stream
|
||
* fgetpos:: Record position in a stream or file
|
||
* fgets:: Get character string from a file or stream
|
||
* fgetwc:: Get a wide character from a file or stream
|
||
* fgetws:: Get a wide character string from a file or stream
|
||
* fileno:: Get file descriptor associated with stream
|
||
* fmemopen:: Open a stream around a fixed-length buffer
|
||
* fopen:: Open a file
|
||
* fopencookie:: Open a stream with custom callbacks
|
||
* fpurge:: Discard all pending I/O on a stream
|
||
* fputc:: Write a character on a stream or file
|
||
* fputs:: Write a character string in a file or stream
|
||
* fputwc:: Write a wide character to a file or stream
|
||
* fputws:: Write a wide character string to a file or stream
|
||
* fread:: Read array elements from a file
|
||
* freopen:: Open a file using an existing file descriptor
|
||
* fseek:: Set file position
|
||
* fsetpos:: Restore position of a stream or file
|
||
* ftell:: Return position in a stream or file
|
||
* funopen:: Open a stream with custom callbacks
|
||
* fwide:: Set and determine the orientation of a FILE stream
|
||
* fwrite:: Write array elements from memory to a file or stream
|
||
* getc:: Get a character from a file or stream (macro)
|
||
* getc_unlocked:: Get a character from a file or stream (macro)
|
||
* getchar:: Get a character from standard input (macro)
|
||
* getchar_unlocked:: Get a character from standard input (macro)
|
||
* getdelim:: Get character string from a file or stream
|
||
* getline:: Get character string from a file or stream
|
||
* gets:: Get character string from standard input (obsolete)
|
||
* getw:: Get a word (int) from a file or stream
|
||
* getwchar:: Get a wide character from standard input
|
||
* mktemp:: Generate unused file name
|
||
* open_memstream:: Open a write stream around an arbitrary-length buffer
|
||
* perror:: Print an error message on standard error
|
||
* putc:: Write a character on a stream or file (macro)
|
||
* putc_unlocked:: Write a character on a stream or file (macro)
|
||
* putchar:: Write a character on standard output (macro)
|
||
* putchar_unlocked:: Write a character on standard output (macro)
|
||
* puts:: Write a character string on standard output
|
||
* putw:: Write a word (int) to a file or stream
|
||
* putwchar:: Write a wide character to standard output
|
||
* remove:: Delete a file's name
|
||
* rename:: Rename a file
|
||
* rewind:: Reinitialize a file or stream
|
||
* setbuf:: Specify full buffering for a file or stream
|
||
* setbuffer:: Specify full buffering for a file or stream with size
|
||
* setlinebuf:: Specify line buffering for a file or stream
|
||
* setvbuf:: Specify buffering for a file or stream
|
||
* siprintf:: Write formatted output (integer only)
|
||
* siscanf:: Scan and format input (integer only)
|
||
* sprintf:: Write formatted output
|
||
* sscanf:: Scan and format input
|
||
* swprintf:: Write formatted wide character output
|
||
* swscanf:: Scan and format wide character input
|
||
* tmpfile:: Create a temporary file
|
||
* tmpnam:: Generate name for a temporary file
|
||
* ungetc:: Push data back into a stream
|
||
* ungetwc:: Push wide character data back into a stream
|
||
* vfprintf:: Format variable argument list
|
||
* vfscanf:: Scan variable argument list
|
||
* vfwprintf:: Format variable wide character argument list
|
||
* vfwscanf:: Scan and format argument list from wide character input
|
||
* viprintf:: Format variable argument list (integer only)
|
||
* viscanf:: Scan variable format list (integer only)
|
||
|
||
|
||
File: libc.info, Node: clearerr, Next: diprintf, Up: Stdio
|
||
|
||
4.1 `clearerr'--clear file or stream error indicator
|
||
====================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
void clearerr(FILE *FP);
|
||
*Description*
|
||
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.
|
||
|
||
*Returns*
|
||
`clearerr' does not return a result.
|
||
|
||
*Portability*
|
||
ANSI C requires `clearerr'.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: diprintf, Next: dprintf, Prev: clearerr, Up: Stdio
|
||
|
||
4.2 `diprintf', `vdiprintf'--print to a file descriptor (integer only)
|
||
======================================================================
|
||
|
||
*Synopsis*
|
||
#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);
|
||
*Description*
|
||
`diprintf' and `vdiprintf' are similar to `dprintf' and `vdprintf',
|
||
except that only integer format specifiers are processed.
|
||
|
||
The functions `_diprintf_r' and `_vdiprintf_r' are simply reentrant
|
||
versions of the functions above.
|
||
|
||
*Returns*
|
||
Similar to `dprintf' and `vdprintf'.
|
||
|
||
*Portability*
|
||
This set of functions is an integer-only extension, and is not portable.
|
||
|
||
Supporting OS subroutines required: `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: dprintf, Next: fclose, Prev: diprintf, Up: Stdio
|
||
|
||
4.3 `dprintf', `vdprintf'--print to a file descriptor
|
||
=====================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
#include <stdarg.h>
|
||
int dprintf(int FD, const char *FORMAT, ...);
|
||
int vdprintf(int FD, const char *FORMAT, va_list AP);
|
||
int _dprintf_r(struct _reent *PTR, int FD,
|
||
const char *FORMAT, ...);
|
||
int _vdprintf_r(struct _reent *PTR, int FD,
|
||
const char *FORMAT, va_list AP);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
The return value and errors are exactly as for `write', except that
|
||
`errno' may also be set to `ENOMEM' if the heap is exhausted.
|
||
|
||
*Portability*
|
||
This function is originally a GNU extension in glibc and is not
|
||
portable.
|
||
|
||
Supporting OS subroutines required: `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: fclose, Next: fcloseall, Prev: dprintf, Up: Stdio
|
||
|
||
4.4 `fclose'--close a file
|
||
==========================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int fclose(FILE *FP);
|
||
int _fclose_r(struct _reent *REENT, FILE *FP);
|
||
*Description*
|
||
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.
|
||
|
||
*Returns*
|
||
`fclose' returns `0' if successful (including when FP is `NULL' or not
|
||
an open file); otherwise, it returns `EOF'.
|
||
|
||
*Portability*
|
||
`fclose' is required by ANSI C.
|
||
|
||
Required OS subroutines: `close', `fstat', `isatty', `lseek',
|
||
`read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: fcloseall, Next: fdopen, Prev: fclose, Up: Stdio
|
||
|
||
4.5 `fcloseall'--close all files
|
||
================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int fcloseall(void);
|
||
int _fcloseall_r (struct _reent *PTR);
|
||
*Description*
|
||
`fcloseall' closes all files in the current reentrancy struct's domain.
|
||
The function `_fcloseall_r' is the same function, except the reentrancy
|
||
struct is passed in as the PTR argument.
|
||
|
||
This function is not recommended as it closes all streams, including
|
||
the std streams.
|
||
|
||
*Returns*
|
||
`fclose' returns `0' if all closes are successful. Otherwise, EOF is
|
||
returned.
|
||
|
||
*Portability*
|
||
`fcloseall' is a glibc extension.
|
||
|
||
Required OS subroutines: `close', `fstat', `isatty', `lseek',
|
||
`read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: fdopen, Next: feof, Prev: fcloseall, Up: Stdio
|
||
|
||
4.6 `fdopen'--turn open file into a stream
|
||
==========================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
FILE *fdopen(int FD, const char *MODE);
|
||
FILE *_fdopen_r(struct _reent *REENT,
|
||
int FD, const char *MODE);
|
||
*Description*
|
||
`fdopen' produces a file descriptor of type `FILE *', from a descriptor
|
||
for an already-open file (returned, for example, by the system
|
||
subroutine `open' rather than by `fopen'). The MODE argument has the
|
||
same meanings as in `fopen'.
|
||
|
||
*Returns*
|
||
File pointer or `NULL', as for `fopen'.
|
||
|
||
*Portability*
|
||
`fdopen' is ANSI.
|
||
|
||
|
||
File: libc.info, Node: feof, Next: ferror, Prev: fdopen, Up: Stdio
|
||
|
||
4.7 `feof'--test for end of file
|
||
================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int feof(FILE *FP);
|
||
*Description*
|
||
`feof' tests whether or not the end of the file identified by FP has
|
||
been reached.
|
||
|
||
*Returns*
|
||
`feof' returns `0' if the end of file has not yet been reached; if at
|
||
end of file, the result is nonzero.
|
||
|
||
*Portability*
|
||
`feof' is required by ANSI C.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: ferror, Next: fflush, Prev: feof, Up: Stdio
|
||
|
||
4.8 `ferror'--test whether read/write error has occurred
|
||
========================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int ferror(FILE *FP);
|
||
*Description*
|
||
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.
|
||
|
||
*Returns*
|
||
`ferror' returns `0' if no errors have occurred; it returns a nonzero
|
||
value otherwise.
|
||
|
||
*Portability*
|
||
ANSI C requires `ferror'.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: fflush, Next: fgetc, Prev: ferror, Up: Stdio
|
||
|
||
4.9 `fflush'--flush buffered file output
|
||
========================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int fflush(FILE *FP);
|
||
|
||
int _fflush_r(struct _reent *REENT, FILE *FP);
|
||
*Description*
|
||
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.
|
||
|
||
The alternate function `_fflush_r' is a reentrant version, where the
|
||
extra argument REENT is a pointer to a reentrancy structure, and FP
|
||
must not be NULL.
|
||
|
||
*Returns*
|
||
`fflush' returns `0' unless it encounters a write error; in that
|
||
situation, it returns `EOF'.
|
||
|
||
*Portability*
|
||
ANSI C requires `fflush'. The behavior on input streams is only
|
||
specified by POSIX, and not all implementations follow POSIX rules.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: fgetc, Next: fgetpos, Prev: fflush, Up: Stdio
|
||
|
||
4.10 `fgetc'--get a character from a file or stream
|
||
===================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int fgetc(FILE *FP);
|
||
|
||
#include <stdio.h>
|
||
int _fgetc_r(struct _reent *PTR, FILE *FP);
|
||
*Description*
|
||
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'.
|
||
|
||
The function `_fgetc_r' is simply a reentrant version of `fgetc'
|
||
that is passed the additional reentrant structure pointer argument: PTR.
|
||
|
||
*Returns*
|
||
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, `fgetc' returns `EOF'.
|
||
|
||
You can distinguish the two situations that cause an `EOF' result by
|
||
using the `ferror' and `feof' functions.
|
||
|
||
*Portability*
|
||
ANSI C requires `fgetc'.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: fgetpos, Next: fgets, Prev: fgetc, Up: Stdio
|
||
|
||
4.11 `fgetpos'--record position in a stream or file
|
||
===================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int fgetpos(FILE *FP, fpos_t *POS);
|
||
int _fgetpos_r(struct _reent *PTR, FILE *FP, fpos_t *POS);
|
||
*Description*
|
||
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 `*POS'. Later, you can use this value with `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'.
|
||
|
||
*Returns*
|
||
`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'.
|
||
|
||
*Portability*
|
||
`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.
|
||
|
||
|
||
File: libc.info, Node: fgets, Next: fgetwc, Prev: fgetpos, Up: Stdio
|
||
|
||
4.12 `fgets'--get character string from a file or stream
|
||
========================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
char *fgets(char *BUF, int N, FILE *FP);
|
||
|
||
#include <stdio.h>
|
||
char *_fgets_r(struct _reent *PTR, char *BUF, int N, FILE *FP);
|
||
*Description*
|
||
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.
|
||
|
||
The `_fgets_r' function is simply the reentrant version of `fgets'
|
||
and is passed an additional reentrancy structure pointer: PTR.
|
||
|
||
*Returns*
|
||
`fgets' 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 no data are read, NULL is
|
||
returned instead.
|
||
|
||
*Portability*
|
||
`fgets' should replace all uses of `gets'. Note however that `fgets'
|
||
returns all of the data, while `gets' removes the trailing newline
|
||
(with no indication that it has done so.)
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: fgetwc, Next: fgetws, Prev: fgets, Up: Stdio
|
||
|
||
4.13 `fgetwc', `getwc'--get a wide character from a file or stream
|
||
==================================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
#include <wchar.h>
|
||
wint_t fgetwc(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 getwc(FILE *FP);
|
||
|
||
#include <stdio.h>
|
||
#include <wchar.h>
|
||
wint_t _getwc_r(struct _reent *PTR, FILE *FP);
|
||
*Description*
|
||
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.
|
||
|
||
The `getwc' function or macro functions identically to `fgetwc'.
|
||
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' and `_getwc_r' are simply reentrant versions of `fgetwc'
|
||
and `getwc' that are passed the additional reentrant structure pointer
|
||
argument: PTR.
|
||
|
||
*Returns*
|
||
The next wide character cast to `wint_t'), unless there is no more data,
|
||
or the host system reports a read error; in either of these situations,
|
||
`fgetwc' and `getwc' return `WEOF'.
|
||
|
||
You can distinguish the two situations that cause an `EOF' result by
|
||
using the `ferror' and `feof' functions.
|
||
|
||
*Portability*
|
||
C99, POSIX.1-2001
|
||
|
||
|
||
File: libc.info, Node: fgetws, Next: fileno, Prev: fgetwc, Up: Stdio
|
||
|
||
4.14 `fgetws'--get wide character string from a file or stream
|
||
==============================================================
|
||
|
||
*Synopsis*
|
||
#include <wchar.h>
|
||
wchar_t *fgetws(wchar_t *WS, int N, FILE *FP);
|
||
|
||
#include <wchar.h>
|
||
wchar_t *_fgetws_r(struct _reent *PTR, wchar_t *WS, int N, FILE *FP);
|
||
*Description*
|
||
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.
|
||
|
||
The `_fgetws_r' function is simply the reentrant version of `fgetws'
|
||
and is passed an additional reentrancy structure pointer: PTR.
|
||
|
||
*Returns*
|
||
`fgetws' 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 no data are read, NULL is
|
||
returned instead.
|
||
|
||
*Portability*
|
||
C99, POSIX.1-2001
|
||
|
||
|
||
File: libc.info, Node: fileno, Next: fmemopen, Prev: fgetws, Up: Stdio
|
||
|
||
4.15 `fileno'--return file descriptor associated with stream
|
||
============================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int fileno(FILE *FP);
|
||
*Description*
|
||
You can use `fileno' to return the file descriptor identified by FP.
|
||
|
||
*Returns*
|
||
`fileno' returns a non-negative integer when successful. If FP is not
|
||
an open stream, `fileno' returns -1.
|
||
|
||
*Portability*
|
||
`fileno' is not part of ANSI C. POSIX requires `fileno'.
|
||
|
||
Supporting OS subroutines required: none.
|
||
|
||
|
||
File: libc.info, Node: fmemopen, Next: fopen, Prev: fileno, Up: Stdio
|
||
|
||
4.16 `fmemopen'--open a stream around a fixed-length string
|
||
===========================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
FILE *fmemopen(void *restrict BUF, size_t SIZE,
|
||
const char *restrict MODE);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
The return value is an open FILE pointer on success. On error, `NULL'
|
||
is returned, and `errno' will be set to EINVAL if SIZE is zero or MODE
|
||
is invalid, ENOMEM if BUF was NULL and memory could not be allocated,
|
||
or EMFILE if too many streams are already open.
|
||
|
||
*Portability*
|
||
This function is being added to POSIX 200x, but is not in POSIX 2001.
|
||
|
||
Supporting OS subroutines required: `sbrk'.
|
||
|
||
|
||
File: libc.info, Node: fopen, Next: fopencookie, Prev: fmemopen, Up: Stdio
|
||
|
||
4.17 `fopen'--open a file
|
||
=========================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
FILE *fopen(const char *FILE, const char *MODE);
|
||
|
||
FILE *_fopen_r(struct _reent *REENT,
|
||
const char *FILE, const char *MODE);
|
||
*Description*
|
||
`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. `*MODE' must begin with one of the three characters ``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 `fseek'.
|
||
|
||
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.
|
||
|
||
*Returns*
|
||
`fopen' returns a file pointer which you can use for other file
|
||
operations, unless the file you requested could not be opened; in that
|
||
situation, the result is `NULL'. If the reason for failure was an
|
||
invalid string at MODE, `errno' is set to `EINVAL'.
|
||
|
||
*Portability*
|
||
`fopen' is required by ANSI C.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `open', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: fopencookie, Next: fpurge, Prev: fopen, Up: Stdio
|
||
|
||
4.18 `fopencookie'--open a stream with custom callbacks
|
||
=======================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
FILE *fopencookie(const void *COOKIE, const char *MODE,
|
||
cookie_io_functions_t FUNCTIONS);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
The return value is an open FILE pointer on success. On error, `NULL'
|
||
is returned, and `errno' will be set to EINVAL if a function pointer is
|
||
missing or MODE is invalid, ENOMEM if the stream cannot be created, or
|
||
EMFILE if too many streams are already open.
|
||
|
||
*Portability*
|
||
This function is a newlib extension, copying the prototype from Linux.
|
||
It is not portable. See also the `funopen' interface from BSD.
|
||
|
||
Supporting OS subroutines required: `sbrk'.
|
||
|
||
|
||
File: libc.info, Node: fpurge, Next: fputc, Prev: fopencookie, Up: Stdio
|
||
|
||
4.19 `fpurge'--discard pending file I/O
|
||
=======================================
|
||
|
||
*Synopsis*
|
||
#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);
|
||
*Description*
|
||
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.
|
||
|
||
*Returns*
|
||
`fpurge' returns `0' unless FP is not valid, in which case it returns
|
||
`EOF' and sets `errno'.
|
||
|
||
*Portability*
|
||
These functions are not portable to any standard.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: fputc, Next: fputs, Prev: fpurge, Up: Stdio
|
||
|
||
4.20 `fputc'--write a character on a stream or file
|
||
===================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int fputc(int CH, FILE *FP);
|
||
|
||
#include <stdio.h>
|
||
int _fputc_r(struct _rent *PTR, int CH, FILE *FP);
|
||
*Description*
|
||
`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'.
|
||
|
||
The `_fputc_r' function is simply a reentrant version of `fputc'
|
||
that takes an additional reentrant structure argument: PTR.
|
||
|
||
*Returns*
|
||
If successful, `fputc' returns its argument CH. If an error
|
||
intervenes, the result is `EOF'. You can use ``ferror(FP)'' to query
|
||
for errors.
|
||
|
||
*Portability*
|
||
`fputc' is required by ANSI C.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: fputs, Next: fputwc, Prev: fputc, Up: Stdio
|
||
|
||
4.21 `fputs'--write a character string in a file or stream
|
||
==========================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int fputs(const char *S, FILE *FP);
|
||
|
||
#include <stdio.h>
|
||
int _fputs_r(struct _reent *PTR, const char *S, FILE *FP);
|
||
*Description*
|
||
`fputs' writes the string at S (but without the trailing null) to the
|
||
file or stream identified by FP.
|
||
|
||
`_fputs_r' is simply the reentrant version of `fputs' that takes an
|
||
additional reentrant struct pointer argument: PTR.
|
||
|
||
*Returns*
|
||
If successful, the result is `0'; otherwise, the result is `EOF'.
|
||
|
||
*Portability*
|
||
ANSI C requires `fputs', but does not specify that the result on
|
||
success must be `0'; any non-negative value is permitted.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: fputwc, Next: fputws, Prev: fputs, Up: Stdio
|
||
|
||
4.22 `fputwc', `putwc'--write a wide character on a stream or file
|
||
==================================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
#include <wchar.h>
|
||
wint_t fputwc(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 putwc(wchar_t WC, FILE *FP);
|
||
|
||
#include <stdio.h>
|
||
#include <wchar.h>
|
||
wint_t _putwc_r(struct _reent *PTR, wchar_t WC, FILE *FP);
|
||
*Description*
|
||
`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.
|
||
|
||
The `putwc' function or macro functions identically to `fputwc'. It
|
||
may be implemented as a macro, and may evaluate its argument more than
|
||
once. There is no reason ever to use it.
|
||
|
||
The `_fputwc_r' and `_putwc_r' functions are simply reentrant
|
||
versions of `fputwc' and `putwc' that take an additional reentrant
|
||
structure argument: PTR.
|
||
|
||
*Returns*
|
||
If successful, `fputwc' and `putwc' return their argument WC. If an
|
||
error intervenes, the result is `EOF'. You can use ``ferror(FP)'' to
|
||
query for errors.
|
||
|
||
*Portability*
|
||
C99, POSIX.1-2001
|
||
|
||
|
||
File: libc.info, Node: fputws, Next: fread, Prev: fputwc, Up: Stdio
|
||
|
||
4.23 `fputws'--write a wide character string in a file or stream
|
||
================================================================
|
||
|
||
*Synopsis*
|
||
#include <wchar.h>
|
||
int fputws(const wchar_t *WS, FILE *FP);
|
||
|
||
#include <wchar.h>
|
||
int _fputws_r(struct _reent *PTR, const wchar_t *WS, FILE *FP);
|
||
*Description*
|
||
`fputws' writes the wide character string at WS (but without the
|
||
trailing null) to the file or stream identified by FP.
|
||
|
||
`_fputws_r' is simply the reentrant version of `fputws' that takes
|
||
an additional reentrant struct pointer argument: PTR.
|
||
|
||
*Returns*
|
||
If successful, the result is a non-negative integer; otherwise, the
|
||
result is `-1' to indicate an error.
|
||
|
||
*Portability*
|
||
C99, POSIX.1-2001
|
||
|
||
|
||
File: libc.info, Node: fread, Next: freopen, Prev: fputws, Up: Stdio
|
||
|
||
4.24 `fread'--read array elements from a file
|
||
=============================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
size_t fread(void *BUF, size_t SIZE, size_t COUNT,
|
||
FILE *FP);
|
||
|
||
#include <stdio.h>
|
||
size_t _fread_r(struct _reent *PTR, void *BUF,
|
||
size_t SIZE, size_t COUNT, FILE *FP);
|
||
*Description*
|
||
`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_r' is simply the reentrant version of `fread' that takes an
|
||
additional reentrant structure pointer argument: PTR.
|
||
|
||
*Returns*
|
||
The result of `fread' is the number of elements it succeeded in reading.
|
||
|
||
*Portability*
|
||
ANSI C requires `fread'.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: freopen, Next: fseek, Prev: fread, Up: Stdio
|
||
|
||
4.25 `freopen'--open a file using an existing file descriptor
|
||
=============================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
FILE *freopen(const char *FILE, const char *MODE,
|
||
FILE *FP);
|
||
FILE *_freopen_r(struct _reent *PTR, const char *FILE,
|
||
const char *MODE, FILE *FP);
|
||
*Description*
|
||
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.
|
||
|
||
*Returns*
|
||
If successful, the result is the same as the argument FP. If the file
|
||
cannot be opened as specified, the result is `NULL'.
|
||
|
||
*Portability*
|
||
ANSI C requires `freopen'.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `open', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: fseek, Next: fsetpos, Prev: freopen, Up: Stdio
|
||
|
||
4.26 `fseek', `fseeko'--set file position
|
||
=========================================
|
||
|
||
*Synopsis*
|
||
#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)
|
||
*Description*
|
||
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.
|
||
|
||
*Returns*
|
||
`fseek'/`fseeko' return `0' when successful. On failure, the result is
|
||
`EOF'. The reason for failure is indicated in `errno': either `ESPIPE'
|
||
(the stream identified by FP doesn't support repositioning) or `EINVAL'
|
||
(invalid file position).
|
||
|
||
*Portability*
|
||
ANSI C requires `fseek'.
|
||
|
||
`fseeko' is defined by the Single Unix specification.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: fsetpos, Next: ftell, Prev: fseek, Up: Stdio
|
||
|
||
4.27 `fsetpos'--restore position of a stream or file
|
||
====================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int fsetpos(FILE *FP, const fpos_t *POS);
|
||
int _fsetpos_r(struct _reent *PTR, FILE *FP,
|
||
const fpos_t *POS);
|
||
*Description*
|
||
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 `*POS' (after first recording it with `fgetpos').
|
||
|
||
See `fseek' for a similar facility.
|
||
|
||
*Returns*
|
||
`fgetpos' returns `0' when successful. If `fgetpos' fails, the result
|
||
is `1'. The reason for failure is indicated in `errno': either
|
||
`ESPIPE' (the stream identified by FP doesn't support repositioning) or
|
||
`EINVAL' (invalid file position).
|
||
|
||
*Portability*
|
||
ANSI C requires `fsetpos', but does not specify the nature of `*POS'
|
||
beyond identifying it as written by `fgetpos'.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: ftell, Next: funopen, Prev: fsetpos, Up: Stdio
|
||
|
||
4.28 `ftell', `ftello'--return position in a stream or file
|
||
===========================================================
|
||
|
||
*Synopsis*
|
||
#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);
|
||
*Description*
|
||
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'.
|
||
|
||
*Returns*
|
||
`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'.
|
||
|
||
*Portability*
|
||
`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.
|
||
|
||
|
||
File: libc.info, Node: funopen, Next: fwide, Prev: ftell, Up: Stdio
|
||
|
||
4.29 `funopen', `fropen', `fwopen'--open a stream with custom callbacks
|
||
=======================================================================
|
||
|
||
*Synopsis*
|
||
#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));
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
The return value is an open FILE pointer on success. On error, `NULL'
|
||
is returned, and `errno' will be set to EINVAL if a function pointer is
|
||
missing, ENOMEM if the stream cannot be created, or EMFILE if too many
|
||
streams are already open.
|
||
|
||
*Portability*
|
||
This function is a newlib extension, copying the prototype from BSD.
|
||
It is not portable. See also the `fopencookie' interface from Linux.
|
||
|
||
Supporting OS subroutines required: `sbrk'.
|
||
|
||
|
||
File: libc.info, Node: fwide, Next: fwrite, Prev: funopen, Up: Stdio
|
||
|
||
4.30 `fwide'--set and determine the orientation of a FILE stream
|
||
================================================================
|
||
|
||
*Synopsis*
|
||
#include <wchar.h>
|
||
int fwide(FILE *FP, int MODE)
|
||
|
||
int _fwide_r(struct _reent *PTR, FILE *FP, int MODE)
|
||
*Description*
|
||
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.
|
||
|
||
*Returns*
|
||
The `fwide' function returns FP's orientation, after possibly changing
|
||
it. A return value > 0 means wide-character oriented. A return value <
|
||
0 means byte oriented. A return value of zero means undecided.
|
||
|
||
*Portability*
|
||
C99, POSIX.1-2001.
|
||
|
||
|
||
File: libc.info, Node: fwrite, Next: getc, Prev: fwide, Up: Stdio
|
||
|
||
4.31 `fwrite'--write array elements
|
||
===================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
size_t fwrite(const void *BUF, size_t SIZE,
|
||
size_t COUNT, FILE *FP);
|
||
|
||
#include <stdio.h>
|
||
size_t _fwrite_r(struct _reent *PTR, const void *BUF, size_t SIZE,
|
||
size_t COUNT, FILE *FP);
|
||
*Description*
|
||
`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_r' is simply the reentrant version of `fwrite' that takes
|
||
an additional reentrant structure argument: PTR.
|
||
|
||
*Returns*
|
||
If `fwrite' succeeds in writing all the elements you specify, the
|
||
result is the same as the argument COUNT. In any event, the result is
|
||
the number of complete elements that `fwrite' copied to the file.
|
||
|
||
*Portability*
|
||
ANSI C requires `fwrite'.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: getc, Next: getc_unlocked, Prev: fwrite, Up: Stdio
|
||
|
||
4.32 `getc'--read a character (macro)
|
||
=====================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int getc(FILE *FP);
|
||
|
||
#include <stdio.h>
|
||
int _getc_r(struct _reent *PTR, FILE *FP);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
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.
|
||
|
||
*Portability*
|
||
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'.
|
||
|
||
|
||
File: libc.info, Node: getc_unlocked, Next: getchar, Prev: getc, Up: Stdio
|
||
|
||
4.33 `getc_unlocked'--non-thread-safe version of getc (macro)
|
||
=============================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int getc_unlocked(FILE *FP);
|
||
|
||
#include <stdio.h>
|
||
int _getc_unlocked_r(FILE *FP);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
See `getc'.
|
||
|
||
*Portability*
|
||
POSIX 1003.1 requires `getc_unlocked'. `getc_unlocked' may be
|
||
implemented as a macro, so arguments should not have side-effects.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
File: libc.info, Node: getchar, Next: getchar_unlocked, Prev: getc_unlocked, Up: Stdio
|
||
|
||
4.34 `getchar'--read a character (macro)
|
||
========================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int getchar(void);
|
||
|
||
int _getchar_r(struct _reent *REENT);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
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)''.
|
||
|
||
*Portability*
|
||
ANSI C requires `getchar'; it suggests, but does not require, that
|
||
`getchar' be implemented as a macro.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: getchar_unlocked, Next: getdelim, Prev: getchar, Up: Stdio
|
||
|
||
4.35 `getchar_unlocked'--non-thread-safe version of getchar (macro)
|
||
===================================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int getchar_unlocked();
|
||
|
||
#include <stdio.h>
|
||
int _getchar_unlocked_r(struct _reent *PTR);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
See `getchar'.
|
||
|
||
*Portability*
|
||
POSIX 1003.1 requires `getchar_unlocked'. `getchar_unlocked' may be
|
||
implemented as a macro.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
File: libc.info, Node: getdelim, Next: getline, Prev: getchar_unlocked, Up: Stdio
|
||
|
||
4.36 `getdelim'--read a line up to a specified line delimiter
|
||
=============================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int getdelim(char **BUFPTR, size_t *N,
|
||
int DELIM, FILE *FP);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
`getdelim' returns `-1' if no characters were successfully read;
|
||
otherwise, it returns the number of bytes successfully read. At end of
|
||
file, the result is nonzero.
|
||
|
||
*Portability*
|
||
`getdelim' is a glibc extension.
|
||
|
||
No supporting OS subroutines are directly required.
|
||
|
||
|
||
File: libc.info, Node: getline, Next: gets, Prev: getdelim, Up: Stdio
|
||
|
||
4.37 `getline'--read a line from a file
|
||
=======================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
ssize_t getline(char **BUFPTR, size_t *N, FILE *FP);
|
||
*Description*
|
||
`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);
|
||
|
||
*Returns*
|
||
`getline' returns `-1' if no characters were successfully read,
|
||
otherwise, it returns the number of bytes successfully read. at end of
|
||
file, the result is nonzero.
|
||
|
||
*Portability*
|
||
`getline' is a glibc extension.
|
||
|
||
No supporting OS subroutines are directly required.
|
||
|
||
|
||
File: libc.info, Node: gets, Next: getw, Prev: getline, Up: Stdio
|
||
|
||
4.38 `gets'--get character string (obsolete, use `fgets' instead)
|
||
=================================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
|
||
char *gets(char *BUF);
|
||
|
||
char *_gets_r(struct _reent *REENT, char *BUF);
|
||
*Description*
|
||
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.
|
||
|
||
*Returns*
|
||
`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'.
|
||
|
||
|
||
File: libc.info, Node: getw, Next: getwchar, Prev: gets, Up: Stdio
|
||
|
||
4.39 `getw'--read a word (int)
|
||
==============================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int getw(FILE *FP);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
The next word (read as an `int'), unless there is no more data or the
|
||
host system reports a read error; in either of these situations, `getw'
|
||
returns `EOF'. Since `EOF' is a valid `int', you must use `ferror' or
|
||
`feof' to distinguish these situations.
|
||
|
||
*Portability*
|
||
`getw' is a remnant of K&R C; it is not part of any ISO C Standard.
|
||
`fread' should be used instead. In fact, this implementation of `getw'
|
||
is based upon `fread'.
|
||
|
||
Supporting OS subroutines required: `fread'.
|
||
|
||
File: libc.info, Node: getwchar, Next: mktemp, Prev: getw, Up: Stdio
|
||
|
||
4.40 `getwchar'--read a wide character from standard input
|
||
==========================================================
|
||
|
||
*Synopsis*
|
||
#include <wchar.h>
|
||
wint_t getwchar(void);
|
||
|
||
wint_t _getwchar_r(struct _reent *REENT);
|
||
*Description*
|
||
`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.
|
||
|
||
The alternate function `_getwchar_r' is a reentrant version. The
|
||
extra argument REENT is a pointer to a reentrancy structure.
|
||
|
||
*Returns*
|
||
The next wide character cast to `wint_t', unless there is no more data,
|
||
or the host system reports a read error; in either of these situations,
|
||
`getwchar' returns `WEOF'.
|
||
|
||
You can distinguish the two situations that cause an `WEOF' result by
|
||
using ``ferror(stdin)'' and ``feof(stdin)''.
|
||
|
||
*Portability*
|
||
C99
|
||
|
||
|
||
File: libc.info, Node: mktemp, Next: open_memstream, Prev: getwchar, Up: Stdio
|
||
|
||
4.41 `mktemp', `mkstemp', `mkostemp', `mkstemps',
|
||
=================================================
|
||
|
||
*Synopsis*
|
||
#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);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
`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'.
|
||
|
||
*Portability*
|
||
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'.
|
||
|
||
|
||
File: libc.info, Node: open_memstream, Next: perror, Prev: mktemp, Up: Stdio
|
||
|
||
4.42 `open_memstream', `open_wmemstream'--open a write stream around an arbitrary-length string
|
||
===============================================================================================
|
||
|
||
*Synopsis*
|
||
#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);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
The return value is an open FILE pointer on success. On error, `NULL'
|
||
is returned, and `errno' will be set to EINVAL if BUF or SIZE is NULL,
|
||
ENOMEM if memory could not be allocated, or EMFILE if too many streams
|
||
are already open.
|
||
|
||
*Portability*
|
||
POSIX.1-2008
|
||
|
||
Supporting OS subroutines required: `sbrk'.
|
||
|
||
|
||
File: libc.info, Node: perror, Next: putc, Prev: open_memstream, Up: Stdio
|
||
|
||
4.43 `perror'--print an error message on standard error
|
||
=======================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
void perror(char *PREFIX);
|
||
|
||
void _perror_r(struct _reent *REENT, char *PREFIX);
|
||
*Description*
|
||
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.
|
||
|
||
*Returns*
|
||
`perror' returns no result.
|
||
|
||
*Portability*
|
||
ANSI C requires `perror', but the strings issued vary from one
|
||
implementation to another.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: putc, Next: putc_unlocked, Prev: perror, Up: Stdio
|
||
|
||
4.44 `putc'--write a character (macro)
|
||
======================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int putc(int CH, FILE *FP);
|
||
|
||
#include <stdio.h>
|
||
int _putc_r(struct _reent *PTR, int CH, FILE *FP);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
If successful, `putc' returns its argument CH. If an error intervenes,
|
||
the result is `EOF'. You can use ``ferror(FP)'' to query for errors.
|
||
|
||
*Portability*
|
||
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'.
|
||
|
||
|
||
File: libc.info, Node: putc_unlocked, Next: putchar, Prev: putc, Up: Stdio
|
||
|
||
4.45 `putc_unlocked'--non-thread-safe version of putc (macro)
|
||
=============================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int putc_unlocked(int CH, FILE *FP);
|
||
|
||
#include <stdio.h>
|
||
int _putc_unlocked_r(struct _reent *PTR, int CH, FILE *FP);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
See `putc'.
|
||
|
||
*Portability*
|
||
POSIX 1003.1 requires `putc_unlocked'. `putc_unlocked' may be
|
||
implemented as a macro, so arguments should not have side-effects.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: putchar, Next: putchar_unlocked, Prev: putc_unlocked, Up: Stdio
|
||
|
||
4.46 `putchar'--write a character (macro)
|
||
=========================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int putchar(int CH);
|
||
|
||
int _putchar_r(struct _reent *REENT, int CH);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
If successful, `putchar' returns its argument CH. If an error
|
||
intervenes, the result is `EOF'. You can use ``ferror(stdin)'' to
|
||
query for errors.
|
||
|
||
*Portability*
|
||
ANSI C requires `putchar'; it suggests, but does not require, that
|
||
`putchar' be implemented as a macro.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: putchar_unlocked, Next: puts, Prev: putchar, Up: Stdio
|
||
|
||
4.47 `putchar_unlocked'--non-thread-safe version of putchar (macro)
|
||
===================================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int putchar_unlocked(int CH);
|
||
*Description*
|
||
`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'.
|
||
|
||
*Returns*
|
||
See `putchar'.
|
||
|
||
*Portability*
|
||
POSIX 1003.1 requires `putchar_unlocked'. `putchar_unlocked' may be
|
||
implemented as a macro.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
File: libc.info, Node: puts, Next: putw, Prev: putchar_unlocked, Up: Stdio
|
||
|
||
4.48 `puts'--write a character string
|
||
=====================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int puts(const char *S);
|
||
|
||
int _puts_r(struct _reent *REENT, const char *S);
|
||
*Description*
|
||
`puts' writes the string at S (followed by a newline, instead of the
|
||
trailing null) to the standard output stream.
|
||
|
||
The alternate function `_puts_r' is a reentrant version. The extra
|
||
argument REENT is a pointer to a reentrancy structure.
|
||
|
||
*Returns*
|
||
If successful, the result is a nonnegative integer; otherwise, the
|
||
result is `EOF'.
|
||
|
||
*Portability*
|
||
ANSI C requires `puts', but does not specify that the result on success
|
||
must be `0'; any non-negative value is permitted.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: putw, Next: putwchar, Prev: puts, Up: Stdio
|
||
|
||
4.49 `putw'--write a word (int)
|
||
===============================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int putw(int W, FILE *FP);
|
||
*Description*
|
||
`putw' is a function, defined in `stdio.h'. You can use `putw' to
|
||
write a word to the file or stream identified by FP. As a side effect,
|
||
`putw' advances the file's current position indicator.
|
||
|
||
*Returns*
|
||
Zero on success, `EOF' on failure.
|
||
|
||
*Portability*
|
||
`putw' is a remnant of K&R C; it is not part of any ISO C Standard.
|
||
`fwrite' should be used instead. In fact, this implementation of
|
||
`putw' is based upon `fwrite'.
|
||
|
||
Supporting OS subroutines required: `fwrite'.
|
||
|
||
|
||
File: libc.info, Node: putwchar, Next: remove, Prev: putw, Up: Stdio
|
||
|
||
4.50 `putwchar'--write a wide character to standard output
|
||
==========================================================
|
||
|
||
*Synopsis*
|
||
#include <wchar.h>
|
||
wint_t putwchar(wchar_t WC);
|
||
|
||
wint_t _putwchar_r(struct _reent *REENT, wchar_t WC);
|
||
*Description*
|
||
The `putwchar' function or macro is the wide-character equivalent of
|
||
the `putchar' function. It writes the wide character wc to stdout.
|
||
|
||
The alternate function `_putwchar_r' is a reentrant version. The
|
||
extra argument REENT is a pointer to a reentrancy structure.
|
||
|
||
*Returns*
|
||
If successful, `putwchar' returns its argument WC. If an error
|
||
intervenes, the result is `EOF'. You can use ``ferror(stdin)'' to
|
||
query for errors.
|
||
|
||
*Portability*
|
||
C99
|
||
|
||
|
||
File: libc.info, Node: remove, Next: rename, Prev: putwchar, Up: Stdio
|
||
|
||
4.51 `remove'--delete a file's name
|
||
===================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int remove(char *FILENAME);
|
||
|
||
int _remove_r(struct _reent *REENT, char *FILENAME);
|
||
*Description*
|
||
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.
|
||
|
||
*Returns*
|
||
`remove' returns `0' if it succeeds, `-1' if it fails.
|
||
|
||
*Portability*
|
||
ANSI C requires `remove', but only specifies that the result on failure
|
||
be nonzero. The behavior of `remove' when you call it on an open file
|
||
may vary among implementations.
|
||
|
||
Supporting OS subroutine required: `unlink'.
|
||
|
||
|
||
File: libc.info, Node: rename, Next: rewind, Prev: remove, Up: Stdio
|
||
|
||
4.52 `rename'--rename a file
|
||
============================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int rename(const char *OLD, const char *NEW);
|
||
*Description*
|
||
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 `*OLD' is unaffected. The
|
||
conditions for failure depend on the host operating system.
|
||
|
||
*Returns*
|
||
The result is either `0' (when successful) or `-1' (when the file could
|
||
not be renamed).
|
||
|
||
*Portability*
|
||
ANSI C requires `rename', but only specifies that the result on failure
|
||
be nonzero. The effects of using the name of an existing file as
|
||
`*NEW' may vary from one implementation to another.
|
||
|
||
Supporting OS subroutines required: `link', `unlink', or `rename'.
|
||
|
||
|
||
File: libc.info, Node: rewind, Next: setbuf, Prev: rename, Up: Stdio
|
||
|
||
4.53 `rewind'--reinitialize a file or stream
|
||
============================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
void rewind(FILE *FP);
|
||
void _rewind_r(struct _reent *PTR, FILE *FP);
|
||
*Description*
|
||
`rewind' returns the file position indicator (if any) for the file or
|
||
stream identified by FP to the beginning of the file. It also clears
|
||
any error indicator and flushes any pending output.
|
||
|
||
*Returns*
|
||
`rewind' does not return a result.
|
||
|
||
*Portability*
|
||
ANSI C requires `rewind'.
|
||
|
||
No supporting OS subroutines are required.
|
||
|
||
|
||
File: libc.info, Node: setbuf, Next: setbuffer, Prev: rewind, Up: Stdio
|
||
|
||
4.54 `setbuf'--specify full buffering for a file or stream
|
||
==========================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
void setbuf(FILE *FP, char *BUF);
|
||
*Description*
|
||
`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.
|
||
|
||
*Warnings*
|
||
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.
|
||
|
||
*Returns*
|
||
`setbuf' does not return a result.
|
||
|
||
*Portability*
|
||
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'.
|
||
|
||
|
||
File: libc.info, Node: setbuffer, Next: setlinebuf, Prev: setbuf, Up: Stdio
|
||
|
||
4.55 `setbuffer'--specify full buffering for a file or stream with size
|
||
=======================================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
void setbuffer(FILE *FP, char *BUF, int SIZE);
|
||
*Description*
|
||
`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.
|
||
|
||
*Warnings*
|
||
You may only use `setbuffer' 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.
|
||
|
||
*Returns*
|
||
`setbuffer' does not return a result.
|
||
|
||
*Portability*
|
||
This function comes from BSD not ANSI or POSIX.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: setlinebuf, Next: setvbuf, Prev: setbuffer, Up: Stdio
|
||
|
||
4.56 `setlinebuf'--specify line buffering for a file or stream
|
||
==============================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
void setlinebuf(FILE *FP);
|
||
*Description*
|
||
`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.
|
||
|
||
*Warnings*
|
||
You may only use `setlinebuf' before performing any file operation
|
||
other than opening the file.
|
||
|
||
*Returns*
|
||
`setlinebuf' returns as per setvbuf.
|
||
|
||
*Portability*
|
||
This function comes from BSD not ANSI or POSIX.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: setvbuf, Next: siprintf, Prev: setlinebuf, Up: Stdio
|
||
|
||
4.57 `setvbuf'--specify file or stream buffering
|
||
================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int setvbuf(FILE *FP, char *BUF,
|
||
int MODE, size_t SIZE);
|
||
*Description*
|
||
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 FP.
|
||
|
||
`_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.
|
||
|
||
*Warnings*
|
||
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.
|
||
|
||
*Returns*
|
||
A `0' result indicates success, `EOF' failure (invalid MODE or SIZE can
|
||
cause failure).
|
||
|
||
*Portability*
|
||
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'.
|
||
|
||
|
||
File: libc.info, Node: siprintf, Next: siscanf, Prev: setvbuf, Up: Stdio
|
||
|
||
4.58 `siprintf', `fiprintf', `iprintf', `sniprintf', `asiprintf', `asniprintf'--format output (integer only)
|
||
============================================================================================================
|
||
|
||
*Synopsis*
|
||
#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, ...);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
Similar to `printf', `fprintf', `sprintf', `snprintf', `asprintf', and
|
||
`asnprintf'.
|
||
|
||
*Portability*
|
||
`iprintf', `fiprintf', `siprintf', `sniprintf', `asiprintf', and
|
||
`asniprintf' are newlib extensions.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: siscanf, Next: sprintf, Prev: siprintf, Up: Stdio
|
||
|
||
4.59 `siscanf', `fiscanf', `iscanf'--scan and format non-floating input
|
||
=======================================================================
|
||
|
||
*Synopsis*
|
||
#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, ...);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
`iscanf' returns the number of input fields successfully scanned,
|
||
converted and stored; the return value does not include scanned fields
|
||
which were not stored.
|
||
|
||
If `iscanf' attempts to read at end-of-file, the return value is
|
||
`EOF'.
|
||
|
||
If no fields were stored, the return value is `0'.
|
||
|
||
*Portability*
|
||
`iscanf', `fiscanf', and `siscanf' are newlib extensions.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: sprintf, Next: sscanf, Prev: siscanf, Up: Stdio
|
||
|
||
4.60 `sprintf', `fprintf', `printf', `snprintf', `asprintf', `asnprintf'--format output
|
||
=======================================================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
|
||
int printf(const char *FORMAT, ...);
|
||
int fprintf(FILE *FD, const char *FORMAT, ...);
|
||
int sprintf(char *STR, const char *FORMAT, ...);
|
||
int snprintf(char *STR, size_t SIZE, const char *FORMAT,
|
||
...);
|
||
int asprintf(char **STRP, const char *FORMAT, ...);
|
||
char *asnprintf(char *STR, size_t *SIZE, const char *FORMAT,
|
||
...);
|
||
|
||
int _printf_r(struct _reent *PTR, const char *FORMAT, ...);
|
||
int _fprintf_r(struct _reent *PTR, FILE *FD,
|
||
const char *FORMAT, ...);
|
||
int _sprintf_r(struct _reent *PTR, char *STR,
|
||
const char *FORMAT, ...);
|
||
int _snprintf_r(struct _reent *PTR, char *STR, size_t SIZE,
|
||
const char *FORMAT, ...);
|
||
int _asprintf_r(struct _reent *PTR, char **STRP,
|
||
const char *FORMAT, ...);
|
||
char *_asnprintf_r(struct _reent *PTR, char *STR,
|
||
size_t *SIZE, const char *FORMAT, ...);
|
||
*Description*
|
||
`printf' accepts a series of arguments, applies to each a format
|
||
specifier from `*FORMAT', and writes the formatted data to `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 `*STR' overlaps with one of the arguments.
|
||
Behavior is also undefined if the argument for `%n' within `*FORMAT'
|
||
overlaps another argument.
|
||
|
||
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 TYPE were `i', `d', `u', `f', `F',
|
||
`g', or `G', the integer portion of the conversion would be
|
||
formatted with thousands' grouping wide characters.)
|
||
|
||
`-'
|
||
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 TYPE of
|
||
`d', `i', `a', `A', `e', `E', `f', `F', `g', or `G') will
|
||
always begin with a plus or minus sign. (If you do not use
|
||
this flag, positive values do not begin with a plus sign.)
|
||
|
||
`" " (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 (`+') flag both appear, the space flag
|
||
is ignored.
|
||
|
||
`0'
|
||
If the TYPE character is `d', `i', `o', `u', `x', `X', `a',
|
||
`A', `e', `E', `f', `F', `g', or `G': leading zeros are used
|
||
to pad the field width (following any indication of sign or
|
||
base); no spaces are used for padding. If the zero (`0') and
|
||
minus (`-') flags both appear, the zero (`0') flag will be
|
||
ignored. For `d', `i', `o', `u', `x', and `X' conversions,
|
||
if a precision PREC is specified, the zero (`0') flag is
|
||
ignored.
|
||
|
||
Note that `0' is interpreted as a flag, not as the beginning
|
||
of a field width.
|
||
|
||
`#'
|
||
The result is to be converted to an alternative form,
|
||
according to 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 `0x' prefix.
|
||
|
||
`X'
|
||
A non-zero result will have a `0X' prefix.
|
||
|
||
`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 `d', `i', `o', `u', `x', or `X', specifies that the
|
||
argument should be converted to a `signed char' or `unsigned
|
||
char' before printing.
|
||
|
||
With `n', specifies that the argument is a pointer to a
|
||
`signed char'.
|
||
|
||
`h'
|
||
With `d', `i', `o', `u', `x', or `X', specifies that the
|
||
argument should be converted to a `short' or `unsigned short'
|
||
before printing.
|
||
|
||
With `n', specifies that the argument is a pointer to a
|
||
`short'.
|
||
|
||
`l'
|
||
With `d', `i', `o', `u', `x', or `X', specifies that the
|
||
argument is a `long' or `unsigned long'.
|
||
|
||
With `c', specifies that the argument has type `wint_t'.
|
||
|
||
With `s', specifies that the argument is a pointer to
|
||
`wchar_t'.
|
||
|
||
With `n', specifies that the argument is a pointer to a
|
||
`long'.
|
||
|
||
With `a', `A', `e', `E', `f', `F', `g', or `G', has no effect
|
||
(because of vararg promotion rules, there is no need to
|
||
distinguish between `float' and `double').
|
||
|
||
`ll'
|
||
With `d', `i', `o', `u', `x', or `X', specifies that the
|
||
argument is a `long long' or `unsigned long long'.
|
||
|
||
With `n', specifies that the argument is a pointer to a `long
|
||
long'.
|
||
|
||
`j'
|
||
With `d', `i', `o', `u', `x', or `X', specifies that the
|
||
argument is an `intmax_t' or `uintmax_t'.
|
||
|
||
With `n', specifies that the argument is a pointer to an
|
||
`intmax_t'.
|
||
|
||
`z'
|
||
With `d', `i', `o', `u', `x', or `X', specifies that the
|
||
argument is a `size_t'.
|
||
|
||
With `n', specifies that the argument is a pointer to a
|
||
`size_t'.
|
||
|
||
`t'
|
||
With `d', `i', `o', `u', `x', or `X', specifies that the
|
||
argument is a `ptrdiff_t'.
|
||
|
||
With `n', specifies that the argument is a pointer to a
|
||
`ptrdiff_t'.
|
||
|
||
`L'
|
||
With `a', `A', `e', `E', `f', `F', `g', or `G', specifies
|
||
that the argument is a `long double'.
|
||
|
||
|
||
* TYPE
|
||
|
||
TYPE specifies what kind of conversion `printf' performs. Here is
|
||
a table of these:
|
||
|
||
`%'
|
||
Prints the percent character (`%').
|
||
|
||
`c'
|
||
Prints ARG as single character. If the `l' size specifier is
|
||
in effect, a multibyte character is printed.
|
||
|
||
`C'
|
||
Short for `%lc'. A POSIX extension to the C standard.
|
||
|
||
`s'
|
||
Prints the elements of a pointer to `char' until the
|
||
precision or a null character is reached. If the `l' size
|
||
specifier is in effect, the pointer is to an array of
|
||
`wchar_t', and the string is converted to multibyte
|
||
characters before printing.
|
||
|
||
`S'
|
||
Short for `%ls'. A POSIX extension to the C standard.
|
||
|
||
`d or i'
|
||
Prints a signed decimal integer; takes an `int'. Leading
|
||
zeros are inserted as necessary to reach the precision. A
|
||
value of 0 with a precision of 0 produces an empty string.
|
||
|
||
`D'
|
||
Newlib extension, short for `%ld'.
|
||
|
||
`o'
|
||
Prints an unsigned octal integer; takes an `unsigned'.
|
||
Leading zeros are inserted as necessary to reach the
|
||
precision. A value of 0 with a precision of 0 produces an
|
||
empty string.
|
||
|
||
`O'
|
||
Newlib extension, short for `%lo'.
|
||
|
||
`u'
|
||
Prints an unsigned decimal integer; takes an `unsigned'.
|
||
Leading zeros are inserted as necessary to reach the
|
||
precision. A value of 0 with a precision of 0 produces an
|
||
empty string.
|
||
|
||
`U'
|
||
Newlib extension, short for `%lu'.
|
||
|
||
`x'
|
||
Prints an unsigned hexadecimal integer (using `abcdef' as
|
||
digits beyond `9'); takes an `unsigned'. Leading zeros are
|
||
inserted as necessary to reach the precision. A value of 0
|
||
with a precision of 0 produces an empty string.
|
||
|
||
`X'
|
||
Like `x', but uses `ABCDEF' as digits beyond `9'.
|
||
|
||
`f'
|
||
Prints a signed value of the form `[-]9999.9999', with the
|
||
precision determining how many digits follow the decimal
|
||
point; takes a `double' (remember that `float' promotes to
|
||
`double' as a vararg). The low order digit is rounded to
|
||
even. If the precision results in at most DECIMAL_DIG
|
||
digits, the result is rounded correctly; if more than
|
||
DECIMAL_DIG digits are printed, the result is only guaranteed
|
||
to round back to the original value.
|
||
|
||
If the value is infinite, the result is `inf', and no zero
|
||
padding is performed. If the value is not a number, the
|
||
result is `nan', and no zero padding is performed.
|
||
|
||
`F'
|
||
Like `f', but uses `INF' and `NAN' for non-finite numbers.
|
||
|
||
`e'
|
||
Prints a signed value of the form `[-]9.9999e[+|-]999'; takes
|
||
a `double'. The digit before the decimal point is non-zero
|
||
if the value is non-zero. The precision determines how many
|
||
digits appear between `.' and `e', and the exponent always
|
||
contains at least two digits. The value zero has an exponent
|
||
of zero. If the value is not finite, it is printed like `f'.
|
||
|
||
`E'
|
||
Like `e', but using `E' to introduce the exponent, and like
|
||
`F' for non-finite values.
|
||
|
||
`g'
|
||
Prints a signed value in either `f' or `e' form, based on the
|
||
given value and precision--an exponent less than -4 or
|
||
greater than the precision selects the `e' form. Trailing
|
||
zeros and the decimal point are printed only if necessary;
|
||
takes a `double'.
|
||
|
||
`G'
|
||
Like `g', except use `F' or `E' form.
|
||
|
||
`a'
|
||
Prints a signed value of the form `[-]0x1.ffffp[+|-]9'; takes
|
||
a `double'. The letters `abcdef' are used for digits beyond
|
||
`9'. The precision determines how many digits appear after
|
||
the decimal point. The exponent contains at least one digit,
|
||
and is a decimal value representing the power of 2; a value
|
||
of 0 has an exponent of 0. Non-finite values are printed
|
||
like `f'.
|
||
|
||
`A'
|
||
Like `a', except uses `X', `P', and `ABCDEF' instead of lower
|
||
case.
|
||
|
||
`n'
|
||
Takes a pointer to `int', and stores a count of the number of
|
||
bytes written so far. No output is created.
|
||
|
||
`p'
|
||
Takes a pointer to `void', and prints it in an
|
||
implementation-defined format. This implementation is
|
||
similar to `%#tx'), except that `0x' appears even for the
|
||
NULL pointer.
|
||
|
||
`m'
|
||
Prints the output of `strerror(errno)'; no argument is
|
||
required. A GNU extension.
|
||
|
||
|
||
|
||
`_printf_r', `_fprintf_r', `_asprintf_r', `_sprintf_r',
|
||
`_snprintf_r', `_asnprintf_r' are simply reentrant versions of the
|
||
functions above.
|
||
|
||
*Returns*
|
||
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.
|
||
|
||
*Bugs*
|
||
The ""' (quote) flag does not work when locale's thousands_sep is not
|
||
empty.
|
||
|
||
*Portability*
|
||
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'.
|
||
|
||
|
||
File: libc.info, Node: sscanf, Next: swprintf, Prev: sprintf, Up: Stdio
|
||
|
||
4.61 `sscanf', `fscanf', `scanf'--scan and format input
|
||
=======================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
|
||
int scanf(const char *FORMAT, ...);
|
||
int fscanf(FILE *FD, const char *FORMAT, ...);
|
||
int sscanf(const char *STR, const char *FORMAT, ...);
|
||
|
||
int _scanf_r(struct _reent *PTR, const char *FORMAT, ...);
|
||
int _fscanf_r(struct _reent *PTR, FILE *FD,
|
||
const char *FORMAT, ...);
|
||
int _sscanf_r(struct _reent *PTR, const char *STR,
|
||
const char *FORMAT, ...);
|
||
*Description*
|
||
`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 `*FORMAT' 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.
|
||
|
||
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 no effect
|
||
e, f, c, s, p
|
||
|
||
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 no effect
|
||
c, s, p
|
||
|
||
ll d, i, o, u, x, n convert to long long,
|
||
store in long long
|
||
|
||
L d, i, o, u, x, n convert to long long,
|
||
store in long long
|
||
|
||
L e, f, g, E, G convert to long double,
|
||
store in long double
|
||
|
||
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 (`%') is stored.
|
||
|
||
`c'
|
||
Scans one character. Corresponding ARG: `(char *arg)'.
|
||
|
||
`s'
|
||
Reads a character string into the array supplied.
|
||
Corresponding ARG: `(char arg[])'.
|
||
|
||
`[PATTERN]'
|
||
Reads a non-empty character string into memory starting at
|
||
ARG. This area must be large enough to accept the sequence
|
||
and a terminating null character which will be added
|
||
automatically. (PATTERN is discussed in the paragraph
|
||
following this table). Corresponding ARG: `(char *arg)'.
|
||
|
||
`d'
|
||
Reads a decimal integer into the corresponding ARG: `(int
|
||
*arg)'.
|
||
|
||
`D'
|
||
Reads a decimal integer into the corresponding ARG: `(long
|
||
*arg)'.
|
||
|
||
`o'
|
||
Reads an octal integer into the corresponding ARG: `(int
|
||
*arg)'.
|
||
|
||
`O'
|
||
Reads an octal integer into the corresponding ARG: `(long
|
||
*arg)'.
|
||
|
||
`u'
|
||
Reads an unsigned decimal integer into the corresponding ARG:
|
||
`(unsigned int *arg)'.
|
||
|
||
`U'
|
||
Reads an unsigned decimal integer into the corresponding ARG:
|
||
`(unsigned long *arg)'.
|
||
|
||
`x,X'
|
||
Read a hexadecimal integer into the corresponding ARG: `(int
|
||
*arg)'.
|
||
|
||
`e, f, g'
|
||
Read a floating-point number into the corresponding ARG:
|
||
`(float *arg)'.
|
||
|
||
`E, F, G'
|
||
Read a floating-point number into the corresponding ARG:
|
||
`(double *arg)'.
|
||
|
||
`i'
|
||
Reads a decimal, octal or hexadecimal integer into the
|
||
corresponding ARG: `(int *arg)'.
|
||
|
||
`I'
|
||
Reads a decimal, octal or hexadecimal integer into the
|
||
corresponding ARG: `(long *arg)'.
|
||
|
||
`n'
|
||
Stores the number of characters read in the corresponding
|
||
ARG: `(int *arg)'.
|
||
|
||
`p'
|
||
Stores a scanned pointer. ANSI C leaves the details to each
|
||
implementation; this implementation treats `%p' exactly the
|
||
same as `%U'. Corresponding ARG: `(void **arg)'.
|
||
|
||
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 `a', `b', `c', and `d'.
|
||
|
||
`%[^abcd]'
|
||
matches strings containing any characters except `a', `b',
|
||
`c', or `d'
|
||
|
||
`%[A-DW-Z]'
|
||
matches strings containing `A', `B', `C', `D', `W', `X', `Y',
|
||
`Z'
|
||
|
||
`%[z-a]'
|
||
matches the characters `z', `-', and `a'
|
||
|
||
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.
|
||
|
||
*Returns*
|
||
`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.
|
||
|
||
*Portability*
|
||
`scanf' is ANSI C.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: swprintf, Next: swscanf, Prev: sscanf, Up: Stdio
|
||
|
||
4.62 `swprintf', `fwprintf', `wprintf'--wide character format output
|
||
====================================================================
|
||
|
||
*Synopsis*
|
||
#include <wchar.h>
|
||
|
||
int wprintf(const wchar_t *FORMAT, ...);
|
||
int fwprintf(FILE *FD, const wchar_t *FORMAT, ...);
|
||
int swprintf(wchar_t *STR, size_t SIZE,
|
||
const wchar_t *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, ...);
|
||
*Description*
|
||
`wprintf' accepts a series of arguments, applies to each a format
|
||
specifier from `*FORMAT', and writes the formatted data to `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 `*STR'
|
||
overlaps with one of the arguments. Behavior is also undefined if the
|
||
argument for `%n' within `*FORMAT' overlaps another argument.
|
||
|
||
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 TYPE were `i', `d', `u', `f', `F',
|
||
`g', or `G', the integer portion of the conversion would be
|
||
formatted with thousands' grouping wide characters.)
|
||
|
||
`-'
|
||
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 TYPE of
|
||
`d', `i', `a', `A', `e', `E', `f', `F', `g', or `G') will
|
||
always begin with a plus or minus sign. (If you do not use
|
||
this flag, positive values do not begin with a plus sign.)
|
||
|
||
`" " (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 (`+') flag both appear, the space flag
|
||
is ignored.
|
||
|
||
`0'
|
||
If the TYPE character is `d', `i', `o', `u', `x', `X', `a',
|
||
`A', `e', `E', `f', `F', `g', or `G': leading zeros are used
|
||
to pad the field width (following any indication of sign or
|
||
base); no spaces are used for padding. If the zero (`0') and
|
||
minus (`-') flags both appear, the zero (`0') flag will be
|
||
ignored. For `d', `i', `o', `u', `x', and `X' conversions,
|
||
if a precision PREC is specified, the zero (`0') flag is
|
||
ignored.
|
||
|
||
Note that `0' is interpreted as a flag, not as the beginning
|
||
of a field width.
|
||
|
||
`#'
|
||
The result is to be converted to an alternative form,
|
||
according to 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 `0x' prefix.
|
||
|
||
`X'
|
||
A non-zero result will have a `0X' prefix.
|
||
|
||
`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 `d', `i', `o', `u', `x', or `X', specifies that the
|
||
argument should be converted to a `signed char' or `unsigned
|
||
char' before printing.
|
||
|
||
With `n', specifies that the argument is a pointer to a
|
||
`signed char'.
|
||
|
||
`h'
|
||
With `d', `i', `o', `u', `x', or `X', specifies that the
|
||
argument should be converted to a `short' or `unsigned short'
|
||
before printing.
|
||
|
||
With `n', specifies that the argument is a pointer to a
|
||
`short'.
|
||
|
||
`l'
|
||
With `d', `i', `o', `u', `x', or `X', specifies that the
|
||
argument is a `long' or `unsigned long'.
|
||
|
||
With `c', specifies that the argument has type `wint_t'.
|
||
|
||
With `s', specifies that the argument is a pointer to
|
||
`wchar_t'.
|
||
|
||
With `n', specifies that the argument is a pointer to a
|
||
`long'.
|
||
|
||
With `a', `A', `e', `E', `f', `F', `g', or `G', has no effect
|
||
(because of vararg promotion rules, there is no need to
|
||
distinguish between `float' and `double').
|
||
|
||
`ll'
|
||
With `d', `i', `o', `u', `x', or `X', specifies that the
|
||
argument is a `long long' or `unsigned long long'.
|
||
|
||
With `n', specifies that the argument is a pointer to a `long
|
||
long'.
|
||
|
||
`j'
|
||
With `d', `i', `o', `u', `x', or `X', specifies that the
|
||
argument is an `intmax_t' or `uintmax_t'.
|
||
|
||
With `n', specifies that the argument is a pointer to an
|
||
`intmax_t'.
|
||
|
||
`z'
|
||
With `d', `i', `o', `u', `x', or `X', specifies that the
|
||
argument is a `size_t'.
|
||
|
||
With `n', specifies that the argument is a pointer to a
|
||
`size_t'.
|
||
|
||
`t'
|
||
With `d', `i', `o', `u', `x', or `X', specifies that the
|
||
argument is a `ptrdiff_t'.
|
||
|
||
With `n', specifies that the argument is a pointer to a
|
||
`ptrdiff_t'.
|
||
|
||
`L'
|
||
With `a', `A', `e', `E', `f', `F', `g', or `G', specifies
|
||
that the argument is a `long double'.
|
||
|
||
|
||
* TYPE
|
||
|
||
TYPE specifies what kind of conversion `wprintf' performs. Here
|
||
is a table of these:
|
||
|
||
`%'
|
||
Prints the percent character (`%').
|
||
|
||
`c'
|
||
If no `l' qualifier is present, the int argument shall be
|
||
converted to a wide character as if by calling the btowc()
|
||
function and the resulting wide character shall be written.
|
||
Otherwise, the wint_t argument shall be converted to wchar_t,
|
||
and written.
|
||
|
||
`C'
|
||
Short for `%lc'. A POSIX extension to the C standard.
|
||
|
||
`s'
|
||
If no `l' qualifier is present, the application shall ensure
|
||
that the argument is a pointer to a character array
|
||
containing a character sequence beginning in the initial
|
||
shift state. Characters from the array shall be converted as
|
||
if by repeated calls to the mbrtowc() function, with the
|
||
conversion state described by an mbstate_t object initialized
|
||
to zero before the first character is converted, and written
|
||
up to (but not including) the terminating null wide
|
||
character. If the precision is specified, no more than that
|
||
many wide characters shall be written. If the precision is
|
||
not specified, or is greater than the size of the array, the
|
||
application shall ensure that the array contains a null wide
|
||
character.
|
||
|
||
If an `l' qualifier is present, the application shall ensure
|
||
that the argument is a pointer to an array of type wchar_t.
|
||
Wide characters from the array shall be written up to (but
|
||
not including) a terminating null wide character. If no
|
||
precision is specified, or is greater than the size of the
|
||
array, the application shall ensure that the array contains a
|
||
null wide character. If a precision is specified, no more
|
||
than that many wide characters shall be written.
|
||
|
||
`S'
|
||
Short for `%ls'. A POSIX extension to the C standard.
|
||
|
||
`d or i'
|
||
Prints a signed decimal integer; takes an `int'. Leading
|
||
zeros are inserted as necessary to reach the precision. A
|
||
value of 0 with a precision of 0 produces an empty string.
|
||
|
||
`o'
|
||
Prints an unsigned octal integer; takes an `unsigned'.
|
||
Leading zeros are inserted as necessary to reach the
|
||
precision. A value of 0 with a precision of 0 produces an
|
||
empty string.
|
||
|
||
`u'
|
||
Prints an unsigned decimal integer; takes an `unsigned'.
|
||
Leading zeros are inserted as necessary to reach the
|
||
precision. A value of 0 with a precision of 0 produces an
|
||
empty string.
|
||
|
||
`x'
|
||
Prints an unsigned hexadecimal integer (using `abcdef' as
|
||
digits beyond `9'); takes an `unsigned'. Leading zeros are
|
||
inserted as necessary to reach the precision. A value of 0
|
||
with a precision of 0 produces an empty string.
|
||
|
||
`X'
|
||
Like `x', but uses `ABCDEF' as digits beyond `9'.
|
||
|
||
`f'
|
||
Prints a signed value of the form `[-]9999.9999', with the
|
||
precision determining how many digits follow the decimal
|
||
point; takes a `double' (remember that `float' promotes to
|
||
`double' as a vararg). The low order digit is rounded to
|
||
even. If the precision results in at most DECIMAL_DIG
|
||
digits, the result is rounded correctly; if more than
|
||
DECIMAL_DIG digits are printed, the result is only guaranteed
|
||
to round back to the original value.
|
||
|
||
If the value is infinite, the result is `inf', and no zero
|
||
padding is performed. If the value is not a number, the
|
||
result is `nan', and no zero padding is performed.
|
||
|
||
`F'
|
||
Like `f', but uses `INF' and `NAN' for non-finite numbers.
|
||
|
||
`e'
|
||
Prints a signed value of the form `[-]9.9999e[+|-]999'; takes
|
||
a `double'. The digit before the decimal point is non-zero
|
||
if the value is non-zero. The precision determines how many
|
||
digits appear between `.' and `e', and the exponent always
|
||
contains at least two digits. The value zero has an exponent
|
||
of zero. If the value is not finite, it is printed like `f'.
|
||
|
||
`E'
|
||
Like `e', but using `E' to introduce the exponent, and like
|
||
`F' for non-finite values.
|
||
|
||
`g'
|
||
Prints a signed value in either `f' or `e' form, based on the
|
||
given value and precision--an exponent less than -4 or
|
||
greater than the precision selects the `e' form. Trailing
|
||
zeros and the decimal point are printed only if necessary;
|
||
takes a `double'.
|
||
|
||
`G'
|
||
Like `g', except use `F' or `E' form.
|
||
|
||
`a'
|
||
Prints a signed value of the form `[-]0x1.ffffp[+|-]9'; takes
|
||
a `double'. The letters `abcdef' are used for digits beyond
|
||
`9'. The precision determines how many digits appear after
|
||
the decimal point. The exponent contains at least one digit,
|
||
and is a decimal value representing the power of 2; a value
|
||
of 0 has an exponent of 0. Non-finite values are printed
|
||
like `f'.
|
||
|
||
`A'
|
||
Like `a', except uses `X', `P', and `ABCDEF' instead of lower
|
||
case.
|
||
|
||
`n'
|
||
Takes a pointer to `int', and stores a count of the number of
|
||
bytes written so far. No output is created.
|
||
|
||
`p'
|
||
Takes a pointer to `void', and prints it in an
|
||
implementation-defined format. This implementation is
|
||
similar to `%#tx'), except that `0x' appears even for the
|
||
NULL pointer.
|
||
|
||
`m'
|
||
Prints the output of `strerror(errno)'; no argument is
|
||
required. A GNU extension.
|
||
|
||
|
||
|
||
`_wprintf_r', `_fwprintf_r', `_swprintf_r', are simply reentrant
|
||
versions of the functions above.
|
||
|
||
*Returns*
|
||
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').
|
||
|
||
*Bugs*
|
||
The ""' (quote) flag does not work when locale's thousands_sep is not
|
||
empty.
|
||
|
||
*Portability*
|
||
POSIX-1.2008 with extensions; C99 (compliant except for POSIX
|
||
extensions).
|
||
|
||
Depending on how newlib was configured, not all format specifiers are
|
||
supported.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: swscanf, Next: tmpfile, Prev: swprintf, Up: Stdio
|
||
|
||
4.63 `swscanf', `fwscanf', `wscanf'--scan and format wide character input
|
||
=========================================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
|
||
int wscanf(const wchar_t *FORMAT, ...);
|
||
int fwscanf(FILE *FD, const wchar_t *FORMAT, ...);
|
||
int swscanf(const wchar_t *STR, const wchar_t *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, ...);
|
||
*Description*
|
||
`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 `*FORMAT' 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.
|
||
|
||
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
|
||
|
||
L d, i, o, u, x, n convert to long long,
|
||
store in long long
|
||
|
||
L e, f, g, E, G convert to long double,
|
||
store in long double
|
||
|
||
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 (`%') is stored.
|
||
|
||
`c'
|
||
Scans one wide character. Corresponding ARG: `(char *arg)'.
|
||
Otherwise, if an `l' specifier is present, the corresponding
|
||
ARG is a `(wchar_t *arg)'.
|
||
|
||
`s'
|
||
Reads a character string into the array supplied.
|
||
Corresponding ARG: `(char arg[])'. If an `l' specifier is
|
||
present, the corresponding ARG is a `(wchar_t *arg)'.
|
||
|
||
`[PATTERN]'
|
||
Reads a non-empty character string into memory starting at
|
||
ARG. This area must be large enough to accept the sequence
|
||
and a terminating null character which will be added
|
||
automatically. (PATTERN is discussed in the paragraph
|
||
following this table). Corresponding ARG: `(char *arg)'. If
|
||
an `l' specifier is present, the corresponding ARG is a
|
||
`(wchar_t *arg)'.
|
||
|
||
`d'
|
||
Reads a decimal integer into the corresponding ARG: `(int
|
||
*arg)'.
|
||
|
||
`o'
|
||
Reads an octal integer into the corresponding ARG: `(int
|
||
*arg)'.
|
||
|
||
`u'
|
||
Reads an unsigned decimal integer into the corresponding ARG:
|
||
`(unsigned int *arg)'.
|
||
|
||
`x,X'
|
||
Read a hexadecimal integer into the corresponding ARG: `(int
|
||
*arg)'.
|
||
|
||
`e, f, g'
|
||
Read a floating-point number into the corresponding ARG:
|
||
`(float *arg)'.
|
||
|
||
`E, F, G'
|
||
Read a floating-point number into the corresponding ARG:
|
||
`(double *arg)'.
|
||
|
||
`i'
|
||
Reads a decimal, octal or hexadecimal integer into the
|
||
corresponding ARG: `(int *arg)'.
|
||
|
||
`n'
|
||
Stores the number of characters read in the corresponding
|
||
ARG: `(int *arg)'.
|
||
|
||
`p'
|
||
Stores a scanned pointer. ANSI C leaves the details to each
|
||
implementation; this implementation treats `%p' exactly the
|
||
same as `%U'. Corresponding ARG: `(void **arg)'.
|
||
|
||
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 `a', `b', `c',
|
||
and `d'.
|
||
|
||
`%[^abcd]'
|
||
matches wide character strings containing any characters
|
||
except `a', `b', `c', or `d'.
|
||
|
||
`%[A-DW-Z]'
|
||
Note: No wide character ranges, so this expression matches
|
||
wide character strings containing `A', `-', `D', `W', `Z'.
|
||
|
||
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.
|
||
|
||
*Returns*
|
||
`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.
|
||
|
||
*Portability*
|
||
`wscanf' is C99, POSIX-1.2008.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: tmpfile, Next: tmpnam, Prev: swscanf, Up: Stdio
|
||
|
||
4.64 `tmpfile'--create a temporary file
|
||
=======================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
FILE *tmpfile(void);
|
||
|
||
FILE *_tmpfile_r(struct _reent *REENT);
|
||
*Description*
|
||
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.
|
||
|
||
*Returns*
|
||
`tmpfile' normally returns a pointer to the temporary file. If no
|
||
temporary file could be created, the result is NULL, and `errno'
|
||
records the reason for failure.
|
||
|
||
*Portability*
|
||
Both ANSI C and the System V Interface Definition (Issue 2) require
|
||
`tmpfile'.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `getpid',
|
||
`isatty', `lseek', `open', `read', `sbrk', `write'.
|
||
|
||
`tmpfile' also requires the global pointer `environ'.
|
||
|
||
|
||
File: libc.info, Node: tmpnam, Next: ungetc, Prev: tmpfile, Up: Stdio
|
||
|
||
4.65 `tmpnam', `tempnam'--name for a temporary file
|
||
===================================================
|
||
|
||
*Synopsis*
|
||
#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);
|
||
*Description*
|
||
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.
|
||
|
||
*Warnings*
|
||
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'.
|
||
|
||
*Returns*
|
||
Both `tmpnam' and `tempnam' return a pointer to the newly generated
|
||
filename.
|
||
|
||
*Portability*
|
||
ANSI C requires `tmpnam', but does not specify the use of `P_tmpdir'.
|
||
The System V Interface Definition (Issue 2) requires both `tmpnam' and
|
||
`tempnam'.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `getpid',
|
||
`isatty', `lseek', `open', `read', `sbrk', `write'.
|
||
|
||
The global pointer `environ' is also required.
|
||
|
||
|
||
File: libc.info, Node: ungetc, Next: ungetwc, Prev: tmpnam, Up: Stdio
|
||
|
||
4.66 `ungetc'--push data back into a stream
|
||
===========================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
int ungetc(int C, FILE *STREAM);
|
||
|
||
int _ungetc_r(struct _reent *REENT, int C, FILE *STREAM);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
The character pushed back, or `EOF' on error.
|
||
|
||
*Portability*
|
||
ANSI C requires `ungetc', but only requires a pushback buffer of one
|
||
byte; although this implementation can handle multiple bytes, not all
|
||
can. Pushing back a signed char is a common application bug.
|
||
|
||
Supporting OS subroutines required: `sbrk'.
|
||
|
||
|
||
File: libc.info, Node: ungetwc, Next: vfprintf, Prev: ungetc, Up: Stdio
|
||
|
||
4.67 `ungetwc'--push wide character data back into a stream
|
||
===========================================================
|
||
|
||
*Synopsis*
|
||
#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);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
The wide character pushed back, or `WEOF' on error.
|
||
|
||
*Portability*
|
||
C99
|
||
|
||
|
||
File: libc.info, Node: vfprintf, Next: vfscanf, Prev: ungetwc, Up: Stdio
|
||
|
||
4.68 `vfprintf', `vprintf', `vsprintf', `vsnprintf', `vasprintf', `vasnprintf'--format argument list
|
||
====================================================================================================
|
||
|
||
*Synopsis*
|
||
#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);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
The return values are consistent with the corresponding functions.
|
||
|
||
*Portability*
|
||
ANSI C requires `vprintf', `vfprintf', `vsprintf', and `vsnprintf'.
|
||
The remaining functions are newlib extensions.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: vfscanf, Next: vfwprintf, Prev: vfprintf, Up: Stdio
|
||
|
||
4.69 `vfscanf', `vscanf', `vsscanf'--format argument list
|
||
=========================================================
|
||
|
||
*Synopsis*
|
||
#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);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
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.
|
||
|
||
*Portability*
|
||
These are GNU extensions.
|
||
|
||
Supporting OS subroutines required:
|
||
|
||
|
||
File: libc.info, Node: vfwprintf, Next: vfwscanf, Prev: vfscanf, Up: Stdio
|
||
|
||
4.70 `vfwprintf', `vwprintf', `vswprintf'--wide character format argument list
|
||
==============================================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
#include <stdarg.h>
|
||
#include <wchar.h>
|
||
int vwprintf(const wchar_t *FMT, va_list LIST);
|
||
int vfwprintf(FILE *FP, const wchar_t *FMT, va_list LIST);
|
||
int vswprintf(wchar_t *STR, size_t SIZE, const wchar_t *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);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
The return values are consistent with the corresponding functions.
|
||
|
||
*Portability*
|
||
POSIX-1.2008 with extensions; C99 (compliant except for POSIX
|
||
extensions).
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
*See Also*
|
||
`wprintf', `fwprintf' and `swprintf'.
|
||
|
||
|
||
File: libc.info, Node: vfwscanf, Next: viprintf, Prev: vfwprintf, Up: Stdio
|
||
|
||
4.71 `vfwscanf', `vwscanf', `vswscanf'--scan and format argument list from wide character input
|
||
===============================================================================================
|
||
|
||
*Synopsis*
|
||
#include <stdio.h>
|
||
#include <stdarg.h>
|
||
int vwscanf(const wchar_t *FMT, va_list LIST);
|
||
int vfwscanf(FILE *FP, const wchar_t *FMT, va_list LIST);
|
||
int vswscanf(const wchar_t *STR, const wchar_t *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);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
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.
|
||
|
||
*Portability*
|
||
C99, POSIX-1.2008
|
||
|
||
|
||
File: libc.info, Node: viprintf, Next: viscanf, Prev: vfwscanf, Up: Stdio
|
||
|
||
4.72 `viprintf', `vfiprintf', `vsiprintf', `vsniprintf', `vasiprintf', `vasniprintf'--format argument list (integer only)
|
||
=========================================================================================================================
|
||
|
||
*Synopsis*
|
||
#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);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
The return values are consistent with the corresponding functions:
|
||
|
||
*Portability*
|
||
All of these functions are newlib extensions.
|
||
|
||
Supporting OS subroutines required: `close', `fstat', `isatty',
|
||
`lseek', `read', `sbrk', `write'.
|
||
|
||
|
||
File: libc.info, Node: viscanf, Prev: viprintf, Up: Stdio
|
||
|
||
4.73 `viscanf', `vfiscanf', `vsiscanf'--format argument list
|
||
============================================================
|
||
|
||
*Synopsis*
|
||
#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);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
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.
|
||
|
||
*Portability*
|
||
These are newlib extensions.
|
||
|
||
Supporting OS subroutines required:
|
||
|
||
|
||
File: libc.info, Node: Strings, Next: Wchar strings, Prev: Stdio, Up: Top
|
||
|
||
5 Strings and Memory (`string.h')
|
||
*********************************
|
||
|
||
This chapter describes string-handling functions and functions for
|
||
managing areas of memory. The corresponding declarations are in
|
||
`string.h'.
|
||
|
||
* Menu:
|
||
|
||
* bcmp:: Compare two memory areas
|
||
* bcopy:: Copy memory regions
|
||
* bzero:: Initialize memory to zero
|
||
* index:: Search for character in string
|
||
* memccpy:: Copy memory regions up to end-token
|
||
* memchr:: Find character in memory
|
||
* memcmp:: Compare two memory areas
|
||
* memcpy:: Copy memory regions
|
||
* memmem:: Find memory segment
|
||
* memmove:: Move possibly overlapping memory
|
||
* mempcpy:: Copy memory regions and locate end
|
||
* memset:: Set an area of memory
|
||
* rindex:: Reverse search for character in string
|
||
* stpcpy:: Copy string returning a pointer to its end
|
||
* stpncpy:: Counted copy string returning a pointer to its end
|
||
* strcasecmp:: Compare strings ignoring case
|
||
* strcasestr:: Find string segment ignoring case
|
||
* strcat:: Concatenate strings
|
||
* strchr:: Search for character in string
|
||
* strcmp:: Character string compare
|
||
* strcoll:: Locale-specific character string compare
|
||
* strcpy:: Copy string
|
||
* strcspn:: Count chars not in string
|
||
* strerror:: Convert error number to string
|
||
* strerror_r:: Convert error number to string
|
||
* strlen:: Character string length
|
||
* strlwr:: Convert string to lowercase
|
||
* strncasecmp:: Compare strings ignoring case
|
||
* strncat:: Concatenate strings
|
||
* strncmp:: Character string compare
|
||
* strncpy:: Counted copy string
|
||
* strnlen:: Character string length
|
||
* strpbrk:: Find chars in string
|
||
* strrchr:: Reverse search for character in string
|
||
* strsignal:: Return signal message string
|
||
* strspn:: Find initial match
|
||
* strstr:: Find string segment
|
||
* strtok:: Get next token from a string
|
||
* strupr:: Convert string to upper case
|
||
* strxfrm:: Transform string
|
||
* swab:: Swap adjacent bytes
|
||
* wcscasecmp:: Compare wide character strings ignoring case
|
||
* wcsdup:: Wide character string duplicate
|
||
* wcsncasecmp:: Compare wide character strings ignoring case
|
||
|
||
|
||
File: libc.info, Node: bcmp, Next: bcopy, Up: Strings
|
||
|
||
5.1 `bcmp'--compare two memory areas
|
||
====================================
|
||
|
||
*Synopsis*
|
||
#include <strings.h>
|
||
int bcmp(const void *S1, const void *S2, size_t N);
|
||
*Description*
|
||
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'.
|
||
|
||
*Returns*
|
||
The function returns an integer greater than, equal to or less than
|
||
zero according to whether the object pointed to by S1 is greater than,
|
||
equal to or less than the object pointed to by S2.
|
||
|
||
*Portability*
|
||
`bcmp' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: bcopy, Next: bzero, Prev: bcmp, Up: Strings
|
||
|
||
5.2 `bcopy'--copy memory regions
|
||
================================
|
||
|
||
*Synopsis*
|
||
#include <strings.h>
|
||
void bcopy(const void *IN, void *OUT, size_t N);
|
||
*Description*
|
||
This function copies N bytes from the memory region pointed to by IN to
|
||
the memory region pointed to by OUT.
|
||
|
||
This function is implemented in term of `memmove'.
|
||
|
||
*Portability*
|
||
`bcopy' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: bzero, Next: index, Prev: bcopy, Up: Strings
|
||
|
||
5.3 `bzero'--initialize memory to zero
|
||
======================================
|
||
|
||
*Synopsis*
|
||
#include <strings.h>
|
||
void bzero(void *B, size_t LENGTH);
|
||
*Description*
|
||
`bzero' initializes LENGTH bytes of memory, starting at address B, to
|
||
zero.
|
||
|
||
*Returns*
|
||
`bzero' does not return a result.
|
||
|
||
*Portability*
|
||
`bzero' is in the Berkeley Software Distribution. Neither ANSI C nor
|
||
the System V Interface Definition (Issue 2) require `bzero'.
|
||
|
||
`bzero' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: index, Next: memccpy, Prev: bzero, Up: Strings
|
||
|
||
5.4 `index'--search for character in string
|
||
===========================================
|
||
|
||
*Synopsis*
|
||
#include <strings.h>
|
||
char * index(const char *STRING, int C);
|
||
*Description*
|
||
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'.
|
||
|
||
*Returns*
|
||
Returns a pointer to the located character, or a null pointer if C does
|
||
not occur in STRING.
|
||
|
||
*Portability*
|
||
`index' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: memccpy, Next: memchr, Prev: index, Up: Strings
|
||
|
||
5.5 `memccpy'--copy memory regions with end-token check
|
||
=======================================================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
void* memccpy(void *OUT, const void *IN,
|
||
int ENDCHAR, size_t N);
|
||
*Description*
|
||
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.
|
||
|
||
*Returns*
|
||
`memccpy' returns a pointer to the first byte following the ENDCHAR in
|
||
the OUT region. If no byte matching ENDCHAR was copied, then `NULL' is
|
||
returned.
|
||
|
||
*Portability*
|
||
`memccpy' is a GNU extension.
|
||
|
||
`memccpy' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: memchr, Next: memcmp, Prev: memccpy, Up: Strings
|
||
|
||
5.6 `memchr'--find character in memory
|
||
======================================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
void *memchr(const void *SRC, int C, size_t LENGTH);
|
||
*Description*
|
||
This function searches memory starting at `*SRC' for the character C.
|
||
The search only ends with the first occurrence of C, or after LENGTH
|
||
characters; in particular, `NUL' does not terminate the search.
|
||
|
||
*Returns*
|
||
If the character C is found within LENGTH characters of `*SRC', a
|
||
pointer to the character is returned. If C is not found, then `NULL' is
|
||
returned.
|
||
|
||
*Portability*
|
||
`memchr' is ANSI C.
|
||
|
||
`memchr' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: memcmp, Next: memcpy, Prev: memchr, Up: Strings
|
||
|
||
5.7 `memcmp'--compare two memory areas
|
||
======================================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
int memcmp(const void *S1, const void *S2, size_t N);
|
||
*Description*
|
||
This function compares not more than N characters of the object pointed
|
||
to by S1 with the object pointed to by S2.
|
||
|
||
*Returns*
|
||
The function returns an integer greater than, equal to or less than
|
||
zero according to whether the object pointed to by S1 is greater than,
|
||
equal to or less than the object pointed to by S2.
|
||
|
||
*Portability*
|
||
`memcmp' is ANSI C.
|
||
|
||
`memcmp' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: memcpy, Next: memmem, Prev: memcmp, Up: Strings
|
||
|
||
5.8 `memcpy'--copy memory regions
|
||
=================================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
void* memcpy(void *OUT, const void *IN, size_t N);
|
||
*Description*
|
||
This function copies N bytes from the memory region pointed to by IN to
|
||
the memory region pointed to by OUT.
|
||
|
||
If the regions overlap, the behavior is undefined.
|
||
|
||
*Returns*
|
||
`memcpy' returns a pointer to the first byte of the OUT region.
|
||
|
||
*Portability*
|
||
`memcpy' is ANSI C.
|
||
|
||
`memcpy' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: memmem, Next: memmove, Prev: memcpy, Up: Strings
|
||
|
||
5.9 `memmem'--find memory segment
|
||
=================================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
char *memmem(const void *S1, size_t L1, const void *S2,
|
||
size_t L2);
|
||
*Description*
|
||
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'.
|
||
|
||
*Returns*
|
||
Returns a pointer to the located segment, or a null pointer if S2 is
|
||
not found. If L2 is 0, S1 is returned.
|
||
|
||
*Portability*
|
||
`memmem' is a newlib extension.
|
||
|
||
`memmem' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: memmove, Next: mempcpy, Prev: memmem, Up: Strings
|
||
|
||
5.10 `memmove'--move possibly overlapping memory
|
||
================================================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
void *memmove(void *DST, const void *SRC, size_t LENGTH);
|
||
*Description*
|
||
This function moves LENGTH characters from the block of memory starting
|
||
at `*SRC' to the memory starting at `*DST'. `memmove' reproduces the
|
||
characters correctly at `*DST' even if the two areas overlap.
|
||
|
||
*Returns*
|
||
The function returns DST as passed.
|
||
|
||
*Portability*
|
||
`memmove' is ANSI C.
|
||
|
||
`memmove' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: mempcpy, Next: memset, Prev: memmove, Up: Strings
|
||
|
||
5.11 `mempcpy'--copy memory regions and return end pointer
|
||
==========================================================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
void* mempcpy(void *OUT, const void *IN, size_t N);
|
||
*Description*
|
||
This function copies N bytes from the memory region pointed to by IN to
|
||
the memory region pointed to by OUT.
|
||
|
||
If the regions overlap, the behavior is undefined.
|
||
|
||
*Returns*
|
||
`mempcpy' returns a pointer to the byte following the last byte copied
|
||
to the OUT region.
|
||
|
||
*Portability*
|
||
`mempcpy' is a GNU extension.
|
||
|
||
`mempcpy' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: memset, Next: rindex, Prev: mempcpy, Up: Strings
|
||
|
||
5.12 `memset'--set an area of memory
|
||
====================================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
void *memset(void *DST, int C, size_t LENGTH);
|
||
*Description*
|
||
This function converts the argument C into an unsigned char and fills
|
||
the first LENGTH characters of the array pointed to by DST to the value.
|
||
|
||
*Returns*
|
||
`memset' returns the value of DST.
|
||
|
||
*Portability*
|
||
`memset' is ANSI C.
|
||
|
||
`memset' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: rindex, Next: stpcpy, Prev: memset, Up: Strings
|
||
|
||
5.13 `rindex'--reverse search for character in string
|
||
=====================================================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
char * rindex(const char *STRING, int C);
|
||
*Description*
|
||
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'.
|
||
|
||
*Returns*
|
||
Returns a pointer to the located character, or a null pointer if C does
|
||
not occur in STRING.
|
||
|
||
*Portability*
|
||
`rindex' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: stpcpy, Next: stpncpy, Prev: rindex, Up: Strings
|
||
|
||
5.14 `stpcpy'--copy string returning a pointer to its end
|
||
=========================================================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
char *stpcpy(char *DST, const char *SRC);
|
||
*Description*
|
||
`stpcpy' copies the string pointed to by SRC (including the terminating
|
||
null character) to the array pointed to by DST.
|
||
|
||
*Returns*
|
||
This function returns a pointer to the end of the destination string,
|
||
thus pointing to the trailing '\0'.
|
||
|
||
*Portability*
|
||
`stpcpy' is a GNU extension, candidate for inclusion into POSIX/SUSv4.
|
||
|
||
`stpcpy' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: stpncpy, Next: strcasecmp, Prev: stpcpy, Up: Strings
|
||
|
||
5.15 `stpncpy'--counted copy string returning a pointer to its end
|
||
==================================================================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
char *stpncpy(char *DST, const char *SRC, size_t LENGTH);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
This function returns a pointer to the end of the destination string,
|
||
thus pointing to the trailing '\0', or, if the destination string is
|
||
not null-terminated, pointing to dst + n.
|
||
|
||
*Portability*
|
||
`stpncpy' is a GNU extension, candidate for inclusion into POSIX/SUSv4.
|
||
|
||
`stpncpy' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: strcasecmp, Next: strcasestr, Prev: stpncpy, Up: Strings
|
||
|
||
5.16 `strcasecmp'--case-insensitive character string compare
|
||
============================================================
|
||
|
||
*Synopsis*
|
||
#include <strings.h>
|
||
int strcasecmp(const char *A, const char *B);
|
||
*Description*
|
||
`strcasecmp' compares the string at A to the string at B in a
|
||
case-insensitive manner.
|
||
|
||
*Returns*
|
||
If `*A' sorts lexicographically after `*B' (after both are converted to
|
||
lowercase), `strcasecmp' returns a number greater than zero. If the
|
||
two strings match, `strcasecmp' returns zero. If `*A' sorts
|
||
lexicographically before `*B', `strcasecmp' returns a number less than
|
||
zero.
|
||
|
||
*Portability*
|
||
`strcasecmp' is in the Berkeley Software Distribution.
|
||
|
||
`strcasecmp' requires no supporting OS subroutines. It uses
|
||
tolower() from elsewhere in this library.
|
||
|
||
|
||
File: libc.info, Node: strcasestr, Next: strcat, Prev: strcasecmp, Up: Strings
|
||
|
||
5.17 `strcasestr'--case-insensitive character string search
|
||
===========================================================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
char *strcasestr(const char *S, const char *FIND);
|
||
*Description*
|
||
`strcasestr' searchs the string S for the first occurrence of the
|
||
sequence FIND. `strcasestr' is identical to `strstr' except the search
|
||
is case-insensitive.
|
||
|
||
*Returns*
|
||
A pointer to the first case-insensitive occurrence of the sequence FIND
|
||
or `NULL' if no match was found.
|
||
|
||
*Portability*
|
||
`strcasestr' is in the Berkeley Software Distribution.
|
||
|
||
`strcasestr' requires no supporting OS subroutines. It uses
|
||
tolower() from elsewhere in this library.
|
||
|
||
|
||
File: libc.info, Node: strcat, Next: strchr, Prev: strcasestr, Up: Strings
|
||
|
||
5.18 `strcat'--concatenate strings
|
||
==================================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
char *strcat(char *DST, const char *SRC);
|
||
*Description*
|
||
`strcat' appends a copy of 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.
|
||
|
||
*Returns*
|
||
This function returns the initial value of DST
|
||
|
||
*Portability*
|
||
`strcat' is ANSI C.
|
||
|
||
`strcat' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: strchr, Next: strcmp, Prev: strcat, Up: Strings
|
||
|
||
5.19 `strchr'--search for character in string
|
||
=============================================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
char * strchr(const char *STRING, int C);
|
||
*Description*
|
||
This function finds the first occurence of C (converted to a char) in
|
||
the string pointed to by STRING (including the terminating null
|
||
character).
|
||
|
||
*Returns*
|
||
Returns a pointer to the located character, or a null pointer if C does
|
||
not occur in STRING.
|
||
|
||
*Portability*
|
||
`strchr' is ANSI C.
|
||
|
||
`strchr' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: strcmp, Next: strcoll, Prev: strchr, Up: Strings
|
||
|
||
5.20 `strcmp'--character string compare
|
||
=======================================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
int strcmp(const char *A, const char *B);
|
||
*Description*
|
||
`strcmp' compares the string at A to the string at B.
|
||
|
||
*Returns*
|
||
If `*A' sorts lexicographically after `*B', `strcmp' returns a number
|
||
greater than zero. If the two strings match, `strcmp' returns zero.
|
||
If `*A' sorts lexicographically before `*B', `strcmp' returns a number
|
||
less than zero.
|
||
|
||
*Portability*
|
||
`strcmp' is ANSI C.
|
||
|
||
`strcmp' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: strcoll, Next: strcpy, Prev: strcmp, Up: Strings
|
||
|
||
5.21 `strcoll'--locale-specific character string compare
|
||
========================================================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
int strcoll(const char *STRA, const char * STRB);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
If the first string is greater than the second string, `strcoll'
|
||
returns a number greater than zero. If the two strings are equivalent,
|
||
`strcoll' returns zero. If the first string is less than the second
|
||
string, `strcoll' returns a number less than zero.
|
||
|
||
*Portability*
|
||
`strcoll' is ANSI C.
|
||
|
||
`strcoll' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: strcpy, Next: strcspn, Prev: strcoll, Up: Strings
|
||
|
||
5.22 `strcpy'--copy string
|
||
==========================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
char *strcpy(char *DST, const char *SRC);
|
||
*Description*
|
||
`strcpy' copies the string pointed to by SRC (including the terminating
|
||
null character) to the array pointed to by DST.
|
||
|
||
*Returns*
|
||
This function returns the initial value of DST.
|
||
|
||
*Portability*
|
||
`strcpy' is ANSI C.
|
||
|
||
`strcpy' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: strcspn, Next: strerror, Prev: strcpy, Up: Strings
|
||
|
||
5.23 `strcspn'--count characters not in string
|
||
==============================================
|
||
|
||
*Synopsis*
|
||
size_t strcspn(const char *S1, const char *S2);
|
||
*Description*
|
||
This function computes the length of the initial part of the string
|
||
pointed to by S1 which consists entirely of characters NOT from the
|
||
string pointed to by S2 (excluding the terminating null character).
|
||
|
||
*Returns*
|
||
`strcspn' returns the length of the substring found.
|
||
|
||
*Portability*
|
||
`strcspn' is ANSI C.
|
||
|
||
`strcspn' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: strerror, Next: strerror_r, Prev: strcspn, Up: Strings
|
||
|
||
5.24 `strerror'--convert error number to string
|
||
===============================================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
char *strerror(int ERRNUM);
|
||
char *_strerror_r(struct _reent PTR, int ERRNUM,
|
||
int INTERNAL, int *ERROR);
|
||
*Description*
|
||
`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
|
||
|
||
`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
|
||
|
||
`ECHILD'
|
||
No children
|
||
|
||
`ECOMM'
|
||
Communication error
|
||
|
||
`ECONNABORTED'
|
||
Software caused connection abort
|
||
|
||
`ECONNREFUSED'
|
||
Connection refused
|
||
|
||
`EDEADLK'
|
||
Deadlock
|
||
|
||
`EDESTADDRREQ'
|
||
Destination address required
|
||
|
||
`EEXIST'
|
||
File exists
|
||
|
||
`EDOM'
|
||
Math argument
|
||
|
||
`EFAULT'
|
||
Bad address
|
||
|
||
`EFBIG'
|
||
File too large
|
||
|
||
`EHOSTDOWN'
|
||
Host is down
|
||
|
||
`EHOSTUNREACH'
|
||
Host is unreachable
|
||
|
||
`EIDRM'
|
||
Identifier removed
|
||
|
||
`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'
|
||
`.lib' section in a.out corrupted
|
||
|
||
`EMFILE'
|
||
Too many open files
|
||
|
||
`EMLINK'
|
||
Too many links
|
||
|
||
`EMSGSIZE'
|
||
Message too long
|
||
|
||
`EMULTIHOP'
|
||
Multihop attempted
|
||
|
||
`ENAMETOOLONG'
|
||
File or path name too long
|
||
|
||
`ENETDOWN'
|
||
Network interface not configured
|
||
|
||
`ENETUNREACH'
|
||
Network is unreachable
|
||
|
||
`ENFILE'
|
||
Too many open files in system
|
||
|
||
`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
|
||
|
||
`ENOTSOCK'
|
||
Socket operation on non-socket
|
||
|
||
`ENOTSUP'
|
||
Not supported
|
||
|
||
`ENOTTY'
|
||
Not a character device
|
||
|
||
`ENXIO'
|
||
No such device or address
|
||
|
||
`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
|
||
|
||
`ETIME'
|
||
Stream ioctl timeout
|
||
|
||
`ETIMEDOUT'
|
||
Connection timed out
|
||
|
||
`ETXTBSY'
|
||
Text file busy
|
||
|
||
`EXDEV'
|
||
Cross-device link
|
||
|
||
`ECANCELED'
|
||
Operation canceled
|
||
|
||
`ENOTRECOVERABLE'
|
||
State not recoverable
|
||
|
||
`EOWNERDEAD'
|
||
Previous owner died
|
||
|
||
`ESTRPIPE'
|
||
Strings pipe error
|
||
|
||
|
||
`_strerror_r' is a reentrant version of the above.
|
||
|
||
*Returns*
|
||
This function returns a pointer to a string. Your application must not
|
||
modify that string.
|
||
|
||
*Portability*
|
||
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.
|
||
|
||
|
||
File: libc.info, Node: strerror_r, Next: strlen, Prev: strerror, Up: Strings
|
||
|
||
5.25 `strerror_r'--convert error number to string and copy to buffer
|
||
====================================================================
|
||
|
||
*Synopsis*
|
||
#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
|
||
*Description*
|
||
`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'.
|
||
|
||
*Returns*
|
||
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'.
|
||
|
||
*Portability*
|
||
`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.
|
||
|
||
|
||
File: libc.info, Node: strlen, Next: strlwr, Prev: strerror_r, Up: Strings
|
||
|
||
5.26 `strlen'--character string length
|
||
======================================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
size_t strlen(const char *STR);
|
||
*Description*
|
||
The `strlen' function works out the length of the string starting at
|
||
`*STR' by counting chararacters until it reaches a `NULL' character.
|
||
|
||
*Returns*
|
||
`strlen' returns the character count.
|
||
|
||
*Portability*
|
||
`strlen' is ANSI C.
|
||
|
||
`strlen' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: strlwr, Next: strncasecmp, Prev: strlen, Up: Strings
|
||
|
||
5.27 `strlwr'--force string to lowercase
|
||
========================================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
char *strlwr(char *A);
|
||
*Description*
|
||
`strlwr' converts each character in the string at A to lowercase.
|
||
|
||
*Returns*
|
||
`strlwr' returns its argument, A.
|
||
|
||
*Portability*
|
||
`strlwr' is not widely portable.
|
||
|
||
`strlwr' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: strncasecmp, Next: strncat, Prev: strlwr, Up: Strings
|
||
|
||
5.28 `strncasecmp'--case-insensitive character string compare
|
||
=============================================================
|
||
|
||
*Synopsis*
|
||
#include <strings.h>
|
||
int strncasecmp(const char *A, const char * B, size_t LENGTH);
|
||
*Description*
|
||
`strncasecmp' compares up to LENGTH characters from the string at A to
|
||
the string at B in a case-insensitive manner.
|
||
|
||
*Returns*
|
||
If `*A' sorts lexicographically after `*B' (after both are converted to
|
||
lowercase), `strncasecmp' returns a number greater than zero. If the
|
||
two strings are equivalent, `strncasecmp' returns zero. If `*A' sorts
|
||
lexicographically before `*B', `strncasecmp' returns a number less than
|
||
zero.
|
||
|
||
*Portability*
|
||
`strncasecmp' is in the Berkeley Software Distribution.
|
||
|
||
`strncasecmp' requires no supporting OS subroutines. It uses
|
||
tolower() from elsewhere in this library.
|
||
|
||
|
||
File: libc.info, Node: strncat, Next: strncmp, Prev: strncasecmp, Up: Strings
|
||
|
||
5.29 `strncat'--concatenate strings
|
||
===================================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
char *strncat(char *DST, const char *SRC, size_t LENGTH);
|
||
*Description*
|
||
`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
|
||
|
||
*Warnings*
|
||
Note that a null is always appended, so that if the copy is limited by
|
||
the LENGTH argument, the number of characters appended to DST is `n +
|
||
1'.
|
||
|
||
*Returns*
|
||
This function returns the initial value of DST
|
||
|
||
*Portability*
|
||
`strncat' is ANSI C.
|
||
|
||
`strncat' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: strncmp, Next: strncpy, Prev: strncat, Up: Strings
|
||
|
||
5.30 `strncmp'--character string compare
|
||
========================================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
int strncmp(const char *A, const char * B, size_t LENGTH);
|
||
*Description*
|
||
`strncmp' compares up to LENGTH characters from the string at A to the
|
||
string at B.
|
||
|
||
*Returns*
|
||
If `*A' sorts lexicographically after `*B', `strncmp' returns a number
|
||
greater than zero. If the two strings are equivalent, `strncmp'
|
||
returns zero. If `*A' sorts lexicographically before `*B', `strncmp'
|
||
returns a number less than zero.
|
||
|
||
*Portability*
|
||
`strncmp' is ANSI C.
|
||
|
||
`strncmp' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: strncpy, Next: strnlen, Prev: strncmp, Up: Strings
|
||
|
||
5.31 `strncpy'--counted copy string
|
||
===================================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
char *strncpy(char *DST, const char *SRC, size_t LENGTH);
|
||
*Description*
|
||
`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.
|
||
|
||
*Returns*
|
||
This function returns the initial value of DST.
|
||
|
||
*Portability*
|
||
`strncpy' is ANSI C.
|
||
|
||
`strncpy' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: strnlen, Next: strpbrk, Prev: strncpy, Up: Strings
|
||
|
||
5.32 `strnlen'--character string length
|
||
=======================================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
size_t strnlen(const char *STR, size_t N);
|
||
*Description*
|
||
The `strnlen' function works out the length of the string starting at
|
||
`*STR' by counting chararacters until it reaches a NUL character or the
|
||
maximum: N number of characters have been inspected.
|
||
|
||
*Returns*
|
||
`strnlen' returns the character count or N.
|
||
|
||
*Portability*
|
||
`strnlen' is a GNU extension.
|
||
|
||
`strnlen' requires no supporting OS subroutines.
|
||
|
||
|
||
File: libc.info, Node: strpbrk, Next: strrchr, Prev: strnlen, Up: Strings
|
||
|
||
5.33 `strpbrk'--find characters in string
|
||
=========================================
|
||
|
||
*Synopsis*
|
||
#include <string.h>
|
||
char *strpbrk(const char *S1, const char *S2);
|
||
*Description*
|
||
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).
|
||
|
||
*Returns*
|
||
`strpbrk' returns a pointer to the character found in S1, or a null
|
||
pointer if no character from S2 occurs in S1.
|
||
|
||
*Portability*
|
||
`strpbrk' requires no supporting OS subroutines.
|
||
|