[Top] [Contents] [Index] [ ? ]

The Newlib C Library

1. Standard Utility Functions (`stdlib.h')  
2. Character Type Macros and Functions (`ctype.h')  
3. Input and Output (`stdio.h')  

4. Strings and Memory (`string.h')  
5. Wide Character Strings (`wchar.h')  
6. Signal Handling (`signal.h')  

7. Time Functions (`time.h')  
8. Locale (`locale.h')  
9. Reentrancy  

10. Miscellaneous Macros and Functions  
11. System Calls  
12. Variable Argument Lists  

Index  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1. 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'.

1.1 abort---abnormal termination of a program  Abnormal termination of a program
1.2 abs---integer absolute value (magnitude)  Integer absolute value (magnitude)
1.3 assert---Macro for Debugging Diagnostics  Macro for Debugging Diagnostics
1.4 atexit---request execution of functions at program exit  Request execution of functions at program exit
1.5 atof, atoff---string to double or float  String to double or float
1.6 atoi, atol---string to integer  String to integer
1.7 atoll---convert a string to a long long integer  String to long long
1.8 calloc---allocate space for arrays  Allocate space for arrays
1.9 div---divide two integers  Divide two integers
1.12 ecvtbuf, fcvtbuf---double or float to string  Double or float to string of digits
1.10 ecvt,ecvtf,fcvt,fcvtf---double or float to string  Double or float to string of digits (malloc result)
1.13 __env_lock, __env_unlock--lock environ variable  Lock environment list for getenv and setenv
1.11 gvcvt, gcvtf---format double or float as string  Format double or float as string
1.14 exit---end program execution  End program execution
1.15 getenv---look up environment variable  Look up environment variable
1.16 labs---long integer absolute value  Long integer absolute value (magnitude)
1.17 ldiv---divide two long integers  Divide two long integers
1.18 llabs---compute the absolute value of an long long integer.  Long long integer absolute value (magnitude)
1.19 lldiv---divide two long long integers  Divide two long long integers
1.20 malloc, realloc, free---manage memory  Allocate and manage memory (malloc, realloc, free)
1.21 mallinfo, malloc_stats, mallopt--malloc support  Get information about allocated memory
1.22 __malloc_lock, __malloc_unlock--lock malloc pool  Lock memory pool for malloc and free
1.24 mbstowcs---minimal multibyte string to wide char converter  Minimal multibyte string to wide string converter
1.23 mblen---minimal multibyte length function  Minimal multibyte length
1.25 mbtowc---minimal multibyte to wide char converter  Minimal multibyte to wide character converter
1.26 rand, srand---pseudo-random numbers  Pseudo-random numbers
1.27 rand48, drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, lcong48 --pseudo random number generators and initialization routines  Uniformly distributed pseudo-random numbers
1.28 strtod, strtof---string to double or float  String to double or float
1.29 strtol---string to long  String to long
1.30 strtoul---string to unsigned long  String to unsigned long
1.31 system---execute command string  Execute command string
1.32 wcstombs---minimal wide char string to multibyte string converter  Minimal wide string to multibyte string converter
1.33 wctomb---minimal wide char to multibyte converter  Minimal wide character to multibyte converter


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 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

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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.7 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.8 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.9 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.10 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.




[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.11 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.12 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.13 __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 does not do anything. 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.14 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.15 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.16 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.17 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.18 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.19 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.20 malloc, realloc, free---manage memory

Synopsis
 
#include <stdlib.h>
void *malloc(size_t nbytes);
void *realloc(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 _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 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, _free_r, _memalign_r, and _malloc_usable_size_r are reentrant versions. The extra argument reent is a pointer to a reentrancy structure.

If you have multiple threads of execution which may call any of these routines, or if any of these routines may be called reentrantly, then you must provide implementations of the __malloc_lock and __malloc_unlock functions for your system. See the documentation for those functions.

These functions operate by calling the function _sbrk_r or sbrk, which allocates space. You may need to provide one of these functions for your system. _sbrk_r is called with a positive value to allocate more space, and with a negative value to release previously allocated space if it is no longer required. See section 11.1 Definitions for OS interface.


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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.21 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.22 __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 does not do anything. 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.23 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.24 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.25 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.26 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.27 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.28 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 the format:
 
[+|-]digits[.][digits][(e|E)[+|-]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. 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.

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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.29 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.30 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.31 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.32 wcstombs---minimal wide char string to multibyte string converter

Synopsis
 
#include <stdlib.h>
int wcstombs(const char *s, 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.33 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2. 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.

2.1 isalnum---alphanumeric character predicate  Alphanumeric character predicate
2.2 isalpha---alphabetic character predicate  Alphabetic character predicate
2.3 isascii---ASCII character predicate  ASCII character predicate
2.4 iscntrl---control character predicate  Control character predicate
2.5 isdigit---decimal digit predicate  Decimal digit predicate
2.6 islower---lower-case character predicate  Lower-case character predicate
2.7 isprint, isgraph---printable character predicates  Printable character predicates (isprint, isgraph)
2.8 ispunct---punctuation character predicate  Punctuation character predicate
2.9 isspace---whitespace character predicate  Whitespace character predicate
2.10 isupper---uppercase character predicate  Uppercase character predicate
2.11 isxdigit---hexadecimal digit predicate  Hexadecimal digit predicate
2.12 toascii---force integers to ASCII range  Force integers to ASCII range
2.13 tolower---translate characters to lower case  Translate characters to lower case
2.14 toupper---translate characters to upper case  Translate characters to upper case
2.15 iswalnum---alpha-numeric wide-character test  Alphanumeric wide-character predicate
2.16 iswalpha---alphabetic wide-character test  Alphabetic wide-character predicate
2.17 iswcntrl---wide-character cntrl test  Control wide-character predicate
2.18 iswdigit---decimal digit wide-character test  Decimal digit wide-character predicate
2.19 iswgraph---graphic wide-character test  Graphic wide-character predicate
2.20 iswlower---lower-case wide-character test  Lower-case wide-character predicate
2.21 iswprint---printable wide-character test  Printable wide-character predicate
2.22 iswpunct---punctuation wide-character test  Punctuation wide-character predicate
2.23 iswspace---wide-character space test  Whitespace wide-character predicate
2.24 iswupper---upper-case wide-character test  Uppercase wide-character predicate
2.25 iswxdigit---hexadecimal digit wide-character test  Hexadecimal digit wide-character predicate
2.26 iswctype---extensible wide-character test  Extensible wide-character test
2.27 wctype---get wide-character classification type  Compute wide-character test type
2.28 towlower---translate wide-characters to lower case  Translate wide-characters to lower case
2.29 towupper---translate wide-characters to upper case  Translate wide-characters to upper case
2.30 towctrans---extensible wide-character case mapping  Extensible wide-character case mapping
2.31 wctrans---get wide-character translation type  Compute wide-character translation type


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.6 islower---lower-case 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 (lower-case 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 lower case letter (a--z).


Portability
islower is ANSI C.

No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.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 upper-case 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 upper case letter (A-Z).


Portability
isupper is ANSI C.

No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.13 tolower---translate characters to lower case

Synopsis
 
#include <ctype.h>
int tolower(int c);
int _tolower(int c);

Description
tolower is a macro which converts upper-case characters to lower case, 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 lower-case equivalent of c when it is a character between A and Z, and c otherwise.

_tolower returns the lower-case 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.14 toupper---translate characters to upper case

Synopsis
 
#include <ctype.h>
int toupper(int c);
int _toupper(int c);

Description
toupper is a macro which converts lower-case characters to upper case, 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 upper-case equivalent of c when it is a character between a and z, and c otherwise.

_toupper returns the upper-case 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.15 iswalnum---alpha-numeric wide-character test

Synopsis
 
#include <wctype.h>
int iswalnum(wint_t c);

Description
iswalnum is a function which classifies wide-character values that are alpha-numeric.


Returns
iswalnum returns non-zero if c is a alpha-numeric wide-character.


Portability
iswalnum is C99.

No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.17 iswcntrl---wide-character cntrl test

Synopsis
 
#include <wctype.h>
int iswcntrl(wint_t c);

Description
iswcntrl is a function which classifies wide-character values that are categorized as a control character.


Returns
iswcntrl returns non-zero if c is a control wide-character.


Portability
iswcntrl is C99.

No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.18 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.19 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.20 iswlower---lower-case wide-character test

Synopsis
 
#include <wctype.h>
int iswlower(wint_t c);

Description
iswlower is a function which classifies wide-character values that have an upper-case translation.


Returns
iswlower returns non-zero if c is a lower-case wide-character.


Portability
iswlower is C99.

No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.21 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.22 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.23 iswspace---wide-character space test

Synopsis
 
#include <wctype.h>
int iswspace(wint_t c);

Description
iswspace is a function which classifies wide-character values that are categorized as white-space.


Returns
iswspace returns non-zero if c is a white-space wide-character.


Portability
iswspace is C99.

No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.24 iswupper---upper-case wide-character test

Synopsis
 
#include <wctype.h>
int iswupper(wint_t c);

Description
iswupper is a function which classifies wide-character values that have an upper-case translation.


Returns
iswupper returns non-zero if c is a upper-case wide-character.


Portability
iswupper is C99.

No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.25 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.26 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.27 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.28 towlower---translate wide-characters to lower case

Synopsis
 
#include <wctype.h>
wint_t towlower(wint_t c);

Description
towlower is a function which converts upper-case wide-characters to lower case, leaving all other characters unchanged.


Returns
towlower returns the lower-case equivalent of c when it is a upper-case wide-character, otherwise, it returns the input character.


Portability
towlower is C99.

No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.29 towupper---translate wide-characters to upper case

Synopsis
 
#include <wctype.h>
wint_t towupper(wint_t c);

Description
towupper is a function which converts lower-case wide-characters to upper case, leaving all other characters unchanged.


Returns
towupper returns the upper-case equivalent of c when it is a lower-case wide-character, otherwise, it returns the input character.


Portability
towupper is C99.

No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.30 towctrans---extensible wide-character case mapping

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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.31 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3. 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.

When using the small version of the C library, some functionality is removed from the input and output functions. In particular, no file opening or closing is supported, no buffering of output streams, no input streams and no floating point support. For more details on which functions are not supported, please see the entries under each function.

3.1 clearerr---clear file or stream error indicator  Clear file or stream error indicator
3.2 fclose---close a file  Close a file
3.3 feof---test for end of file  Test for end of file
3.4 ferror---test whether read/write error has occurred  Test whether read/write error has occurred
3.5 fflush---flush buffered file output  Flush buffered file output
3.6 fgetc---get a character from a file or stream  Get a character from a file or stream
3.7 fgetpos---record position in a stream or file  Record position in a stream or file
3.8 fgets---get character string from a file or stream  Get character string from a file or stream
3.9 fiprintf---format output to file (integer only)  Write formatted output to file (integer only)
3.10 fopen---open a file  Open a file
3.11 fdopen---turn open file into a stream  Turn an open file into a stream
3.12 fputc---write a character on a stream or file  Write a character on a stream or file
3.13 fputs---write a character string in a file or stream  Write a character string in a file or stream
3.14 fread---read array elements from a file  Read array elements from a file
3.15 freopen---open a file using an existing file descriptor  Open a file using an existing file descriptor
3.16 fseek, fseeko---set file position  Set file position
3.17 fsetpos---restore position of a stream or file  Restore position of a stream or file
3.18 ftell, ftello---return position in a stream or file  Return position in a stream or file
3.19 fwrite---write array elements  Write array elements from memory to a file or stream
3.20 getc---read a character (macro)  Get a character from a file or stream (macro)
3.21 getchar---read a character (macro)  Get a character from standard input (macro)
3.22 gets---get character string (obsolete, use fgets instead)  Get character string from standard input (obsolete)
3.23 getw---read a word (int)  Get a word (int) from a file or stream
3.24 iprintf---write formatted output (integer only)  Write formatted output (integer only)
3.25 mktemp, mkstemp---generate unused file name  Generate unused file name
3.26 perror---print an error message on standard error  Print an error message on standard error
3.27 putc---write a character (macro)  Write a character on a stream or file (macro)
3.28 putchar---write a character (macro)  Write a character on standard output (macro)
3.29 puts---write a character string  Write a character string on standard output
3.30 putw---write a word (int)  Write a word (int) to a file or stream
3.31 remove---delete a file's name  Delete a file's name
3.32 rename---rename a file  Rename a file
3.33 rewind---reinitialize a file or stream  Reinitialize a file or stream
3.34 setbuf---specify full buffering for a file or stream  Specify full buffering for a file or stream
3.35 setvbuf---specify file or stream buffering  Specify buffering for a file or stream
3.36 siprintf---write formatted output (integer only)  Write formatted output (integer only)
3.37 printf, fprintf, asprintf, sprintf, snprintf---format output  Write formatted output
3.38 scanf, fscanf, sscanf---scan and format input  Scan and format input
3.39 tmpfile---create a temporary file  Create a temporary file
3.40 tmpnam, tempnam---name for a temporary file  Generate name for a temporary file
3.41 vprintf, vfprintf, vsprintf---format argument list  Format variable argument list


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2 fclose---close a file

Synopsis
 
#include <stdio.h>
int fclose(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)).


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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3 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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.4 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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5 fflush---flush buffered file output

Synopsis
 
#include <stdio.h>
int fflush(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.


Returns
fflush returns 0 unless it encounters a write error; in that situation, it returns EOF.


Portability
ANSI C requires fflush.

No supporting OS subroutines are required.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.6 fgetc---get a character from a file or stream

Synopsis
 
#include <stdio.h>
int fgetc(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.


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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.7 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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.8 fgets---get character string from a file or stream

Synopsis
 
#include <stdio.h>
char *fgets(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.


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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.9 fiprintf---format output to file (integer only)

Synopsis
 
#include <stdio.h>

int fiprintf(FILE *fd, const char *format, ...);

Description
fiprintf is a restricted version of fprintf: it has the same arguments and behavior, save that it cannot perform any floating-point formatting--the f, g, G, e, and F type specifiers are not recognized.


Returns
fiprintf returns the number of bytes in the output string, save that the concluding NULL is not counted. fiprintf returns when the end of the format string is encountered. If an error occurs, fiprintf returns EOF.


Portability
fiprintf is not required by ANSI C.

Supporting OS subroutines required: close, fstat, isatty, lseek, read, sbrk, write.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.10 fopen---open a file

Synopsis
 
#include <stdio.h>
FILE *fopen(const char *file, const char *mode);

FILE *_fopen_r(void *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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.11 fdopen---turn open file into a stream

Synopsis
 
#include <stdio.h>
FILE *fdopen(int fd, const char *mode);
FILE *_fdopen_r(void *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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.12 fputc---write a character on a stream or file

Synopsis
 
#include <stdio.h>
int fputc(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.


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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.13 fputs---write a character string in a file or stream

Synopsis
 
#include <stdio.h>
int fputs(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.


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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.14 fread---read array elements from a file

Synopsis
 
#include <stdio.h>
size_t fread(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.


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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.15 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.


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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.16 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.17 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, l
    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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.18 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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.19 fwrite---write array elements

Synopsis
 
#include <stdio.h>
size_t fwrite(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.


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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.20 getc---read a character (macro)

Synopsis
 
#include <stdio.h>
int getc(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.


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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.21 getchar---read a character (macro)

Synopsis
 
#include <stdio.h>
int getchar(void);

int _getchar_r(void *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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.22 gets---get character string (obsolete, use fgets instead)

Synopsis
 
#include <stdio.h>

char *gets(char *buf);

char *_gets_r(void *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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.23 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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.24 iprintf---write formatted output (integer only)

Synopsis
 
#include <stdio.h>

int iprintf(const char *format, ...);

Description
iprintf is a restricted version of printf: it has the same arguments and behavior, save that it cannot perform any floating-point formatting: the f, g, G, e, and F type specifiers are not recognized.


Returns
iprintf returns the number of bytes in the output string, save that the concluding NULL is not counted. iprintf returns when the end of the format string is encountered. If an error occurs, iprintf returns EOF.


Portability
iprintf is not required by ANSI C.

Supporting OS subroutines required: close, fstat, isatty, lseek, read, sbrk, write.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.25 mktemp, mkstemp---generate unused file name

Synopsis
 
#include <stdio.h>
char *mktemp(char *path);
int mkstemp(char *path);

char *_mktemp_r(void *reent, char *path);
int *_mkstemp_r(void *reent, char *path);

Description
mktemp and mkstemp attempt to generate a file name that is not yet in use for any existing file. mkstemp creates the file and opens it for reading and writing; mktemp simply generates the file name.

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 some number of `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.

The alternate functions _mktemp_r and _mkstemp_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.

mkstemp returns 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.

Supporting OS subroutines required: getpid, open, stat.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.26 perror---print an error message on standard error

Synopsis
 
#include <stdio.h>
void perror(char *prefix);

void _perror_r(void *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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.27 putc---write a character (macro)

Synopsis
 
#include <stdio.h>
int putc(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.


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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.28 putchar---write a character (macro)

Synopsis
 
#include <stdio.h>
int putchar(int ch);

int _putchar_r(void *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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.29 puts---write a character string

Synopsis
 
#include <stdio.h>
int puts(const char *s);

int _puts_r(void *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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.30 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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.31 remove---delete a file's name

Synopsis
 
#include <stdio.h>
int remove(char *filename);

int _remove_r(void *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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.32 rename---rename a file

Synopsis
 
#include <stdio.h>
int rename(const char *old, const char *new);

int _rename_r(void *reent, 
    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.

The alternate function _rename_r is a reentrant version. The extra argument reent is a pointer to a reentrancy structure.


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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.33 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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.34 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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.35 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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.36 siprintf---write formatted output (integer only)

Synopsis
 
#include <stdio.h>

int siprintf(char *str, const char *format [, arg, ...]);

Description
siprintf is a restricted version of sprintf: it has the same arguments and behavior, save that it cannot perform any floating-point formatting: the f, g, G, e, and F type specifiers are not recognized.


Returns
siprintf returns the number of bytes in the output string, save that the concluding NULL is not counted. siprintf returns when the end of the format string is encountered.


Portability
siprintf is not required by ANSI C.

Supporting OS subroutines required: close, fstat, isatty, lseek, read, sbrk, write.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.37 printf, fprintf, asprintf, sprintf, snprintf---format output

Synopsis
 
#include <stdio.h>

int printf(const char *format [, arg, ...]);
int fprintf(FILE *fd, const char *format [, arg, ...]);
int sprintf(char *str, const char *format [, arg, ...]);
int asprintf(char **strp, const char *format [, arg, ...]);
int snprintf(char *str, size_t size, const char *format [, arg, ...]);

Description
printf accepts a series of arguments, applies to each a format specifier from *format, and writes the formatted data to stdout, terminated with a null 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, asprintf, sprintf and snprintf are identical to printf, other than the destination of the formatted output: fprintf sends the output to a specified file fd, while asprintf stores the output in a dynamically allocated buffer, while sprintf stores the output in the specified char array str and snprintf limits number of characters written to str to at most size (including terminating 0). For sprintf and snprintf, the behavior is undefined if the output *str overlaps with one of the arguments. For asprintf, strp points to a pointer to char which is filled in with the dynamically allocated buffer. format is a pointer to a charater 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:

 
       %[flags][width][.prec][size][type]

The fields of the conversion specification have the following meanings:


Returns
sprintf and asprintf return the number of bytes in the output string, save that the concluding NULL is not counted. printf and fprintf return the number of characters transmitted. If an error occurs, printf and fprintf return EOF and asprintf returns -1. No error returns occur for sprintf.


Portability
The ANSI C standard specifies that implementations must support at least formatted output of up to 509 characters.

Supporting OS subroutines required: close, fstat, isatty, lseek, read, sbrk, write.


Small C Library
When using the small C library, floating point (f, e, E, g, G formats), pointer output (p format) and characters written (n format) are not available.

In addition, all output will be unbuffered.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.38 scanf, fscanf, sscanf---scan and format input

Synopsis
 
#include <stdio.h>

int scanf(const char *format [, arg, ...]);
int fscanf(FILE *fd, const char *format [, arg, ...]);
int sscanf(const char *str, const char *format 
    [, arg, ...]);

int _scanf_r(struct _reent *ptr, const char *format [, arg, ...]);
int _fscanf_r(struct _reent *ptr, FILE *fd, const char *format [, arg, ...]);
int _sscanf_r(struct _reent *ptr, const char *str, const char *format 
    [, arg, ...]);

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, l, and L 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

   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

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:

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:

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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.39 tmpfile---create a temporary file

Synopsis
 
#include <stdio.h>
FILE *tmpfile(void);

FILE *_tmpfile_r(void *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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.40 tmpnam, tempnam---name for a temporary file

Synopsis
 
#include <stdio.h>
char *tmpnam(char *s);
char *tempnam(char *dir, char *pfx);
char *_tmpnam_r(void *reent, char *s);
char *_tempnam_r(void *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.


Small C Library
When using the small C library, these functions are not available.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.41 vprintf, vfprintf, vsprintf---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 vasprintf(char **strp, const char *fmt, va_list list);
int vsnprintf(char *str, size_t size, const char *fmt, va_list list);

int _vprintf_r(void *reent, const char *fmt,
    va_list list);
int _vfprintf_r(void *reent, FILE *fp, const char *fmt,
    va_list list);
int _vasprintf_r(void *reent, char **str, const char *fmt,
    va_list list);
int _vsprintf_r(void *reent, char *str, const char *fmt,
    va_list list);
int _vsnprintf_r(void *reent, char *str, size_t size, const char *fmt,
    va_list list);

Description
vprintf, vfprintf, vasprintf, vsprintf and vsnprintf are (respectively) variants of printf, fprintf, asprintf, sprintf, and snprintf. 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: vasprintf/vsprintf returns the number of bytes in the output string, save that the concluding NULL is not counted. vprintf and vfprintf return the number of characters transmitted. If an error occurs, vprintf and vfprintf return EOF and vasprintf returns -1. No error returns occur for vsprintf.


Portability
ANSI C requires all three functions.

Supporting OS subroutines required: close, fstat, isatty, lseek, read, sbrk, write.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4. 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'.

4.1 bcmp---compare two memory areas  Compare two memory areas
4.2 bcopy---copy memory regions  Copy memory regions
4.3 bzero---initialize memory to zero  Initialize memory to zero
4.4 index---search for character in string  Search for character in string
4.5 memccpy---copy memory regions with end-token check  Copy memory regions up to end-token
4.6 memchr---find character in memory  Find character in memory
4.7 memcmp---compare two memory areas  Compare two memory areas
4.8 memcpy---copy memory regions  Copy memory regions
4.9 memmove---move possibly overlapping memory  Move possibly overlapping memory
4.10 mempcpy---copy memory regions and return end pointer  Copy memory regions and locate end
4.11 memset---set an area of memory  Set an area of memory
4.12 rindex---reverse search for character in string  Reverse search for character in string
4.13 strcasecmp---case insensitive character string compare  Compare strings ignoring case
4.14 strcat---concatenate strings  Concatenate strings
4.15 strchr---search for character in string  Search for character in string
4.16 strcmp---character string compare  Character string compare
4.17 strcoll---locale specific character string compare  Locale specific character string compare
4.18 strcpy---copy string  Copy string
4.19 strcspn---count chars not in string  Count chars not in string
4.20 strerror---convert error number to string  Convert error number to string
4.21 strlen---character string length  Character string length
4.22 strlwr---force string to lower case  Convert string to lower case
4.23 strncasecmp---case insensitive character string compare  Compare strings ignoring case
4.24 strncat---concatenate strings  Concatenate strings
4.25 strncmp---character string compare  Character string compare
4.26 strncpy---counted copy string  Counted copy string
4.27 strpbrk---find chars in string  Find chars in string
4.28 strrchr---reverse search for character in string  Reverse search for character in string
4.29 strspn---find initial match  Find initial match
4.30 strstr---find string segment  Find string segment
4.31 strtok,strtok_r,strsep---get next token from a string  Get next token from a string
4.32 strupr---force string to uppercase  Convert string to upper case
4.33 strxfrm---transform string  Transform string
4.34 swab---swap adjacent bytes  Swap adjacent bytes


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1 bcmp---compare two memory areas

Synopsis
 
#include <string.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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2 bcopy---copy memory regions

Synopsis
 
#include <string.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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3 bzero---initialize memory to zero

Synopsis
 
#include <string.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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.4 index---search for character in string

Synopsis
 
#include <string.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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.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, NULL 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.9 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.10 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.11 memset---set an area of memory

Synopsis
 
#include <string.h>
void *memset(const 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 m.


Portability
memset is ANSI C.

memset requires no supporting OS subroutines.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.12 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.13 strcasecmp---case insensitive character string compare

Synopsis
 
#include <string.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 upper case), 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.14 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.15 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.16 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.17 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.18 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.19 strcspn---count chars 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.20 strerror---convert error number to string

Synopsis
 
#include <string.h>
char *strerror(int errnum);

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':

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


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, ANSI C declares that subsequent calls to strerror may overwrite the result string; therefore portable code cannot depend on the reentrancy of this subroutine.

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 errnum as its argument.

_user_strerror takes one argument of type int, and returns a character pointer. If errnum is unknown to _user_strerror, _user_strerror returns NULL. The default _user_strerror returns NULL for all input values.

strerror requires no supporting OS subroutines.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.21 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.22 strlwr---force string to lower case

Synopsis
 
#include <string.h>
char *strlwr(char *a);

Description
strlwr converts each characters in the string at a to lower case.


Returns
strlwr returns its argument, a.


Portability
strlwr is not widely portable.

strlwr requires no supporting OS subroutines.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.23 strncasecmp---case insensitive character string compare

Synopsis
 
#include <string.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 upper case), 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.24 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.25 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.26 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.27 strpbrk---find chars 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.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.28 strrchr---reverse search for character in string

Synopsis
 
#include <string.h>
char * strrchr(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).


Returns
Returns a pointer to the located character, or a null pointer if c does not occur in string.


Portability
strrchr is ANSI C.

strrchr requires no supporting OS subroutines.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.29 strspn---find initial match

Synopsis
 
#include <string.h>
size_t strspn(const char *s1, const char *s2);

Description
This function computes the length of the initial segment of the string pointed to by s1 which consists entirely of characters from the string pointed to by s2 (excluding the terminating null character).


Returns
strspn returns the length of the segment found.


Portability
strspn is ANSI C.

strspn requires no supporting OS subroutines.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.30 strstr---find string segment

Synopsis
 
#include <string.h>
char *strstr(const char *s1, const char *s2);

Description
Locates the first occurence in the string pointed to by s1 of the sequence of characters in the string pointed to by s2 (excluding the terminating null character).


Returns
Returns a pointer to the located string segment, or a null pointer if the string s2 is not found. If s2 points to a string with zero length, the s1 is returned.


Portability
strstr is ANSI C.

strstr requires no supporting OS subroutines.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.31 strtok,strtok_r,strsep---get next token from a string

Synopsis
 
#include <string.h>
char *strtok(char *source, const char *delimiters)
char *strtok_r(char *source, const char *delimiters,
    char **lasts)
char *strsep(char **source_ptr, const char *delimiters)

Description
The strtok function is used to isolate sequential tokens in a null-terminated string, *source. These tokens are delimited in the string by at least one of the characters in *delimiters. The first time that strtok is called, *source should be specified; subsequent calls, wishing to obtain further tokens from the same string, should pass a null pointer instead. The separator string, *delimiters, must be supplied each time, and may change between calls.

The strtok function returns a pointer to the beginning of each subsequent token in the string, after replacing the separator character itself with a NUL character. When no more tokens remain, a null pointer is returned.

The strtok_r function has the same behavior as strtok, except a pointer to placeholder *[lasts> must be supplied by the caller.

The strsep function is similar in behavior to strtok, except a pointer to the string pointer must be supplied [source_ptr> and the function does not skip leading delimeters. When the string starts with a delimeter, the delimeter is changed to the NUL character and the empty string is returned. Like strtok_r and strtok, the *[source_ptr> is updated to the next character following the last delimeter found or NULL if the end of string is reached with no more delimeters.


Returns
strtok, strtok_r, and strsep all return a pointer to the next token, or NULL if no more tokens can be found. For strsep, a token may be the empty string.


Portability
strtok is ANSI C. strtok_r is POSIX. strsep is a BSD-extension.

strtok, strtok_r, and strsep require no supporting OS subroutines.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.32 strupr---force string to uppercase

Synopsis
 
#include <string.h>
char *strupr(char *a);

Description
strupr converts each characters in the string at a to upper case.


Returns
strupr returns its argument, a.


Portability
strupr is not widely portable.

strupr requires no supporting OS subroutines.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.33 strxfrm---transform string

Synopsis
 
#include <string.h>
size_t strxfrm(char *s1, const char *s2, size_t n);

Description
This function transforms the string pointed to by s2 and places the resulting string into the array pointed to by s1. The transformation is such that if the strcmp function is applied to the two transformed strings, it returns a value greater than, equal to, or less than zero, correspoinding to the result of a strcoll function applied to the same two original strings.

No more than n characters are placed into the resulting array pointed to by s1, including the terminating null character. If n is zero, s1 may be a null pointer. If copying takes place between objects that overlap, the behavior is undefined.

With a C locale, this function just copies.


Returns
The strxfrm function returns the length of the transformed string (not including the terminating null character). If the value returned is n or more, the contents of the array pointed to by s1 are indeterminate.


Portability
strxfrm is ANSI C.

strxfrm requires no supporting OS subroutines.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.34 swab---swap adjacent bytes

Synopsis
 
#include <unistd.h>
void swab(const void *in, void *out, ssize_t n);

Description
This function copies n bytes from the memory region pointed to by in to the memory region pointed to by out, exchanging adjacent even and odd bytes.


Portability
swab requires no supporting OS subroutines.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5. Wide Character Strings (`wchar.h')

This chapter describes wide-character string-handling functions and managing areas of memory containing wide-characters. The corresponding declarations are in `wchar.h'.

5.1 wmemchr---find a wide-character in memory  Find wide-character in memory
5.2 wmemcmp---compare wide-characters in memory  Compare two wide-character memory areas
5.3 wmemcpy---copy wide-characters in memory  Copy wide-character memory regions
5.4 wmemmove---wmemmove - copy wide-characters in memory with overlapping areas  Move possibly overlapping wide-character memory
5.5 wmemset---set wide-characters in memory  Set an area of memory to a specified wide-character
5.6 wcscat---concatenate two wide-character strings  Concatenate wide-character strings
5.7 wcschr---wide-character string scanning operation  Search for wide-character in string
5.8 wcscmp---compare two wide-character strings  Wide-character string compare
5.9 wcscoll---locale specific wide-character string compare  Locale specific Wide-character string compare
5.10 wcscpy---copy a wide-character string  Copy wide-character string
5.11 wcscspn---get length of a complementary wide substring  Count wide-chars not in string
5.12 wcslcat---concatenate wide-character strings to specified length  Concatenate wide-character strings to specified length
5.13 wcslcpy---copy a wide-character string to specified length  Copy wide-character string to specified length
5.14 wcslen---get wide-character string length  Wide-character string length
5.15 wcsncat---concatenate part of two wide-character strings  Concatenate wide-character strings
5.16 wcsncmp---compare part of two wide-character strings  Wide-character string compare
5.17 wcsncpy---copy part of a wide-character string  Counted copy wide-character string
5.18 wcsnlen---get fixed-size wide character string length  Wide-character string length with maximum limit
5.19 wcspbrk----scan wide-character string for a wide-character code  Find wide-chars in string
5.20 wcsrchr---wide-character string scanning operation  Reverse search for wide-character in string
5.21 wcsspn---get length of a wide substring  Find initial match in wide-character string
5.22 wcsstr---find a wide-character substring  Find wide-character string segment
5.23 wcswidth---number of column positions of a wide-character string  Number of column positions of a wide-character string
5.24 wcwidth---number of column positions of a wide-character code  Number of column positions of a wide-character code


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.1 wmemchr---find a wide-character in memory

Synopsis
 
#include <wchar.h>
wchar_t	*wmemchr(const wchar_t *s, wchar_t c, size_t n);

Description
The wmemchr function locates the first occurrence of c in the initial n wide-characters of the object pointed to be s. This function is not affected by locale and all wchar_t values are treated identically. The null wide-character and wchar_t values not corresponding to valid characters are not treated specially.

If n is zero, s must be a valid pointer and the function behaves as if no valid occurrence of c is found.


Returns
The wmemchr function returns a pointer to the located wide-character, or a null pointer if the wide-character does not occur in the object.


Portability
wmemchr is ISO/IEC 9899/AMD1:1995 (ISO C). No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.2 wmemcmp---compare wide-characters in memory

Synopsis
 
#include <wchar.h>
int wmemcmp(const wchar_t *s1, const wchar_t *s2, size_t n);

Description
The wmemcmp function compares the first n wide-characters of the object pointed to by s1 to the first n wide-characters of the object pointed to by s2. This function is not affected by locale and all wchar_t values are treated identically. The null wide-character and wchar_t values not corresponding to valid characters are not treated specially.

If n is zero, s1 and s2 must be a valid pointers and the function behaves as if the two objects compare equal.


Returns
The wmemcmp function returns an integer greater than, equal to, or less than zero, accordingly as the object pointed to by s1 is greater than, equal to, or less than the object pointed to by s2.


Portability
wmemcmp is ISO/IEC 9899/AMD1:1995 (ISO C). No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.3 wmemcpy---copy wide-characters in memory

Synopsis
 
#include <wchar.h>
wchar_t *wmemcpy(wchar_t *d, const wchar_t *s, size_t n);

Description
The wmemcpy function copies n wide-characters from the object pointed to by s to the object pointed to be d. This function is not affected by locale and all wchar_t values are treated identically. The null wide-character and wchar_t values not corresponding to valid characters are not treated specially.

If n is zero, d and s must be a valid pointers, and the function copies zero wide-characters.


Returns
The wmemcpy function returns the value of d.


Portability
wmemcpy is ISO/IEC 9899/AMD1:1995 (ISO C). No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4 wmemmove---wmemmove - copy wide-characters in memory with overlapping areas

Synopsis
 
#include <wchar.h>
wchar_t *wmemmove(wchar_t *d, const wchar_t *s, size_t n);

Description
The wmemmove function copies n wide-characters from the object pointed to by s to the object pointed to by d. Copying takes place as if the n wide-characters from the object pointed to by s are first copied into a temporary array of n wide-characters that does not overlap the objects pointed to by d or s, and then the n wide-characters from the temporary array are copied into the object pointed to by d.

This function is not affected by locale and all wchar_t values are treated identically. The null wide-character and wchar_t values not corresponding to valid characters are not treated specially.

If n is zero, d and s must be a valid pointers, and the function copies zero wide-characters.


Returns
The wmemmove function returns the value of d.


Portability
wmemmove is ISO/IEC 9899/AMD1:1995 (ISO C). No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.5 wmemset---set wide-characters in memory

Synopsis
 
#include <wchar.h>
wchar_t *wmemset(wchar_t *s, wchar_t c, size_t n);

Description
The wmemset function copies the value of c into each of the first n wide-characters of the object pointed to by s. This function is not affected by locale and all wchar_t values are treated identically. The null wide-character and wchar_t values not corresponding to valid characters are not treated specially.

If n is zero, s must be a valid pointer and the function copies zero wide-characters.


Returns
The wmemset functions returns the value of s.


Portability
wmemset is ISO/IEC 9899/AMD1:1995 (ISO C). No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.6 wcscat---concatenate two wide-character strings

Synopsis
 
#include <wchar.h>
wchar_t *wcscat(wchar_t *s1, const wchar_t *s2);

Description
The wcscat function appends a copy of the wide-character string pointed to by s2 (including the terminating null wide-character code) to the end of the wide-character string pointed to by s1. The initial wide-character code of s2 overwrites the null wide-character code at the end of s1. If copying takes place between objects that overlap, the behaviour is undefined.


Returns
The wcscat function returns s1; no return value is reserved to indicate an error.


Portability
wcscat is ISO/IEC 9899/AMD1:1995 (ISO C). No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.7 wcschr---wide-character string scanning operation

Synopsis
 
#include <wchar.h>
wchar_t *wcschr(const wchar_t *s, wchar_t c);

Description
The wcschr function locates the first occurrence of c in the wide-character string pointed to by s. The value of c must be a character representable as a type wchar_t and must be a wide-character code corresponding to a valid character in the current locale. The terminating null wide-character string.


Returns
Upon completion, wcschr returns a pointer to the wide-character code, or a null pointer if the wide-character code is not found.


Portability
wcschr is ISO/IEC 9899/AMD1:1995 (ISO C). No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.8 wcscmp---compare two wide-character strings

Synopsis
 
#include <wchar.h>
int wcscmp(const wchar_t *s1, *s2);

Description
The wcscmp function compares the wide-character string pointed to by s1 to the wide-character string pointed to by s2.

The sign of a non-zero return value is determined by the sign of the difference between the values of the first pair of wide-character codes that differ in the objects being compared.


Returns
Upon completion, wcscmp returns an integer greater than, equal to or less than 0, if the wide-character string pointed to by s1 is greater than, equal to or less than the wide-character string pointed to by s2 respectively.


Portability
wcscmp is ISO/IEC 9899/AMD1:1995 (ISO C). No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.9 wcscoll---locale specific wide-character string compare

Synopsis
 
#include <wchar.h>
int wcscoll(const wchar_t *stra, const wchar_t * strb);

Description
wcscoll compares the wide-character string pointed to by stra to the wide-character string pointed to by strb, using an interpretation appropriate to the current LC_COLLATE state.

The current implementation of wcscoll simply uses wcscmp and does not support any language-specific sorting.


Returns
If the first string is greater than the second string, wcscoll returns a number greater than zero. If the two strings are equivalent, wcscoll returns zero. If the first string is less than the second string, wcscoll returns a number less than zero.


Portability
wcscoll is ISO/IEC 9899/AMD1:1995 (ISO C).



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.10 wcscpy---copy a wide-character string

Synopsis
 
#include <wchar.h>
wchar_t *wcscpy(wchar_t *s1, const wchar_t *,s2);

Description
The wcscpy function copies the wide-character string pointed to by s2 (including the terminating null wide-character code) into the array pointed to by s1. If copying takes place between objects that overlap, the behaviour is undefined.


Returns
The wcscpy function returns s1; no return value is reserved to indicate an error.


Portability
wcscpy is ISO/IEC 9899/AMD1:1995 (ISO C). No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.11 wcscspn---get length of a complementary wide substring

Synopsis
 
#include <wchar.h>
size_t wcscspn(const wchar_t *s, wchar_t *set);

Description
The wcscspn function computes the length of the maximum initial segment of the wide-character string pointed to by s which consists entirely of wide-character codes not from the wide-character string pointed to by set.


Returns
The wcscspn function returns the length of the initial substring of s1; no return value is reserved to indicate an error.


Portability
wcscspn is ISO/IEC 9899/AMD1:1995 (ISO C). No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.12 wcslcat---concatenate wide-character strings to specified length

Synopsis
 
#include <wchar.h>
size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t siz);

Description
The wcslcat function appends wide-characters from src to end of the dst wide-character string so that the resultant wide-character string is not more than siz wide-characters including terminating null wide-character code. A terminating null wide-character is always added unless siz is 0. Thus, the maximum number of wide-characters that can be appended from src is siz - 1. If copying takes place between objects that overlap, the behaviour is undefined.


Returns
Wide-character string length of initial dst plus the wide-character string length of src (does not include terminating null wide-characters). If the return value is greater than or equal to siz, then truncation occurred and not all wide-characters from src were appended.


Portability
No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.13 wcslcpy---copy a wide-character string to specified length

Synopsis
 
#include <wchar.h>
size_t wcslcpy(wchar_t *dst, const wchar_t *src, size_t siz);

Description
wcslcpy copies wide-characters from src to dst such that up to siz - 1 characters are copied. A terminating null is appended to the result, unless siz is zero.


Returns
wcslcpy returns the number of wide-characters in src, not including the terminating null wide-character. If the return value is greater than or equal to siz, then not all wide-characters were copied from src and truncation occurred.


Portability
No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.14 wcslen---get wide-character string length

Synopsis
 
#include <wchar.h>
size_t wcslen(const wchar_t *s);

Description
The wcslen function computes the number of wide-character codes in the wide-character string to which s points, not including the terminating null wide-character code.


Returns
The wcslen function returns the length of s; no return value is reserved to indicate an error.


Portability
wcslen is ISO/IEC 9899/AMD1:1995 (ISO C). No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.15 wcsncat---concatenate part of two wide-character strings

Synopsis
 
#include <wchar.h>
wchar_t *wcsncat(wchar_t *s1, const wchar_t *s2, size_t n);

Description
The wcsncat function appends not more than n wide-character codes (a null wide-character code and wide-character codes that follow it are not appended) from the array pointed to by s2 to the end of the wide-character string pointed to by s1. The initial wide-character code of s2 overwrites the null wide-character code at the end of s1. A terminating null wide-character code is always appended to the result. If copying takes place between objects that overlap, the behaviour is undefined.


Returns
The wcsncat function returns s1; no return value is reserved to indicate an error.


Portability
wcsncat is ISO/IEC 9899/AMD1:1995 (ISO C). No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.16 wcsncmp---compare part of two wide-character strings

Synopsis
 
#include <wchar.h>
int wcsncmp(const wchar_t *s1, const wchar_t *s2, size_t n);

Description
The wcsncmp function compares not more than n wide-character codes (wide-character codes that follow a null wide-character code are not compared) from the array pointed to by s1 to the array pointed to by s2.

The sign of a non-zero return value is determined by the sign of the difference between the values of the first pair of wide-character codes that differ in the objects being compared.


Returns
Upon successful completion, wcsncmp returns an integer greater than, equal to or less than 0, if the possibly null-terminated array pointed to by s1 is greater than, equal to or less than the possibly null-terminated array pointed to by s2 respectively.


Portability
wcsncmp is ISO/IEC 9899/AMD1:1995 (ISO C). No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.17 wcsncpy---copy part of a wide-character string

Synopsis
 
#include <wchar.h>
wchar_t *wcsncpy(wchar_t *s1, const wchar_t *s2, size_t n);

Description
The wcsncpy function copies not more than n wide-character codes (wide-character codes that follow a null wide-character code are not copied) from the array pointed to by s2 to the array pointed to by s1. If copying takes place between objects that overlap, the behaviour is undefined.

If the array pointed to by s2 is a wide-character string that is shorter than n wide-character codes, null wide-character codes are appended to the copy in the array pointed to by s1, until n wide-character codes in all are written.


Returns
The wcsncpy function returns s1; no return value is reserved to indicate an error.


Portability
wcsncpy is ISO/IEC 9899/AMD1:1995 (ISO C). No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.18 wcsnlen---get fixed-size wide character string length

Synopsis
 
#include <wchar.h>
size_t wcsnlen(const wchar_t *s, size_t maxlen);

Description
The wcsnlen function computes the number of wide character codes in the wide character string pointed to by s not including the terminating L'\0' wide character but at most maxlen wide characters.


Returns
wcsnlen returns the length of s if it is less then maxlen, or maxlen if there is no L'\0' wide character in first maxlen characters.


Portability
wcsnlen is GNU extension.. wcsnlen requires no supporting OS subroutines.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.19 wcspbrk----scan wide-character string for a wide-character code

Synopsis
 
#include <wchar.h>
wchar_t *wcspbrk(const wchar_t *s, const wchar_t *set);

Description
The wcspbrk function locates the first occurrence in the wide-character string pointed to by s of any wide-character code from the wide-character string pointed to by set.


Returns
Upon successful completion, wcspbrk returns a pointer to the wide-character code or a null pointer if no wide-character code from set occurs in s.


Portability
wcspbrk is ISO/IEC 9899/AMD1:1995 (ISO C). No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.20 wcsrchr---wide-character string scanning operation

Synopsis
 
#include <wchar.h>
wchar_t *wcsrchr(const wchar_t *s, wchar_t c);

Description
The wcsrchr function locates the last occurrence of c in the wide-character string pointed to by s. The value of c must be a character representable as a type wchar_t and must be a wide-character code corresponding to a valid character in the current locale. The terminating null wide-character code is considered to be part of the wide-character string.


Returns
Upon successful completion, wcsrchr returns a pointer to the wide-character code or a null pointer if c does not occur in the wide-character string.


Portability
wcsrchr is ISO/IEC 9899/AMD1:1995 (ISO C). No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.21 wcsspn---get length of a wide substring

Synopsis
 
#include <wchar.h>
size_t wcsspn(const wchar_t *s, const wchar_t *set);

Description
The wcsspn function computes the length of the maximum initial segment of the wide-character string pointed to by s which consists entirely of wide-character codes from the wide-character string pointed to by set.


Returns
The wcsspn() function returns the length s1; no return value is reserved to indicate an error.


Portability
wcsspn is ISO/IEC 9899/AMD1:1995 (ISO C). No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.22 wcsstr---find a wide-character substring

Synopsis
 
#include <wchar.h>
wchar_t *wcsstr(const wchar_t *big, const wchar_t *little);

Description
The wcsstr function locates the first occurrence in the wide-character string pointed to by big of the sequence of wide-characters (excluding the terminating null wide-character) in the wide-character string pointed to by little.


Returns
On successful completion, wcsstr returns a pointer to the located wide-character string, or a null pointer if the wide-character string is not found.

If little points to a wide-character string with zero length, the function returns big.


Portability
wcsstr is ISO/IEC 9899/AMD1:1995 (ISO C).



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.23 wcswidth---number of column positions of a wide-character string

Synopsis
 
#include <wchar.h>
int wcswidth(const wchar_t *pwcs, size_t n);

Description
The wcswidth function shall determine the number of column positions required for n wide-character codes (or fewer than n wide-character codes if a null wide-character code is encountered before n wide-character codes are exhausted) in the string pointed to by pwcs.


Returns
The wcswidth function either shall return 0 (if pwcs points to a null wide-character code), or return the number of column positions to be occupied by the wide-character string pointed to by pwcs, or return -1 (if any of the first n wide-character codes in the wide-character string pointed to by pwcs is not a printable wide-character code).


Portability
wcswidth has been introduced in the Single UNIX Specification Volume 2 wcswidth has been marked as extension in Single UNIX Specification Volume 3



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.24 wcwidth---number of column positions of a wide-character code

Synopsis
 
#include <wchar.h>
int wcwidth(const wchar_t wc);

Description
The wcwidth function shall determine the number of column positions required for the wide character wc. The application shall ensure that the value of wc is a character representable as a wchar_t, and is a wide-character code corresponding to a valid character in the current locale.


Returns
The wcwidth function shall either return 0 (if wc is a null wide-character code), or return the number of column positions to be occupied by the wide-character code wc, or return -1 (if wc does not correspond to a printable wide-character code).

The current implementation of wcwidth simply sets the width of all printable characters to 1 since newlib has no character tables around.


Portability
wcwidth has been introduced in the Single UNIX Specification Volume 2 wcwidth has been marked as extension in Single UNIX Specification Volume 3



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6. Signal Handling (`signal.h')

A signal is an event that interrupts the normal flow of control in your program. Your operating environment normally defines the full set of signals available (see `sys/signal.h'), as well as the default means of dealing with them--typically, either printing an error message and aborting your program, or ignoring the signal.

All systems support at least the following signals:

SIGABRT
Abnormal termination of a program; raised by the <<abort>> function.

SIGFPE
A domain error in arithmetic, such as overflow, or division by zero.

SIGILL
Attempt to execute as a function data that is not executable.

SIGINT
Interrupt; an interactive attention signal.

SIGSEGV
An attempt to access a memory location that is not available.

SIGTERM
A request that your program end execution.

Two functions are available for dealing with asynchronous signals--one to allow your program to send signals to itself (this is called raising a signal), and one to specify subroutines (called handlers to handle particular signals that you anticipate may occur--whether raised by your own program or the operating environment.

To support these functions, `signal.h' defines three macros:

SIG_DFL
Used with the signal function in place of a pointer to a handler subroutine, to select the operating environment's default handling of a signal.

SIG_IGN
Used with the signal function in place of a pointer to a handler, to ignore a particular signal.

SIG_ERR
Returned by the signal function in place of a pointer to a handler, to indicate that your request to set up a handler could not be honored for some reason.

`signal.h' also defines an integral type, sig_atomic_t. This type is not used in any function declarations; it exists only to allow your signal handlers to declare a static storage location where they may store a signal value. (Static storage is not otherwise reliable from signal handlers.)

6.1 raise---send a signal  Send a signal
6.2 signal---specify handler subroutine for a signal  Specify handler subroutine for a signal


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.1 raise---send a signal

Synopsis
 
#include <signal.h>
int raise(int sig);

int _raise_r(void *reent, int sig);

Description
Send the signal sig (one of the macros from `sys/signal.h'). This interrupts your program's normal flow of execution, and allows a signal handler (if you've defined one, using signal) to take control.

The alternate function _raise_r is a reentrant version. The extra argument reent is a pointer to a reentrancy structure.


Returns
The result is 0 if sig was successfully raised, 1 otherwise. However, the return value (since it depends on the normal flow of execution) may not be visible, unless the signal handler for sig terminates with a return or unless SIG_IGN is in effect for this signal.


Portability
ANSI C requires raise, but allows the full set of signal numbers to vary from one implementation to another.

Required OS subroutines: getpid, kill.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.2 signal---specify handler subroutine for a signal

Synopsis
 
#include <signal.h>
void ( * signal(int sig, void(*func)(int)) )(int);

void ( * _signal_r(void *reent, 
    int sig, void(*func)(int)) )(int);

int raise (int sig);

int _raise_r (void *reent, int sig);

Description
signal, raise provide a simple signal/raise implementation for embedded targets.

signal allows you to request changed treatment for a particular signal sig. You can use one of the predefined macros SIG_DFL (select system default handling) or SIG_IGN (ignore this signal) as the value of func; otherwise, func is a function pointer that identifies a subroutine in your program as the handler for this signal.

Some of the execution environment for signal handlers is unpredictable; notably, the only library function required to work correctly from within a signal handler is signal itself, and only when used to redefine the handler for the current signal value.

Static storage is likewise unreliable for signal handlers, with one exception: if you declare a static storage location as `volatile sig_atomic_t', then you may use that location in a signal handler to store signal values.

If your signal handler terminates using return (or implicit return), your program's execution continues at the point where it was when the signal was raised (whether by your program itself, or by an external event). Signal handlers can also use functions such as exit and abort to avoid returning.

raise sends the signal sig to the executing program. It returns zero if successful, non-zero if unsuccessful.

The alternate functions _signal_r, _raise_r are the reentrant versions. The extra argument reent is a pointer to a reentrancy structure.


Returns
If your request for a signal handler cannot be honored, the result is SIG_ERR; a specific error number is also recorded in errno.

Otherwise, the result is the previous handler (a function pointer or one of the predefined macros).


Portability
ANSI C requires raise, signal.

No supporting OS subroutines are required to link with signal, but it will not have any useful effects, except for software generated signals, without an operating system that can actually raise exceptions.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7. Time Functions (`time.h')

This chapter groups functions used either for reporting on time (elapsed, current, or compute time) or to perform calculations based on time.

The header file `time.h' defines three types. clock_t and time_t are both used for representations of time particularly suitable for arithmetic. (In this implementation, quantities of type clock_t have the highest resolution possible on your machine, and quantities of type time_t resolve to seconds.) size_t is also defined if necessary for quantities representing sizes.

`time.h' also defines the structure tm for the traditional representation of Gregorian calendar time as a series of numbers, with the following fields:

tm_sec
Seconds.

tm_min
Minutes.

tm_hour
Hours.

tm_mday
Day.

tm_mon
Month.

tm_year
Year (since 1900).

tm_wday
Day of week: the number of days since Sunday.

tm_yday
Number of days elapsed since last January 1.

tm_isdst
Daylight Savings Time flag: positive means DST in effect, zero means DST not in effect, negative means no information about DST is available.

7.1 asctime---format time as string  Format time as string
7.2 clock---cumulative processor time  Cumulative processor time
7.3 ctime---convert time to local and format as string  Convert time to local and format as string
7.4 difftime---subtract two times  Subtract two times
7.5 gmtime---convert time to UTC traditional form  Convert time to UTC (GMT) traditional representation
7.6 localtime---convert time to local representation  Convert time to local representation
7.7 mktime---convert time to arithmetic representation  Convert time to arithmetic representation
7.8 strftime---flexible calendar time formatter  Flexible calendar time formatter
7.9 time---get current calendar time (as single number)  Get current calendar time (as single number)
7.10 tzset---set timezone characteristics from TZ environment variable  Set timezone info


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.1 asctime---format time as string

Synopsis
 
#include <time.h>
char *asctime(const struct tm *clock);
char *asctime_r(const struct tm *clock, char *buf);

Description
Format the time value at clock into a string of the form
 
 Wed Jun 15 11:38:07 1988\n\0
The string is generated in a static buffer; each call to asctime overwrites the string generated by previous calls.


Returns
A pointer to the string containing a formatted timestamp.


Portability
ANSI C requires asctime.

asctime requires no supporting OS subroutines.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.2 clock---cumulative processor time

Synopsis
 
#include <time.h>
clock_t clock(void);

Description
Calculates the best available approximation of the cumulative amount of time used by your program since it started. To convert the result into seconds, divide by the macro CLOCKS_PER_SEC.


Returns
The amount of processor time used so far by your program, in units defined by the machine-dependent macro CLOCKS_PER_SEC. If no measurement is available, the result is (clock_t)-1.


Portability
ANSI C requires clock and CLOCKS_PER_SEC.

Supporting OS subroutine required: times.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.3 ctime---convert time to local and format as string

Synopsis
 
#include <time.h>
char *ctime(const time_t *clock);
char *ctime_r(const time_t *clock, char *buf);

Description
Convert the time value at clock to local time (like localtime) and format it into a string of the form
 
 Wed Jun 15 11:38:07 1988\n\0
(like asctime).


Returns
A pointer to the string containing a formatted timestamp.


Portability
ANSI C requires ctime.

ctime requires no supporting OS subroutines.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.4 difftime---subtract two times

Synopsis
 
#include <time.h>
double difftime(time_t tim1, time_t tim2);

Description
Subtracts the two times in the arguments: `tim1 - tim2'.


Returns
The difference (in seconds) between tim2 and tim1, as a double.


Portability
ANSI C requires difftime, and defines its result to be in seconds in all implementations.

difftime requires no supporting OS subroutines.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.5 gmtime---convert time to UTC traditional form

Synopsis
 
#include <time.h>
struct tm *gmtime(const time_t *clock);
struct tm *gmtime_r(const time_t *clock, struct tm *res);

Description
gmtime assumes the time at clock represents a local time. gmtime converts it to UTC (Universal Coordinated Time, also known in some countries as GMT, Greenwich Mean time), then converts the representation from the arithmetic representation to the traditional representation defined by struct tm.

gmtime constructs the traditional time representation in static storage; each call to gmtime or localtime will overwrite the information generated by previous calls to either function.


Returns
A pointer to the traditional time representation (struct tm).


Portability
ANSI C requires gmtime.

gmtime requires no supporting OS subroutines.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.6 localtime---convert time to local representation

Synopsis
 
#include <time.h>
struct tm *localtime(time_t *clock);
struct tm *localtime_r(time_t *clock, struct tm *res);

Description
localtime converts the time at clock into local time, then converts its representation from the arithmetic representation to the traditional representation defined by struct tm.

localtime constructs the traditional time representation in static storage; each call to gmtime or localtime will overwrite the information generated by previous calls to either function.

mktime is the inverse of localtime.


Returns
A pointer to the traditional time representation (struct tm).


Portability
ANSI C requires localtime.

localtime requires no supporting OS subroutines.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.7 mktime---convert time to arithmetic representation

Synopsis
 
#include <time.h>
time_t mktime(struct tm *timp);

Description
mktime assumes the time at timp is a local time, and converts its representation from the traditional representation defined by struct tm into a representation suitable for arithmetic.

localtime is the inverse of mktime.


Returns
If the contents of the structure at timp do not form a valid calendar time representation, the result is -1. Otherwise, the result is the time, converted to a time_t value.


Portability
ANSI C requires mktime.

mktime requires no supporting OS subroutines.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.8 strftime---flexible calendar time formatter

Synopsis
 
#include <time.h>
size_t strftime(char *s, size_t maxsize,
    const char *format, const struct tm *timp);

Description
strftime converts a struct tm representation of the time (at timp) into a string, starting at s and occupying no more than maxsize characters.

You control the format of the output using the string at format. *format can contain two kinds of specifications: text to be copied literally into the formatted string, and time conversion specifications. Time conversion specifications are two-character sequences beginning with `%' (use `%%' to include a percent sign in the output). Each defined conversion specification selects a field of calendar time data from *timp, and converts it to a string in one of the following ways:

%a
An abbreviation for the day of the week.

%A
The full name for the day of the week.

%b
An abbreviation for the month name.

%B
The full name of the month.

%c
A string representing the complete date and time, in the form
 
 Mon Apr 01 13:13:13 1992

%d
The day of the month, formatted with two digits.

%e
The day of the month, formatted with leading space if single digit.

%H
The hour (on a 24-hour clock), formatted with two digits.

%I
The hour (on a 12-hour clock), formatted with two digits.

%j
The count of days in the year, formatted with three digits (from `001' to `366').

%m
The month number, formatted with two digits.

%M
The minute, formatted with two digits.

%p
Either `AM' or `PM' as appropriate.

%S
The second, formatted with two digits.

%U
The week number, formatted with two digits (from `00' to `53'; week number 1 is taken as beginning with the first Sunday in a year). See also %W.

%w
A single digit representing the day of the week: Sunday is day 0.

%W
Another version of the week number: like `%U', but counting week 1 as beginning with the first Monday in a year.

o %x
A string representing the complete date, in a format like
 
 Mon Apr 01 1992

%X
A string representing the full time of day (hours, minutes, and seconds), in a format like
 
 13:13:13

%y
The last two digits of the year.

%Y
The full year, formatted with four digits to include the century.

%Z
The time zone name. If tm_isdst is -1, no output is generated. Otherwise, the time zone name based on the TZ environment variable is used.

%%
A single character, `%'.


Returns
When the formatted time takes up no more than maxsize characters, the result is the length of the formatted string. Otherwise, if the formatting operation was abandoned due to lack of room, the result is 0, and the string starting at s corresponds to just those parts of *format that could be completely filled in within the maxsize limit.


Portability
ANSI C requires strftime, but does not specify the contents of *s when the formatted string would require more than maxsize characters.

strftime requires no supporting OS subroutines.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.9 time---get current calendar time (as single number)

Synopsis
 
#include <time.h>
time_t time(time_t *t);

Description
time looks up the best available representation of the current time and returns it, encoded as a time_t. It stores the same value at t unless the argument is NULL.


Returns
A -1 result means the current time is not available; otherwise the result represents the current time.


Portability
ANSI C requires time.

Supporting OS subroutine required: Some implementations require gettimeofday.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.10 tzset---set timezone characteristics from TZ environment variable

Synopsis
 
#include <time.h>
void tzset(void);
void _tzset_r (struct _reent *);

Description
tzset examines the TZ environment variable and sets up the three external variables: _timezone, _daylight, and tzname. The value of _timezone shall be the offset from the current time zone to GMT. The value of _daylight shall be 0 if there is no daylight savings time for the current time zone, otherwise it will be non-zero. The tzname array has two entries: the first is the name of the standard time zone, the second is the name of the daylight-savings time zone.

The TZ environment variable is expected to be in the following POSIX format:

stdoffset1[dst[offset2][,start[/time1],end[/time2]]]

where: std is the name of the standard time-zone (minimum 3 chars) offset1 is the value to add to local time to arrive at Universal time it has the form: hh[:mm[:ss]] dst is the name of the alternate (daylight-savings) time-zone (min 3 chars) offset2 is the value to add to local time to arrive at Universal time it has the same format as the std offset start is the day that the alternate time-zone starts time1 is the optional time that the alternate time-zone starts (this is in local time and defaults to 02:00:00 if not specified) end is the day that the alternate time-zone ends time2 is the time that the alternate time-zone ends (it is in local time and defaults to 02:00:00 if not specified)

Note that there is no white-space padding between fields. Also note that if TZ is null, the default is Universal GMT which has no daylight-savings time. If TZ is empty, the default EST5EDT is used.

The function _tzset_r is identical to tzset only it is reentrant and is used for applications that use multiple threads.


Returns
There is no return value.


Portability
tzset is part of the POSIX standard.

Supporting OS subroutine required: None



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8. Locale (`locale.h')

A locale is the name for a collection of parameters (affecting collating sequences and formatting conventions) that may be different depending on location or culture. The "C" locale is the only one defined in the ANSI C standard.

This is a minimal implementation, supporting only the required "C" value for locale; strings representing other locales are not honored. ("" is also accepted; it represents the default locale for an implementation, here equivalent to "C".

`locale.h' defines the structure lconv to collect the information on a locale, with the following fields:

char *decimal_point
The decimal point character used to format "ordinary" numbers (all numbers except those referring to amounts of money). "." in the C locale.

char *thousands_sep
The character (if any) used to separate groups of digits, when formatting ordinary numbers. "" in the C locale.

char *grouping
Specifications for how many digits to group (if any grouping is done at all) when formatting ordinary numbers. The numeric value of each character in the string represents the number of digits for the next group, and a value of 0 (that is, the string's trailing NULL) means to continue grouping digits using the last value specified. Use CHAR_MAX to indicate that no further grouping is desired. "" in the C locale.

char *int_curr_symbol
The international currency symbol (first three characters), if any, and the character used to separate it from numbers. "" in the C locale.

char *currency_symbol
The local currency symbol, if any. "" in the C locale.

char *mon_decimal_point
The symbol used to delimit fractions in amounts of money. "" in the C locale.

char *mon_thousands_sep
Similar to thousands_sep, but used for amounts of money. "" in the C locale.

char *mon_grouping
Similar to grouping, but used for amounts of money. "" in the C locale.

char *positive_sign
A string to flag positive amounts of money when formatting. "" in the C locale.

char *negative_sign
A string to flag negative amounts of money when formatting. "" in the C locale.

char int_frac_digits
The number of digits to display when formatting amounts of money to international conventions. CHAR_MAX (the largest number representable as a char) in the C locale.

char frac_digits
The number of digits to display when formatting amounts of money to local conventions. CHAR_MAX in the C locale.

char p_cs_precedes
1 indicates the local currency symbol is used before a positive or zero formatted amount of money; 0 indicates the currency symbol is placed after the formatted number. CHAR_MAX in the C locale.

char p_sep_by_space
1 indicates the local currency symbol must be separated from positive or zero numbers by a space; 0 indicates that it is immediately adjacent to numbers. CHAR_MAX in the C locale.

char n_cs_precedes
1 indicates the local currency symbol is used before a negative formatted amount of money; 0 indicates the currency symbol is placed after the formatted number. CHAR_MAX in the C locale.

char n_sep_by_space
1 indicates the local currency symbol must be separated from negative numbers by a space; 0 indicates that it is immediately adjacent to numbers. CHAR_MAX in the C locale.

char p_sign_posn
Controls the position of the positive sign for numbers representing money. 0 means parentheses surround the number; 1 means the sign is placed before both the number and the currency symbol; 2 means the sign is placed after both the number and the currency symbol; 3 means the sign is placed just before the currency symbol; and 4 means the sign is placed just after the currency symbol. CHAR_MAX in the C locale.

char n_sign_posn
Controls the position of the negative sign for numbers representing money, using the same rules as p_sign_posn. CHAR_MAX in the C locale.

8.1 setlocale, localeconv---select or query locale  Select or query locale


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.1 setlocale, localeconv---select or query locale

Synopsis
 
#include <locale.h>
char *setlocale(int category, const char *locale);
lconv *localeconv(void);

char *_setlocale_r(void *reent,
    int category, const char *locale);
lconv *_localeconv_r(void *reent);

Description
setlocale is the facility defined by ANSI C to condition the execution environment for international collating and formatting information; localeconv reports on the settings of the current locale.

This is a minimal implementation, supporting only the required "C" value for locale; strings representing other locales are not honored unless MB_CAPABLE is defined in which case three new extensions are allowed for LC_CTYPE or LC_MESSAGES only: "C-JIS", "C-EUCJP", "C-SJIS", or "C-ISO-8859-1". ("" is also accepted; it represents the default locale for an implementation, here equivalent to "C".)

If you use NULL as the locale argument, setlocale returns a pointer to the string representing the current locale (always "C" in this implementation). The acceptable values for category are defined in `locale.h' as macros beginning with "LC_", but this implementation does not check the values you pass in the category argument.

localeconv returns a pointer to a structure (also defined in `locale.h') describing the locale-specific conventions currently in effect.

_localeconv_r and _setlocale_r are reentrant versions of localeconv and setlocale respectively. The extra argument reent is a pointer to a reentrancy structure.


Returns
setlocale returns either a pointer to a string naming the locale currently in effect (always "C" for this implementation, or, if the locale request cannot be honored, NULL.

localeconv returns a pointer to a structure of type lconv, which describes the formatting and collating conventions in effect (in this implementation, always those of the C locale).


Portability
ANSI C requires setlocale, but the only locale required across all implementations is the C locale.

No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9. Reentrancy

Reentrancy is a characteristic of library functions which allows multiple processes to use the same address space with assurance that the values stored in those spaces will remain constant between calls. Cygnus's implementation of the library functions ensures that whenever possible, these library functions are reentrant. However, there are some functions that can not be trivially made reentrant. Hooks have been provided to allow you to use these functions in a fully reentrant fashion.

These hooks use the structure _reent defined in `reent.h'. A variable defined as `struct _reent' is called a reentrancy structure. All functions which must manipulate global information are available in two versions. The first version has the usual name, and uses a single global instance of the reentrancy structure. The second has a different name, normally formed by prepending `_' and appending `_r', and takes a pointer to the particular reentrancy structure to use.

For example, the function fopen takes two arguments, file and mode, and uses the global reentrancy structure. The function _fopen_r takes the arguments, struct_reent, which is a pointer to an instance of the reentrancy structure, file and mode.

There are two versions of `struct _reent', a normal one and one for small memory systems, controlled by the _REENT_SMALL definition from the (automatically included) `<sys/config.h>'.

Each function which uses the global reentrancy structure uses the global variable _impure_ptr, which points to a reentrancy structure.

This means that you have two ways to achieve reentrancy. Both require that each thread of execution control initialize a unique global variable of type `struct _reent':

  1. Use the reentrant versions of the library functions, after initializing a global reentrancy structure for each process. Use the pointer to this structure as the extra argument for all library functions.

  2. Ensure that each thread of execution control has a pointer to its own unique reentrancy structure in the global variable _impure_ptr, and call the standard library subroutines.

The following functions are provided in both reentrant and non-reentrant versions.

 
Equivalent for errno variable:
_errno_r

Locale functions:
_localeconv_r  _setlocale_r

Equivalents for stdio variables:
_stdin_r        _stdout_r       _stderr_r

Stdio functions:
_fdopen_r       _perror_r       _tempnam_r
_fopen_r        _putchar_r      _tmpnam_r
_getchar_r      _puts_r         _tmpfile_r
_gets_r         _remove_r       _vfprintf_r
_iprintf_r      _rename_r       _vsnprintf_r
_mkstemp_r      _snprintf_r     _vsprintf_r
_mktemp_t       _sprintf_r

Signal functions:
_init_signal_r  _signal_r
_kill_r         __sigtramp_r
_raise_r

Stdlib functions:
_calloc_r       _mblen_r        _setenv_r
_dtoa_r         _mbstowcs_r     _srand_r
_free_r         _mbtowc_r       _strtod_r
_getenv_r       _memalign_r     _strtol_r
_mallinfo_r     _mstats_r       _strtoul_r
_malloc_r       _putenv_r       _system_r
_malloc_r       _rand_r         _wcstombs_r
_malloc_stats_r _realloc_r      _wctomb_r

String functions:
_strdup_r       _strtok_r

System functions:
_close_r        _link_r         _unlink_r
_execve_r       _lseek_r        _wait_r
_fcntl_r        _open_r         _write_r 
_fork_r         _read_r
_fstat_r        _sbrk_r
_gettimeofday_r _stat_r
_getpid_r       _times_r

Additional 64-bit I/O System functions:
_fstat64_r	_lseek64_r	_open64_r

Time function:
_asctime_r


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10. Miscellaneous Macros and Functions

This chapter describes miscellaneous routines not covered elsewhere.

10.1 ffs---find first bit set in a word  Return first bit set in a word
10.2 unctrl---translate characters to upper case  Return printable representation of a character


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.1 ffs---find first bit set in a word

Synopsis
 
int ffs(int word);

Description

ffs returns the first bit set in a word.


Returns
ffs returns 0 if c is 0, 1 if c is odd, 2 if c is a multiple of 2, etc.


Portability
ffs is not ANSI C.

No supporting OS subroutines are required.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.2 unctrl---translate characters to upper case

Synopsis
 
#include <unctrl.h>
char *unctrl(int c);
int unctrllen(int c);

Description
unctrl is a macro which returns the printable representation of c as a string. unctrllen is a macro which returns the length of the printable representation of c.


Returns
unctrl returns a string of the printable representation of c.

unctrllen returns the length of the string which is the printable representation of c.


Portability
unctrl and unctrllen are not ANSI C.

No supporting OS subroutines are required.



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11. System Calls

The C subroutine library depends on a handful of subroutine calls for operating system services. If you use the C library on a system that complies with the POSIX.1 standard (also known as IEEE 1003.1), most of these subroutines are supplied with your operating system.

If some of these subroutines are not provided with your system--in the extreme case, if you are developing software for a "bare board" system, without an OS--you will at least need to provide do-nothing stubs (or subroutines with minimal functionality) to allow your programs to link with the subroutines in libc.a.

11.1 Definitions for OS interface  
11.2 Reentrant covers for OS subroutines  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.1 Definitions for OS interface

This is the complete set of system definitions (primarily subroutines) required; the examples shown implement the minimal functionality required to allow libc to link, and fail gracefully where OS services are not available.

Graceful failure is permitted by returning an error code. A minor complication arises here: the C library must be compatible with development environments that supply fully functional versions of these subroutines. Such environments usually return error codes in a global errno. However, the Cygnus C library provides a macro definition for errno in the header file `errno.h', as part of its support for reentrant routines (see section Reentrancy).

The bridge between these two interpretations of errno is straightforward: the C library routines with OS interface calls capture the errno values returned globally, and record them in the appropriate field of the reentrancy structure (so that you can query them using the errno macro from `errno.h').

This mechanism becomes visible when you write stub routines for OS interfaces. You must include `errno.h', then disable the macro, like this:

 
#include <errno.h>
#undef errno
extern int errno;

The examples in this chapter include this treatment of errno.

_exit
Exit a program without cleaning up files. If your system doesn't provide this, it is best to avoid linking with subroutines that require it (exit, system).

close
Close a file. Minimal implementation:

 
int close(int file){
    return -1;
}

environ
A pointer to a list of environment variables and their values. For a minimal environment, this empty list is adequate:

 
char *__env[1] = { 0 };
char **environ = __env;

execve
Transfer control to a new process. Minimal implementation (for a system without processes):

 
#include <errno.h>
#undef errno
extern int errno;
int execve(char *name, char **argv, char **env){
  errno=ENOMEM;
  return -1;
}

fork
Create a new process. Minimal implementation (for a system without processes):

 
#include <errno.h>
#undef errno
extern int errno;
int fork() {
  errno=EAGAIN;
  return -1;
}

fstat
Status of an open file. For consistency with other minimal implementations in these examples, all files are regarded as character special devices. The `sys/stat.h' header file required is distributed in the `include' subdirectory for this C library.

 
#include <sys/stat.h>
int fstat(int file, struct stat *st) {
  st->st_mode = S_IFCHR;
  return 0;
}

getpid
Process-ID; this is sometimes used to generate strings unlikely to conflict with other processes. Minimal implementation, for a system without processes:

 
int getpid() {
  return 1;
}

isatty
Query whether output stream is a terminal. For consistency with the other minimal implementations, which only support output to stdout, this minimal implementation is suggested:

 
int isatty(int file){
   return 1;
}

kill
Send a signal. Minimal implementation:

 
#include <errno.h>
#undef errno
extern int errno;
int kill(int pid, int sig){
  errno=EINVAL;
  return(-1);
}

link
Establish a new name for an existing file. Minimal implementation:

 
#include <errno.h>
#undef errno
extern int errno;
int link(char *old, char *new){
  errno=EMLINK;
  return -1;
}

lseek
Set position in a file. Minimal implementation:

 
int lseek(int file, int ptr, int dir){
    return 0;
}

open
Open a file. Minimal implementation:

 
int open(const char *name, int flags, int mode){
    return -1;
}

read
Read from a file. Minimal implementation:

 
int read(int file, char *ptr, int len){
    return 0;
}

sbrk
Increase program data space. As malloc and related functions depend on this, it is useful to have a working implementation. The following suffices for a standalone system; it exploits the symbol end automatically defined by the GNU linker.

 
caddr_t sbrk(int incr){
  extern char end;		/* Defined by the linker */
  static char *heap_end;
  char *prev_heap_end;
 
  if (heap_end == 0) {
    heap_end = &end;
  }
  prev_heap_end = heap_end;
  if (heap_end + incr > stack_ptr)
    {
      _write (1, "Heap and stack collision\n", 25);
      abort ();
    }

  heap_end += incr;
  return (caddr_t) prev_heap_end;
}

stat
Status of a file (by name). Minimal implementation:

 
int stat(char *file, struct stat *st) {
  st->st_mode = S_IFCHR;
  return 0;
}

times
Timing information for current process. Minimal implementation:

 
int times(struct tms *buf){
  return -1;
}

unlink
Remove a file's directory entry. Minimal implementation:

 
#include <errno.h>
#undef errno
extern int errno;
int unlink(char *name){
  errno=ENOENT;
  return -1; 
}

wait
Wait for a child process. Minimal implementation:
 
#include <errno.h>
#undef errno
extern int errno;
int wait(int *status) {
  errno=ECHILD;
  return -1;
}

write
Write a character to a file. `libc' subroutines will use this system routine for output to all files, including stdout---so if you need to generate any output, for example to a serial port for debugging, you should make your minimal write capable of doing this. The following minimal implementation is an incomplete example; it relies on a writechar subroutine (not shown; typically, you must write this in assembler from examples provided by your hardware manufacturer) to actually perform the output.

 
int write(int file, char *ptr, int len){
    int todo;
  
    for (todo = 0; todo < len; todo++) {
        writechar(*ptr++);
    }
    return len;
}


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.2 Reentrant covers for OS subroutines

Since the system subroutines are used by other library routines that require reentrancy, `libc.a' provides cover routines (for example, the reentrant version of fork is _fork_r). These cover routines are consistent with the other reentrant subroutines in this library, and achieve reentrancy by using a reserved global data block (see section Reentrancy).

_open_r
A reentrant version of open. It takes a pointer to the global data block, which holds errno.

 
int _open_r(void *reent,
    const char *file, int flags, int mode);

_open64_r
A reentrant version of open64. It takes a pointer to the global data block, which holds errno.

 
int _open64_r(void *reent,
    const char *file, int flags, int mode);

_close_r
A reentrant version of close. It takes a pointer to the global data block, which holds errno.

 
int _close_r(void *reent, int fd);

_lseek_r
A reentrant version of lseek. It takes a pointer to the global data block, which holds errno.

 
off_t _lseek_r(void *reent,
    int fd, off_t pos, int whence);

_lseek64_r
A reentrant version of lseek64. It takes a pointer to the global data block, which holds errno.

 
off_t _lseek64_r(void *reent,
    int fd, off_t pos, int whence);

_read_r
A reentrant version of read. It takes a pointer to the global data block, which holds errno.

 
long _read_r(void *reent,
    int fd, void *buf, size_t cnt);

_write_r
A reentrant version of write. It takes a pointer to the global data block, which holds errno.

 
long _write_r(void *reent,
    int fd, const void *buf, size_t cnt);

_fork_r
A reentrant version of fork. It takes a pointer to the global data block, which holds errno.

 
int _fork_r(void *reent);

_wait_r
A reentrant version of wait. It takes a pointer to the global data block, which holds errno.

 
int _wait_r(void *reent, int *status);

_stat_r
A reentrant version of stat. It takes a pointer to the global data block, which holds errno.

 
int _stat_r(void *reent,
    const char *file, struct stat *pstat);

_fstat_r
A reentrant version of fstat. It takes a pointer to the global data block, which holds errno.

 
int _fstat_r(void *reent,
    int fd, struct stat *pstat);

_fstat64_r
A reentrant version of fstat64. It takes a pointer to the global data block, which holds errno.

 
int _fstat64_r(void *reent,
    int fd, struct stat *pstat);

_link_r
A reentrant version of link. It takes a pointer to the global data block, which holds errno.

 
int _link_r(void *reent,
    const char *old, const char *new);

_unlink_r
A reentrant version of unlink. It takes a pointer to the global data block, which holds errno.

 
int _unlink_r(void *reent, const char *file);

_sbrk_r
A reentrant version of sbrk. It takes a pointer to the global data block, which holds errno.

 
char *_sbrk_r(void *reent, size_t incr);


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12. Variable Argument Lists

The printf family of functions is defined to accept a variable number of arguments, rather than a fixed argument list. You can define your own functions with a variable argument list, by using macro definitions from either `stdarg.h' (for compatibility with ANSI C) or from `varargs.h' (for compatibility with a popular convention prior to ANSI C).

12.1 ANSI-standard macros, `stdarg.h'  
12.2 Traditional macros, `varargs.h'  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.1 ANSI-standard macros, `stdarg.h'

In ANSI C, a function has a variable number of arguments when its parameter list ends in an ellipsis (...). The parameter list must also include at least one explicitly named argument; that argument is used to initialize the variable list data structure.

ANSI C defines three macros (va_start, va_arg, and va_end) to operate on variable argument lists. `stdarg.h' also defines a special type to represent variable argument lists: this type is called va_list.

12.1.1 Initialize variable argument list  
12.1.2 Extract a value from argument list  
12.1.3 Abandon a variable argument list  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.1.1 Initialize variable argument list

Synopsis
 
#include <stdarg.h>
void va_start(va_list ap, rightmost);

Description
Use va_start to initialize the variable argument list ap, so that va_arg can extract values from it. rightmost is the name of the last explicit argument in the parameter list (the argument immediately preceding the ellipsis `...' that flags variable arguments in an ANSI C function header). You can only use va_start in a function declared using this ellipsis notation (not, for example, in one of its subfunctions).

Returns
va_start does not return a result.

Portability
ANSI C requires va_start.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.1.2 Extract a value from argument list

Synopsis
 
#include <stdarg.h>
type va_arg(va_list ap, type);

Description
va_arg returns the next unprocessed value from a variable argument list ap (which you must previously create with va_start). Specify the type for the value as the second parameter to the macro, type.

You may pass a va_list object ap to a subfunction, and use va_arg from the subfunction rather than from the function actually declared with an ellipsis in the header; however, in that case you may only use va_arg from the subfunction. ANSI C does not permit extracting successive values from a single variable-argument list from different levels of the calling stack.

There is no mechanism for testing whether there is actually a next argument available; you might instead pass an argument count (or some other data that implies an argument count) as one of the fixed arguments in your function call.

Returns
va_arg returns the next argument, an object of type type.

Portability
ANSI C requires va_arg.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.1.3 Abandon a variable argument list

Synopsis
 
#include <stdarg.h>
void va_end(va_list ap);

Description
Use va_end to declare that your program will not use the variable argument list ap any further.

Returns
va_end does not return a result.

Portability
ANSI C requires va_end.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.2 Traditional macros, `varargs.h'

If your C compiler predates ANSI C, you may still be able to use variable argument lists using the macros from the `varargs.h' header file. These macros resemble their ANSI counterparts, but have important differences in usage. In particular, since traditional C has no declaration mechanism for variable argument lists, two additional macros are provided simply for the purpose of defining functions with variable argument lists.

As with `stdarg.h', the type va_list is used to hold a data structure representing a variable argument list.

12.2.1 Declare variable arguments  
12.2.2 Initialize variable argument list  
12.2.3 Extract a value from argument list  
12.2.4 Abandon a variable argument list  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.2.1 Declare variable arguments

Synopsis
 
#include <varargs.h>
function(va_alist)
va_dcl

Description
To use the `varargs.h' version of variable argument lists, you must declare your function with a call to the macro va_alist as its argument list, and use va_dcl as the declaration. Do not use a semicolon after va_dcl.

Returns
These macros cannot be used in a context where a return is syntactically possible.

Portability
va_alist and va_dcl were the most widespread method of declaring variable argument lists prior to ANSI C.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.2.2 Initialize variable argument list

Synopsis
 
#include <varargs.h>
va_list ap;
va_start(ap);

Description
With the `varargs.h' macros, use va_start to initialize a data structure ap to permit manipulating a variable argument list. ap must have the type va_alist.

Returns
va_start does not return a result.

Portability
va_start is also defined as a macro in ANSI C, but the definitions are incompatible; the ANSI version has another parameter besides ap.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.2.3 Extract a value from argument list

Synopsis
 
#include <varargs.h>
type va_arg(va_list ap, type);

Description
va_arg returns the next unprocessed value from a variable argument list ap (which you must previously create with va_start). Specify the type for the value as the second parameter to the macro, type.

Returns
va_arg returns the next argument, an object of type type.

Portability
The va_arg defined in `varargs.h' has the same syntax and usage as the ANSI C version from `stdarg.h'.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.2.4 Abandon a variable argument list

Synopsis
 
#include <varargs.h>
va_end(va_list ap);

Description
Use va_end to declare that your program will not use the variable argument list ap any further.

Returns
va_end does not return a result.

Portability
The va_end defined in `varargs.h' has the same syntax and usage as the ANSI C version from `stdarg.h'.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Index

Jump to:   _  
A   B   C   D   E   F   G   I   J   K   L   M   N   O   P   R   S   T   U   V   W  

Index Entry Section

_
__env_lock1.13 __env_lock, __env_unlock--lock environ variable
__env_unlock1.13 __env_lock, __env_unlock--lock environ variable
__malloc_lock1.22 __malloc_lock, __malloc_unlock--lock malloc pool
__malloc_unlock1.22 __malloc_lock, __malloc_unlock--lock malloc pool
_asctime_r7.1 asctime---format time as string
_atoi_r1.6 atoi, atol---string to integer
_atol_r1.6 atoi, atol---string to integer
_atoll_r1.7 atoll---convert a string to a long long integer
_calloc_r1.8 calloc---allocate space for arrays
_close_r11.2 Reentrant covers for OS subroutines
_close_r11.2 Reentrant covers for OS subroutines
_exit11.1 Definitions for OS interface
_exit11.1 Definitions for OS interface
_fdopen_r3.11 fdopen---turn open file into a stream
_fgetpos_r3.7 fgetpos---record position in a stream or file
_fopen_r3.10 fopen---open a file
_fork_r11.2 Reentrant covers for OS subroutines
_fork_r11.2 Reentrant covers for OS subroutines
_free_r1.20 malloc, realloc, free---manage memory
_freopen_r3.15 freopen---open a file using an existing file descriptor
_fseek_r3.16 fseek, fseeko---set file position
_fseeko_r3.16 fseek, fseeko---set file position
_fsetpos_r3.17 fsetpos---restore position of a stream or file
_fstat64_r11.2 Reentrant covers for OS subroutines
_fstat64_r11.2 Reentrant covers for OS subroutines
_fstat_r11.2 Reentrant covers for OS subroutines
_fstat_r11.2 Reentrant covers for OS subroutines
_ftell_r3.18 ftell, ftello---return position in a stream or file
_ftello_r3.18 ftell, ftello---return position in a stream or file
_getchar_r3.21 getchar---read a character (macro)
_gets_r3.22 gets---get character string (obsolete, use fgets instead)
_impure_ptr9. Reentrancy
_link_r11.2 Reentrant covers for OS subroutines
_link_r11.2 Reentrant covers for OS subroutines
_localeconv_r8.1 setlocale, localeconv---select or query locale
_lseek64_r11.2 Reentrant covers for OS subroutines
_lseek64_r11.2 Reentrant covers for OS subroutines
_lseek_r11.2 Reentrant covers for OS subroutines
_lseek_r11.2 Reentrant covers for OS subroutines
_mallinfo_r1.21 mallinfo, malloc_stats, mallopt--malloc support
_malloc_r1.20 malloc, realloc, free---manage memory
_malloc_stats_r1.21 mallinfo, malloc_stats, mallopt--malloc support
_malloc_usable_size_r1.20 malloc, realloc, free---manage memory
_mallopt_r1.21 mallinfo, malloc_stats, mallopt--malloc support
_memalign_r1.20 malloc, realloc, free---manage memory
_mkstemp_r3.25 mktemp, mkstemp---generate unused file name
_mktemp_r3.25 mktemp, mkstemp---generate unused file name
_open64_r11.2 Reentrant covers for OS subroutines
_open64_r11.2 Reentrant covers for OS subroutines
_open_r11.2 Reentrant covers for OS subroutines
_open_r11.2 Reentrant covers for OS subroutines
_perror_r3.26 perror---print an error message on standard error
_putchar_r3.28 putchar---write a character (macro)
_puts_r3.29 puts---write a character string
_raise_r6.1 raise---send a signal
_raise_r6.2 signal---specify handler subroutine for a signal
_read_r11.2 Reentrant covers for OS subroutines
_read_r11.2 Reentrant covers for OS subroutines
_realloc_r1.20 malloc, realloc, free---manage memory
_reent9. Reentrancy
_rename_r3.32 rename---rename a file
_rewind_r3.33 rewind---reinitialize a file or stream
_sbrk_r11.2 Reentrant covers for OS subroutines
_sbrk_r11.2 Reentrant covers for OS subroutines
_setlocale_r8.1 setlocale, localeconv---select or query locale
_signal_r6.2 signal---specify handler subroutine for a signal
_stat_r11.2 Reentrant covers for OS subroutines
_stat_r11.2 Reentrant covers for OS subroutines
_strtod_r1.28 strtod, strtof---string to double or float
_strtol_r1.29 strtol---string to long
_strtoul_r1.30 strtoul---string to unsigned long
_system_r1.31 system---execute command string
_tempnam_r3.40 tmpnam, tempnam---name for a temporary file
_tmpfile_r3.39 tmpfile---create a temporary file
_tmpnam_r3.40 tmpnam, tempnam---name for a temporary file
_tolower2.13 tolower---translate characters to lower case
_toupper2.14 toupper---translate characters to upper case
_unlink_r11.2 Reentrant covers for OS subroutines
_unlink_r11.2 Reentrant covers for OS subroutines
_wait_r11.2 Reentrant covers for OS subroutines
_wait_r11.2 Reentrant covers for OS subroutines
_write_r11.2 Reentrant covers for OS subroutines
_write_r11.2 Reentrant covers for OS subroutines

A
abort1.1 abort---abnormal termination of a program
abs1.2 abs---integer absolute value (magnitude)
asctime7.1 asctime---format time as string
asprintf3.37 printf, fprintf, asprintf, sprintf, snprintf---format output
assert1.3 assert---Macro for Debugging Diagnostics
atexit1.4 atexit---request execution of functions at program exit
atof1.5 atof, atoff---string to double or float
atoff1.5 atof, atoff---string to double or float
atoi1.6 atoi, atol---string to integer
atol1.6 atoi, atol---string to integer
atoll1.7 atoll---convert a string to a long long integer

B
bcmp4.1 bcmp---compare two memory areas
bzero4.3 bzero---initialize memory to zero

C
calloc1.8 calloc---allocate space for arrays
clearerr3.1 clearerr---clear file or stream error indicator
clock7.2 clock---cumulative processor time
close11.1 Definitions for OS interface
close11.1 Definitions for OS interface
ctime7.3 ctime---convert time to local and format as string

D
difftime7.4 difftime---subtract two times
div1.9 div---divide two integers
drand481.27 rand48, drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, lcong48 --pseudo random number generators and initialization routines

E
ecvt1.10 ecvt,ecvtf,fcvt,fcvtf---double or float to string
ecvtbuf1.12 ecvtbuf, fcvtbuf---double or float to string
environ1.15 getenv---look up environment variable
environ11.1 Definitions for OS interface
environ11.1 Definitions for OS interface
erand481.27 rand48, drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, lcong48 --pseudo random number generators and initialization routines
errno global vs macro11.1 Definitions for OS interface
execve11.1 Definitions for OS interface
execve11.1 Definitions for OS interface
exit1.14 exit---end program execution
extra argument, reentrant fns9. Reentrancy

F
fclose3.2 fclose---close a file
fcvt1.10 ecvt,ecvtf,fcvt,fcvtf---double or float to string
fcvtbuf1.12 ecvtbuf, fcvtbuf---double or float to string
fdopen3.11 fdopen---turn open file into a stream
feof3.3 feof---test for end of file
ferror3.4 ferror---test whether read/write error has occurred
fflush3.5 fflush---flush buffered file output
ffs10.1 ffs---find first bit set in a word
fgetc3.6 fgetc---get a character from a file or stream
fgetpos3.7 fgetpos---record position in a stream or file
fgets3.8 fgets---get character string from a file or stream
fiprintf3.9 fiprintf---format output to file (integer only)
fopen3.10 fopen---open a file
fork11.1 Definitions for OS interface
fork11.1 Definitions for OS interface
fprintf3.37 printf, fprintf, asprintf, sprintf, snprintf---format output
fputc3.12 fputc---write a character on a stream or file
fputs3.13 fputs---write a character string in a file or stream
fread3.14 fread---read array elements from a file
free1.20 malloc, realloc, free---manage memory
freopen3.15 freopen---open a file using an existing file descriptor
fscanf3.38 scanf, fscanf, sscanf---scan and format input
fseek3.16 fseek, fseeko---set file position
fseeko3.16 fseek, fseeko---set file position
fsetpos3.17 fsetpos---restore position of a stream or file
fstat11.1 Definitions for OS interface
fstat11.1 Definitions for OS interface
ftell3.18 ftell, ftello---return position in a stream or file
ftello3.18 ftell, ftello---return position in a stream or file
fwrite3.19 fwrite---write array elements

G
gcvt1.11 gvcvt, gcvtf---format double or float as string
gcvtf1.11 gvcvt, gcvtf---format double or float as string
getc3.20 getc---read a character (macro)
getchar3.21 getchar---read a character (macro)
getenv1.15 getenv---look up environment variable
getpid11.1 Definitions for OS interface
getpid11.1 Definitions for OS interface
gets3.22 gets---get character string (obsolete, use fgets instead)
getw3.23 getw---read a word (int)
global reentrancy structure9. Reentrancy
gmtime7.5 gmtime---convert time to UTC traditional form

I
index4.4 index---search for character in string
iprintf3.24 iprintf---write formatted output (integer only)
isalnum2.1 isalnum---alphanumeric character predicate
isalpha2.2 isalpha---alphabetic character predicate
isascii2.3 isascii---ASCII character predicate
isatty11.1 Definitions for OS interface
isatty11.1 Definitions for OS interface
iscntrl2.4 iscntrl---control character predicate
isdigit2.5 isdigit---decimal digit predicate
isgraph2.7 isprint, isgraph---printable character predicates
islower2.6 islower---lower-case character predicate
isprint2.7 isprint, isgraph---printable character predicates
ispunct2.8 ispunct---punctuation character predicate
isspace2.9 isspace---whitespace character predicate
isupper2.10 isupper---uppercase character predicate
iswalnum2.15 iswalnum---alpha-numeric wide-character test
iswalpha2.16 iswalpha---alphabetic wide-character test
iswcntrl2.17 iswcntrl---wide-character cntrl test
iswctype2.26 iswctype---extensible wide-character test
iswdigit2.18 iswdigit---decimal digit wide-character test
iswgraph2.19 iswgraph---graphic wide-character test
iswlower2.20 iswlower---lower-case wide-character test
iswprint2.21 iswprint---printable wide-character test
iswpunct2.22 iswpunct---punctuation wide-character test
iswspace2.23 iswspace---wide-character space test
iswupper2.24 iswupper---upper-case wide-character test
iswxdigit2.25 iswxdigit---hexadecimal digit wide-character test
isxdigit2.11 isxdigit---hexadecimal digit predicate

J
jrand481.27 rand48, drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, lcong48 --pseudo random number generators and initialization routines

K
kill11.1 Definitions for OS interface
kill11.1 Definitions for OS interface

L
labs1.16 labs---long integer absolute value
lcong481.27 rand48, drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, lcong48 --pseudo random number generators and initialization routines
ldiv1.17 ldiv---divide two long integers
link11.1 Definitions for OS interface
link11.1 Definitions for OS interface
linking the C library11. System Calls
list of reentrant functions9. Reentrancy
llabs1.18 llabs---compute the absolute value of an long long integer.
lldiv1.19 lldiv---divide two long long integers
localeconv8.1 setlocale, localeconv---select or query locale
localtime7.6 localtime---convert time to local representation
lrand481.27 rand48, drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, lcong48 --pseudo random number generators and initialization routines
lseek11.1 Definitions for OS interface
lseek11.1 Definitions for OS interface

M
mallinfo1.21 mallinfo, malloc_stats, mallopt--malloc support
malloc1.20 malloc, realloc, free---manage memory
malloc_stats1.21 mallinfo, malloc_stats, mallopt--malloc support
malloc_usable_size1.20 malloc, realloc, free---manage memory
mallopt1.21 mallinfo, malloc_stats, mallopt--malloc support
mblen1.23 mblen---minimal multibyte length function
mbstowcs1.24 mbstowcs---minimal multibyte string to wide char converter
mbtowc1.25 mbtowc---minimal multibyte to wide char converter
memalign1.20 malloc, realloc, free---manage memory
memchr4.6 memchr---find character in memory
memcmp4.7 memcmp---compare two memory areas
memmove4.9 memmove---move possibly overlapping memory
memset4.11 memset---set an area of memory
mkstemp3.25 mktemp, mkstemp---generate unused file name
mktemp3.25 mktemp, mkstemp---generate unused file name
mktime7.7 mktime---convert time to arithmetic representation
mrand481.27 rand48, drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, lcong48 --pseudo random number generators and initialization routines

N
nrand481.27 rand48, drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, lcong48 --pseudo random number generators and initialization routines

O
open11.1 Definitions for OS interface
open11.1 Definitions for OS interface
OS interface subroutines11.1 Definitions for OS interface

P
perror3.26 perror---print an error message on standard error
printf3.37 printf, fprintf, asprintf, sprintf, snprintf---format output
putc3.27 putc---write a character (macro)
putchar3.28 putchar---write a character (macro)
puts3.29 puts---write a character string
putw3.30 putw---write a word (int)

R
raise6.1 raise---send a signal
raise6.2 signal---specify handler subroutine for a signal
rand1.26 rand, srand---pseudo-random numbers
rand481.27 rand48, drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, lcong48 --pseudo random number generators and initialization routines
rand_r1.26 rand, srand---pseudo-random numbers
read11.1 Definitions for OS interface
read11.1 Definitions for OS interface
realloc1.20 malloc, realloc, free---manage memory
reent.h9. Reentrancy
reentrancy9. Reentrancy
reentrancy structure9. Reentrancy
reentrant function list9. Reentrancy
remove3.31 remove---delete a file's name
rename3.32 rename---rename a file
rewind3.33 rewind---reinitialize a file or stream
rindex4.12 rindex---reverse search for character in string

S
sbrk11.1 Definitions for OS interface
sbrk11.1 Definitions for OS interface
scanf3.38 scanf, fscanf, sscanf---scan and format input
seed481.27 rand48, drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, lcong48 --pseudo random number generators and initialization routines
setbuf3.34 setbuf---specify full buffering for a file or stream
setlocale8.1 setlocale, localeconv---select or query locale
setvbuf3.35 setvbuf---specify file or stream buffering
signal6.2 signal---specify handler subroutine for a signal
siprintf3.36 siprintf---write formatted output (integer only)
snprintf3.37 printf, fprintf, asprintf, sprintf, snprintf---format output
sprintf3.37 printf, fprintf, asprintf, sprintf, snprintf---format output
srand1.26 rand, srand---pseudo-random numbers
srand481.27 rand48, drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, lcong48 --pseudo random number generators and initialization routines
sscanf3.38 scanf, fscanf, sscanf---scan and format input
stat11.1 Definitions for OS interface
stat11.1 Definitions for OS interface
strcasecmp4.13 strcasecmp---case insensitive character string compare
strcat4.14 strcat---concatenate strings
strchr4.15 strchr---search for character in string
strcmp4.16 strcmp---character string compare
strcoll4.17 strcoll---locale specific character string compare
strcpy4.18 strcpy---copy string
strcspn4.19 strcspn---count chars not in string
strerror4.20 strerror---convert error number to string
strftime7.8 strftime---flexible calendar time formatter
strlen4.21 strlen---character string length
strlwr4.22 strlwr---force string to lower case
strncasecmp4.23 strncasecmp---case insensitive character string compare
strncat4.24 strncat---concatenate strings
strncmp4.25 strncmp---character string compare
strncpy4.26 strncpy---counted copy string
strpbrk4.27 strpbrk---find chars in string
strrchr4.28 strrchr---reverse search for character in string
strsep4.31 strtok,strtok_r,strsep---get next token from a string
strspn4.29 strspn---find initial match
strstr4.30 strstr---find string segment
strtod1.28 strtod, strtof---string to double or float
strtof1.28 strtod, strtof---string to double or float
strtok4.31 strtok,strtok_r,strsep---get next token from a string
strtok_r4.31 strtok,strtok_r,strsep---get next token from a string
strtol1.29 strtol---string to long
strtoul1.30 strtoul---string to unsigned long
strupr4.32 strupr---force string to uppercase
strxfrm4.33 strxfrm---transform string
stubs11.1 Definitions for OS interface
subroutines for OS interface11.1 Definitions for OS interface
system1.31 system---execute command string

T
tempnam3.40 tmpnam, tempnam---name for a temporary file
time7.9 time---get current calendar time (as single number)
times11.1 Definitions for OS interface
times11.1 Definitions for OS interface
tmpfile3.39 tmpfile---create a temporary file
tmpnam3.40 tmpnam, tempnam---name for a temporary file
toascii2.12 toascii---force integers to ASCII range
tolower2.13 tolower---translate characters to lower case
toupper2.14 toupper---translate characters to upper case
towctrans2.30 towctrans---extensible wide-character case mapping
towlower2.28 towlower---translate wide-characters to lower case
towupper2.29 towupper---translate wide-characters to upper case
tzset7.10 tzset---set timezone characteristics from TZ environment variable

U
unctrl10.2 unctrl---translate characters to upper case
unctrllen10.2 unctrl---translate characters to upper case
unlink11.1 Definitions for OS interface
unlink11.1 Definitions for OS interface

V
va_alist12.2.1 Declare variable arguments
va_arg12.1.2 Extract a value from argument list
va_arg12.2.3 Extract a value from argument list
va_dcl12.2.1 Declare variable arguments
va_end12.1.3 Abandon a variable argument list
va_end12.2.4 Abandon a variable argument list
va_start12.1.1 Initialize variable argument list
va_start12.2.2 Initialize variable argument list
vfprintf3.41 vprintf, vfprintf, vsprintf---format argument list
vprintf3.41 vprintf, vfprintf, vsprintf---format argument list
vsnprintf3.41 vprintf, vfprintf, vsprintf---format argument list
vsprintf3.41 vprintf, vfprintf, vsprintf---format argument list

W
wait11.1 Definitions for OS interface
wait11.1 Definitions for OS interface
wcscat5.6 wcscat---concatenate two wide-character strings
wcscoll5.9 wcscoll---locale specific wide-character string compare
wcsnlen5.18 wcsnlen---get fixed-size wide character string length
wcstombs1.32 wcstombs---minimal wide char string to multibyte string converter
wcswidth5.23 wcswidth---number of column positions of a wide-character string
wctomb1.33 wctomb---minimal wide char to multibyte converter
wctrans2.31 wctrans---get wide-character translation type
wctype2.27 wctype---get wide-character classification type
wcwidth5.24 wcwidth---number of column positions of a wide-character code
write11.1 Definitions for OS interface
write11.1 Definitions for OS interface

Jump to:   _  
A   B   C   D   E   F   G   I   J   K   L   M   N   O   P   R   S   T   U   V   W  


[Top] [Contents] [Index] [ ? ]

Table of Contents


[Top] [Contents] [Index] [ ? ]

Short Table of Contents

1. Standard Utility Functions (`stdlib.h')
2. Character Type Macros and Functions (`ctype.h')
3. Input and Output (`stdio.h')
4. Strings and Memory (`string.h')
5. Wide Character Strings (`wchar.h')
6. Signal Handling (`signal.h')
7. Time Functions (`time.h')
8. Locale (`locale.h')
9. Reentrancy
10. Miscellaneous Macros and Functions
11. System Calls
12. Variable Argument Lists
Index

[Top] [Contents] [Index] [ ? ]

About this document

This document was generated by Jonah Graham on August, 2 2004 using texi2html

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ < ] Back previous section in reading order 1.2.2
[ > ] Forward next section in reading order 1.2.4
[ << ] FastBack previous or up-and-previous section 1.1
[ Up ] Up up section 1.2
[ >> ] FastForward next or up-and-next section 1.3
[Top] Top cover (top) of document  
[Contents] Contents table of contents  
[Index] Index concept index  
[ ? ] About this page  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

This document was generated by Jonah Graham on August, 2 2004 using texi2html