This file documents the ANSI C library.
Copyright (C) 1992, 1993, 1994-2004 Red Hat, Inc.
`libc' includes software developed by the University of California,
Berkeley and its contributors.
libc includes software developed by Martin Jackson, Graham Haley and
Steve Chamberlain of Tadpole Technology and released to Cygnus.
libc uses floating-point conversion software developed at AT&T, which
includes this copyright information:
The author of this software is David M. Gay.
Copyright (c) 1991 by AT&T.
Permission to use, copy, modify, and distribute this software for any
purpose without fee is hereby granted, provided that this entire notice
is included in all copies of any software which is or includes a copy
or modification of this software and in all copies of the supporting
documentation for such software.
THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR
IMPLIED WARRANTY. IN PARTICULAR, NEITHER THE AUTHOR NOR AT&T MAKES ANY
REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY
OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, subject to the
terms of the GNU General Public License, which includes the provision
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.
This is libc.info, produced by makeinfo version 4.7 from /oss/src/newlib/libc/libc.texinfo.
START-INFO-DIR-ENTRY
* libc:: The ANSI C library.
END-INFO-DIR-ENTRY
This file documents the ANSI C library.
Copyright (C) 1992, 1993, 1994-2004 Red Hat, Inc.
`libc' includes software developed by the University of California,
Berkeley and its contributors.
libc includes software developed by Martin Jackson, Graham Haley and
Steve Chamberlain of Tadpole Technology and released to Cygnus.
libc uses floating-point conversion software developed at AT&T, which
includes this copyright information:
The author of this software is David M. Gay.
Copyright (c) 1991 by AT&T.
Permission to use, copy, modify, and distribute this software for any
purpose without fee is hereby granted, provided that this entire notice
is included in all copies of any software which is or includes a copy
or modification of this software and in all copies of the supporting
documentation for such software.
THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR
IMPLIED WARRANTY. IN PARTICULAR, NEITHER THE AUTHOR NOR AT&T MAKES ANY
REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY
OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, subject to the
terms of the GNU General Public License, which includes the provision
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.
The Red Hat newlib C Library
****************************
* Menu:
* Stdlib::
* Ctype::
* Stdio::
* Stdio64::
* Strings::
* Wchar strings::
* Signals::
* Timefns::
* Locale::
* Syscalls::
* Misc::
* Arglists::
* Reentrancy::
* Library 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'.
* Menu:
* _Exit:: End program execution without cleaning up
* a64l:: String to long long
* abort:: Abnormal termination of a program
* abs:: Integer absolute value (magnitude)
* assert:: Macro for Debugging Diagnostics
* atexit:: Request execution of functions at program exit
* atof:: String to double or float
* atoi:: String to integer
* atoll:: String to long long
* calloc:: Allocate space for arrays
* div:: Divide two integers
* ecvtbuf:: Double or float to string of digits
* ecvt:: Double or float to string of digits (malloc result)
* __env_lock:: Lock environment list for getenv and setenv
* gvcvt:: Format double or float as string
* exit:: End program execution
* getenv:: Look up environment variable
* labs:: Long integer absolute value (magnitude)
* ldiv:: Divide two long integers
* llabs:: Long long integer absolute value (magnitude)
* lldiv:: Divide two long long integers
* malloc:: Allocate and manage memory (malloc, realloc, free)
* mallinfo:: Get information about allocated memory
* __malloc_lock:: Lock memory pool for malloc and free
* mbstowcs:: Minimal multibyte string to wide string converter
* mblen:: Minimal multibyte length
* mbtowc:: Minimal multibyte to wide character converter
* on_exit:: Request execution of functions at program exit
* rand:: Pseudo-random numbers
* rand48:: Uniformly distributed pseudo-random numbers
* strtod:: String to double or float
* strtol:: String to long
* strtoll:: String to long long
* strtoul:: String to unsigned long
* strtoull:: String to unsigned long long
* system:: Execute command string
* wcstombs:: Minimal wide string to multibyte string converter
* wctomb:: Minimal wide character to multibyte converter
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.
* Menu:
* isalnum:: Alphanumeric character predicate
* isalpha:: Alphabetic character predicate
* isascii:: ASCII character predicate
* iscntrl:: Control character predicate
* isdigit:: Decimal digit predicate
* islower:: Lower-case character predicate
* isprint:: Printable character predicates (isprint, isgraph)
* ispunct:: Punctuation character predicate
* isspace:: Whitespace character predicate
* isupper:: Uppercase character predicate
* isxdigit:: Hexadecimal digit predicate
* toascii:: Force integers to ASCII range
* tolower:: Translate characters to lower case
* toupper:: Translate characters to upper case
* iswalnum:: Alphanumeric wide-character predicate
* iswalpha:: Alphabetic wide-character predicate
* iswblank:: Blank wide-character predicate
* iswcntrl:: Control wide-character predicate
* iswdigit:: Decimal digit wide-character predicate
* iswgraph:: Graphic wide-character predicate
* iswlower:: Lower-case wide-character predicate
* iswprint:: Printable wide-character predicate
* iswpunct:: Punctuation wide-character predicate
* iswspace:: Whitespace wide-character predicate
* iswupper:: Uppercase wide-character predicate
* iswxdigit:: Hexadecimal digit wide-character predicate
* iswctype:: Extensible wide-character test
* wctype:: Compute wide-character test type
* towlower:: Translate wide-characters to lower case
* towupper:: Translate wide-characters to upper case
* towctrans:: Extensible wide-character case mapping
* wctrans:: Compute wide-character translation type
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.
* Menu:
* clearerr:: Clear file or stream error indicator
* fclose:: Close a file
* fcloseall:: Close all files
* feof:: Test for end of file
* ferror:: Test whether read/write error has occurred
* fflush:: Flush buffered file output
* fgetc:: Get a character from a file or stream
* fgetpos:: Record position in a stream or file
* fgets:: Get character string from a file or stream
* fileno:: Get file descriptor associated with stream
* fopen:: Open a file
* fdopen:: Turn an open file into a stream
* fputc:: Write a character on a stream or file
* fputs:: Write a character string in a file or stream
* fread:: Read array elements from a file
* freopen:: Open a file using an existing file descriptor
* fseek:: Set file position
* fsetpos:: Restore position of a stream or file
* ftell:: Return position in a stream or file
* fwrite:: Write array elements from memory to a file or stream
* getc:: Get a character from a file or stream (macro)
* getc_unlocked:: Get a character from a file or stream (macro)
* getchar:: Get a character from standard input (macro)
* getchar_unlocked:: Get a character from standard input (macro)
* getdelim:: Get character string from a file or stream
* getline:: Get character string from a file or stream
* gets:: Get character string from standard input (obsolete)
* getw:: Get a word (int) from a file or stream
* mktemp:: Generate unused file name
* perror:: Print an error message on standard error
* putc:: Write a character on a stream or file (macro)
* putc_unlocked:: Write a character on a stream or file (macro)
* putchar:: Write a character on standard output (macro)
* putchar_unlocked:: Write a character on standard output (macro)
* puts:: Write a character string on standard output
* putw:: Write a word (int) to a file or stream
* remove:: Delete a file's name
* rename:: Rename a file
* rewind:: Reinitialize a file or stream
* setbuf:: Specify full buffering for a file or stream
* setbuffer:: Specify full buffering for a file or stream with size
* setlinebuf:: Specify line buffering for a file or stream
* setvbuf:: Specify buffering for a file or stream
* printf:: Write formatted output
* scanf:: Scan and format input
* iprintf:: Write formatted output (integer only)
* iscanf:: Scan and format input (integer only)
* tmpfile:: Create a temporary file
* tmpnam:: Generate name for a temporary file
* viprintf:: Format variable argument list for non-floating-point output
* viscanf:: Scan variable format list for non-floating-point input
* vprintf:: Format variable argument list
* vscanf:: Format variable argument list
5 Strings and Memory (`string.h')
*********************************
This chapter describes string-handling functions and functions for managing areas of memory. The corresponding declarations are in `string.h'.
* Menu:
* bcmp:: Compare two memory areas
* bcopy:: Copy memory regions
* bzero:: Initialize memory to zero
* index:: Search for character in string
* memccpy:: Copy memory regions up to end-token
* memchr:: Find character in memory
* memcmp:: Compare two memory areas
* memcpy:: Copy memory regions
* memmove:: Move possibly overlapping memory
* mempcpy:: Copy memory regions and locate end
* memset:: Set an area of memory
* rindex:: Reverse search for character in string
* strcasecmp:: Compare strings ignoring case
* strcat:: Concatenate strings
* strchr:: Search for character in string
* strcmp:: Character string compare
* strcoll:: Locale specific character string compare
* strcpy:: Copy string
* strcspn:: Count chars not in string
* strerror:: Convert error number to string
* strerror_r:: Convert error number to string
* strlen:: Character string length
* strlwr:: Convert string to lower case
* strncasecmp:: Compare strings ignoring case
* strncat:: Concatenate strings
* strncmp:: Character string compare
* strncpy:: Counted copy string
* strnlen:: Character string length
* strpbrk:: Find chars in string
* strrchr:: Reverse search for character in string
* strspn:: Find initial match
* strstr:: Find string segment
* strtok:: Get next token from a string
* strupr:: Convert string to upper case
* strxfrm:: Transform string
* swab:: Swap adjacent bytes
7 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.)
* Menu:
* raise:: Send a signal
* signal:: Specify handler subroutine for a signal
8 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, between 0 and 60 inclusive (60 allows for leap seconds).
`tm_min'
Minutes, between 0 and 59 inclusive.
`tm_hour'
Hours, between 0 and 23 inclusive.
`tm_mday'
Day of the month, between 1 and 31 inclusive.
`tm_mon'
Month, between 0 (January) and 11 (December).
`tm_year'
Year (since 1900), can be negative for earlier years.
`tm_wday'
Day of week, between 0 (Sunday) and 6 (Saturday).
`tm_yday'
Number of days elapsed since last January 1, between 0 and 365
inclusive.
`tm_isdst'
Daylight Savings Time flag: positive means DST in effect, zero
means DST not in effect, negative means no information about DST
is available.
* Menu:
* asctime:: Format time as string
* clock:: Cumulative processor time
* ctime:: Convert time to local and format as string
* difftime:: Subtract two times
* gmtime:: Convert time to UTC (GMT) traditional representation
* localtime:: Convert time to local representation
* mktime:: Convert time to arithmetic representation
* strftime:: Flexible calendar time formatter
* time:: Get current calendar time (as single number)
* __tz_lock:: Lock time zone global variables
* tzset:: Set timezone info
9 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.
* Menu:
* setlocale:: Select or query locale
10 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
11 Miscellaneous Macros and Functions
*************************************
This chapter describes miscellaneous routines not covered elsewhere.
* Menu:
* ffs:: Return first bit set in a word
* unctrl:: Return printable representation of a character
12 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'.
* Menu:
* Stubs:: Definitions for OS interface
* Reentrant Syscalls:: Reentrant covers for OS subroutines
12.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 (*note Reentrancy: 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, 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;
}
12.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 (*note Reentrancy: 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);
13 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).
* Menu:
* Stdarg::
* Varargs::
13.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'.
* Menu:
* va_start::
* va_arg::
* va_end::
13.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.
* Menu:
* va_alist::
* va_start-trad::
* va_arg-trad::
* va_end-trad::
Index
*****