malloc
malloc
malloc
malloc
malloc-Related Functions
printf
sysconf
pathconf
@dircategory GNU libraries @direntry * Libc: (libc). C library.
@shorttitlepage The GNU C Library Reference Manual The GNU C Library
Reference Manual
Sandra Loosemore with Richard M. Stallman, Roland McGrath, Andrew Oram, and Ulrich Drepper
Edition 0.07 DRAFT
last updated 4 Oct 1996
for version 2.00 Beta Copyright (C) 1993, '94, '95, '96, '97 Free Software Foundation, Inc.
Published by the Free Software Foundation
59 Temple Place -- Suite 330,
Boston, MA 02111-1307 USA
Printed copies are available for $50 each.
ISBN 1-882114-53-1
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, provided also that the section entitled "GNU Library General Public License" is included exactly as in the original, and provided 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, except that the text of the translation of the section entitled "GNU Library General Public License" must be approved for accuracy by the Foundation.
The C language provides no built-in facilities for performing such common operations as input/output, memory management, string manipulation, and the like. Instead, these facilities are defined in a standard library, which you compile and link with your programs.
The GNU C library, described in this document, defines all of the library functions that are specified by the ISO C standard, as well as additional features specific to POSIX and other derivatives of the Unix operating system, and extensions specific to the GNU system.
The purpose of this manual is to tell you how to use the facilities of the GNU library. We have mentioned which features belong to which standards to help you identify things that are potentially nonportable to other systems. But the emphasis in this manual is not on strict portability.
This manual is written with the assumption that you are at least somewhat familiar with the C programming language and basic programming concepts. Specifically, familiarity with ISO standard C (see section ISO C), rather than "traditional" pre-ISO C dialects, is assumed.
The GNU C library includes several header files, each of which provides definitions and declarations for a group of related facilities; this information is used by the C compiler when processing your program. For example, the header file `stdio.h' declares facilities for performing input and output, and the header file `string.h' declares string processing utilities. The organization of this manual generally follows the same division as the header files.
If you are reading this manual for the first time, you should read all of the introductory material and skim the remaining chapters. There are a lot of functions in the GNU C library and it's not realistic to expect that you will be able to remember exactly how to use each and every one of them. It's more important to become generally familiar with the kinds of facilities that the library provides, so that when you are writing your programs you can recognize when to make use of library functions, and where in this manual you can find more specific information about them.
This section discusses the various standards and other sources that the GNU C library is based upon. These sources include the ISO C and POSIX standards, and the System V and Berkeley Unix implementations.
The primary focus of this manual is to tell you how to make effective use of the GNU library facilities. But if you are concerned about making your programs compatible with these standards, or portable to operating systems other than GNU, this can affect how you use the library. This section gives you an overview of these standards, so that you will know what they are when they are mentioned in other parts of the manual.
See section Summary of Library Facilities, for an alphabetical list of the functions and other symbols provided by the library. This list also states which standards each function or symbol comes from.
The GNU C library is compatible with the C standard adopted by the American National Standards Institute (ANSI): American National Standard X3.159-1989---"ANSI C" and later by the International Standardization Organization (ISO): ISO/IEC 9899:1990, "Programming languages--C". We here refer to the standard as ISO C since this is the more general standard in respect of ratification. The header files and library facilities that make up the GNU library are a superset of those specified by the ISO C standard.
If you are concerned about strict adherence to the ISO C standard, you should use the `-ansi' option when you compile your programs with the GNU C compiler. This tells the compiler to define only ISO standard features from the library header files, unless you explicitly ask for additional features. See section Feature Test Macros, for information on how to do this.
Being able to restrict the library to include only ISO C features is important because ISO C puts limitations on what names can be defined by the library implementation, and the GNU extensions don't fit these limitations. See section Reserved Names, for more information about these restrictions.
This manual does not attempt to give you complete details on the differences between ISO C and older dialects. It gives advice on how to write programs to work portably under multiple C dialects, but does not aim for completeness.
The GNU library is also compatible with the IEEE POSIX family of standards, known more formally as the Portable Operating System Interface for Computer Environments. POSIX is derived mostly from various versions of the Unix operating system.
The library facilities specified by the POSIX standards are a superset of those required by ISO C; POSIX specifies additional features for ISO C functions, as well as specifying new additional functions. In general, the additional requirements and functionality defined by the POSIX standards are aimed at providing lower-level support for a particular kind of operating system environment, rather than general programming language support which can run in many diverse operating system environments.
The GNU C library implements all of the functions specified in IEEE Std 1003.1-1990, the POSIX System Application Program Interface, commonly referred to as POSIX.1. The primary extensions to the ISO C facilities specified by this standard include file system interface primitives (see section File System Interface), device-specific terminal control functions (see section Low-Level Terminal Interface), and process control functions (see section Processes).
Some facilities from IEEE Std 1003.2-1992, the POSIX Shell and Utilities standard (POSIX.2) are also implemented in the GNU library. These include utilities for dealing with regular expressions and other pattern matching facilities (see section Pattern Matching).
The GNU C library defines facilities from some versions of Unix which are not formally standardized, specifically from the 4.2 BSD, 4.3 BSD, and 4.4 BSD Unix systems (also known as Berkeley Unix) and from SunOS (a popular 4.2 BSD derivative that includes some Unix System V functionality). These systems support most of the ISO C and POSIX facilities, and 4.4 BSD and newer releases of SunOS in fact support them all.
The BSD facilities include symbolic links (see section Symbolic Links), the
select function (see section Waiting for Input or Output), the BSD signal
functions (see section BSD Signal Handling), and sockets (see section Sockets).
The System V Interface Description (SVID) is a document describing the AT&T Unix System V operating system. It is to some extent a superset of the POSIX standard (see section POSIX (The Portable Operating System Interface)).
The GNU C library defines some of the facilities required by the SVID that are not also required by the ISO C or POSIX standards, for compatibility with System V Unix and other Unix systems (such as SunOS) which include these facilities. However, many of the more obscure and less generally useful facilities required by the SVID are not included. (In fact, Unix System V itself does not provide them all.)
This section describes some of the practical issues involved in using the GNU C library.
Libraries for use by C programs really consist of two parts: header files that define types and macros and declare variables and functions; and the actual library or archive that contains the definitions of the variables and functions.
(Recall that in C, a declaration merely provides information that a function or variable exists and gives its type. For a function declaration, information about the types of its arguments might be provided as well. The purpose of declarations is to allow the compiler to correctly process references to the declared variables and functions. A definition, on the other hand, actually allocates storage for a variable or says what a function does.)
In order to use the facilities in the GNU C library, you should be sure that your program source files include the appropriate header files. This is so that the compiler has declarations of these facilities available and can correctly process references to them. Once your program has been compiled, the linker resolves these references to the actual definitions provided in the archive file.
Header files are included into a program source file by the `#include' preprocessor directive. The C language supports two forms of this directive; the first,
#include "header"
is typically used to include a header file header that you write yourself; this would contain definitions and declarations describing the interfaces between the different parts of your particular application. By contrast,
#include <file.h>
is typically used to include a header file `file.h' that contains definitions and declarations for a standard library. This file would normally be installed in a standard place by your system administrator. You should use this second form for the C library header files.
Typically, `#include' directives are placed at the top of the C source file, before any other code. If you begin your source files with some comments explaining what the code in the file does (a good idea), put the `#include' directives immediately afterwards, following the feature test macro definition (see section Feature Test Macros).
For more information about the use of header files and `#include' directives, see section `Header Files' in The GNU C Preprocessor Manual.
The GNU C library provides several header files, each of which contains the type and macro definitions and variable and function declarations for a group of related facilities. This means that your programs may need to include several header files, depending on exactly which facilities you are using.
Some library header files include other library header files automatically. However, as a matter of programming style, you should not rely on this; it is better to explicitly include all the header files required for the library facilities you are using. The GNU C library header files have been written in such a way that it doesn't matter if a header file is accidentally included more than once; including a header file a second time has no effect. Likewise, if your program needs to include multiple header files, the order in which they are included doesn't matter.
Compatibility Note: Inclusion of standard header files in any order and any number of times works in any ISO C implementation. However, this has traditionally not been the case in many older C implementations.
Strictly speaking, you don't have to include a header file to use a function it declares; you could declare the function explicitly yourself, according to the specifications in this manual. But it is usually better to include the header file because it may define types and macros that are not otherwise available and because it may define more efficient macro replacements for some functions. It is also a sure way to have the correct declaration.
If we describe something as a function in this manual, it may have a macro definition as well. This normally has no effect on how your program runs--the macro definition does the same thing as the function would. In particular, macro equivalents for library functions evaluate arguments exactly once, in the same way that a function call would. The main reason for these macro definitions is that sometimes they can produce an inline expansion that is considerably faster than an actual function call.
Taking the address of a library function works even if it is also defined as a macro. This is because, in this context, the name of the function isn't followed by the left parenthesis that is syntactically necessary to recognize a macro call.
You might occasionally want to avoid using the macro definition of a function--perhaps to make your program easier to debug. There are two ways you can do this:
For example, suppose the header file `stdlib.h' declares a function
named abs with
extern int abs (int);
and also provides a macro definition for abs. Then, in:
#include <stdlib.h>
int f (int *i) { return (abs (++*i)); }
the reference to abs might refer to either a macro or a function.
On the other hand, in each of the following examples the reference is
to a function and not a macro.
#include <stdlib.h>
int g (int *i) { return ((abs)(++*i)); }
#undef abs
int h (int *i) { return (abs (++*i)); }
Since macro definitions that double for a function behave in exactly the same way as the actual function version, there is usually no need for any of these methods. In fact, removing macro definitions usually just makes your program slower.
The names of all library types, macros, variables and functions that come from the ISO C standard are reserved unconditionally; your program may not redefine these names. All other library names are reserved if your program explicitly includes the header file that defines or declares them. There are several reasons for these restrictions:
exit to do something completely different from
what the standard exit function does, for example. Preventing
this situation helps to make your programs easier to understand and
contributes to modularity and maintainability.
In addition to the names documented in this manual, reserved names include all external identifiers (global functions and variables) that begin with an underscore (`_') and all identifiers regardless of use that begin with either two underscores or an underscore followed by a capital letter are reserved names. This is so that the library and header files can define functions, variables, and macros for internal purposes without risk of conflict with names in user programs.
Some additional classes of identifier names are reserved for future extensions to the C language or the POSIX.1 environment. While using these names for your own purposes right now might not cause a problem, they do raise the possibility of conflict with future versions of the C or POSIX standards, so you should avoid these names.
float and long double arguments,
respectively.
In addition, some individual header files reserve names beyond those that they actually define. You only need to worry about these restrictions if your program includes that particular header file.
The exact set of features available when you compile a source file is controlled by which feature test macros you define.
If you compile your programs using `gcc -ansi', you get only the ISO C library features, unless you explicitly request additional features by defining one or more of the feature macros. See section `GNU CC Command Options' in The GNU CC Manual, for more information about GCC options.
You should define these macros by using `#define' preprocessor
directives at the top of your source code files. These directives
must come before any #include of a system header file. It
is best to make them the very first thing in the file, preceded only by
comments. You could also use the `-D' option to GCC, but it's
better if you make the source files indicate their own meaning in a
self-contained way.
1, then the
functionality from the POSIX.1 standard (IEEE Standard 1003.1) is made
available. If you define this macro with a value of 2, then both
the functionality from the POSIX.1 standard and the functionality from
the POSIX.2 standard (IEEE Standard 1003.2) are made available. This is
in addition to the ISO C facilities.
Some of the features derived from 4.3 BSD Unix conflict with the corresponding features specified by the POSIX.1 standard. If this macro is defined, the 4.3 BSD definitions take precedence over the POSIX definitions.
Due to the nature of some of the conflicts between 4.3 BSD and POSIX.1,
you need to use a special BSD compatibility library when linking
programs compiled for BSD compatibility. This is because some functions
must be defined in two different ways, one of them in the normal C
library, and one of them in the compatibility library. If your program
defines _BSD_SOURCE, you must give the option `-lbsd-compat'
to the compiler or linker when linking the program, to tell it to find
functions in this special compatibility library before looking for them in
the normal C library.
_POSIX_SOURCE and
_POSIX_C_SOURCE are automatically defined.
As the unification of all Unices, functionality only available in BSD and SVID is also included.
If the macro _XOPEN_SOURCE_EXTENDED is also defined, even more
functionality is available. The extra functions will make all functions
available which are necessary for the X/Open Unix brand.
If you want to get the full effect of _GNU_SOURCE but make the
BSD definitions take precedence over the POSIX definitions, use this
sequence of definitions:
#define _GNU_SOURCE #define _BSD_SOURCE #define _SVID_SOURCE
Note that if you do this, you must link your program with the BSD compatibility library by passing the `-lbsd-compat' option to the compiler or linker. Note: If you forget to do this, you may get very strange errors at run time.
Unlike on some other systems no special version of the C library must be used for linking. There is only one version but while compiling this it must have been specified to compile as thread safe.
We recommend you use _GNU_SOURCE in new programs. If you don't
specify the `-ansi' option to GCC and don't define any of these
macros explicitly, the effect is the same as defining
_POSIX_C_SOURCE to 2 and _POSIX_SOURCE,
_SVID_SOURCE, and _BSD_SOURCE to 1.
When you define a feature test macro to request a larger class of features,
it is harmless to define in addition a feature test macro for a subset of
those features. For example, if you define _POSIX_C_SOURCE, then
defining _POSIX_SOURCE as well has no effect. Likewise, if you
define _GNU_SOURCE, then defining either _POSIX_SOURCE or
_POSIX_C_SOURCE or _SVID_SOURCE as well has no effect.
Note, however, that the features of _BSD_SOURCE are not a subset of
any of the other feature test macros supported. This is because it defines
BSD features that take precedence over the POSIX features that are
requested by the other macros. For this reason, defining
_BSD_SOURCE in addition to the other feature test macros does have
an effect: it causes the BSD features to take priority over the conflicting
POSIX features.
Here is an overview of the contents of the remaining chapters of this manual.
sizeof
operator and the symbolic constant NULL, how to write functions
accepting variable numbers of arguments, and constants describing the
ranges and other properties of the numerical types. There is also a simple
debugging mechanism which allows you to put assertions in your code, and
have diagnostic messages printed if the tests fail.
isspace) and functions for
performing case conversion.
FILE * objects). These are the normal C library functions
from `stdio.h'.
char data type.
setjmp and
longjmp functions. These functions provide a facility for
goto-like jumps which can jump from one function to another.
If you already know the name of the facility you are interested in, you can look it up in section Summary of Library Facilities. This gives you a summary of its syntax and a pointer to where you can find a more detailed description. This appendix is particularly useful if you just want to verify the order and type of arguments to a function, for example. It also tells you what standard or system each function, variable, or macro is derived from.
Many functions in the GNU C library detect and report error conditions, and sometimes your programs need to check for these error conditions. For example, when you open an input file, you should verify that the file was actually opened correctly, and print an error message or take other appropriate action if the call to the library function failed.
This chapter describes how the error reporting facility works. Your program should include the header file `errno.h' to use this facility.
Most library functions return a special value to indicate that they have
failed. The special value is typically -1, a null pointer, or a
constant such as EOF that is defined for that purpose. But this
return value tells you only that an error has occurred. To find out
what kind of error it was, you need to look at the error code stored in the
variable errno. This variable is declared in the header file
`errno.h'.
errno contains the system error number. You can
change the value of errno.
Since errno is declared volatile, it might be changed
asynchronously by a signal handler; see section Defining Signal Handlers.
However, a properly written signal handler saves and restores the value
of errno, so you generally do not need to worry about this
possibility except when writing signal handlers.
The initial value of errno at program startup is zero. Many
library functions are guaranteed to set it to certain nonzero values
when they encounter certain kinds of errors. These error conditions are
listed for each function. These functions do not change errno
when they succeed; thus, the value of errno after a successful
call is not necessarily zero, and you should not use errno to
determine whether a call failed. The proper way to do that is
documented for each function. If the call the failed, you can
examine errno.
Many library functions can set errno to a nonzero value as a
result of calling other library functions which might fail. You should
assume that any library function might alter errno when the
function returns an error.
Portability Note: ISO C specifies errno as a
"modifiable lvalue" rather than as a variable, permitting it to be
implemented as a macro. For example, its expansion might involve a
function call, like *_errno (). In fact, that is what it is
on the GNU system itself. The GNU library, on non-GNU systems, does
whatever is right for the particular system.
There are a few library functions, like sqrt and atan,
that return a perfectly legitimate value in case of an error, but also
set errno. For these functions, if you want to check to see
whether an error occurred, the recommended method is to set errno
to zero before calling the function, and then check its value afterward.
All the error codes have symbolic names; they are macros defined in `errno.h'. The names start with `E' and an upper-case letter or digit; you should consider names of this form to be reserved names. See section Reserved Names.
The error code values are all positive integers and are all distinct,
with one exception: EWOULDBLOCK and EAGAIN are the same.
Since the values are distinct, you can use them as labels in a
switch statement; just don't use both EWOULDBLOCK and
EAGAIN. Your program should not make any other assumptions about
the specific values of these symbolic constants.
The value of errno doesn't necessarily have to correspond to any
of these macros, since some library functions might return other error
codes of their own for other situations. The only values that are
guaranteed to be meaningful for a particular library function are the
ones that this manual lists for that function.
On non-GNU systems, almost any system call can return EFAULT if
it is given an invalid pointer as an argument. Since this could only
happen as a result of a bug in your program, and since it will not
happen on the GNU system, we have saved space by not mentioning
EFAULT in the descriptions of individual functions.
In some Unix systems, many system calls can also return EFAULT if
given as an argument a pointer into the stack, and the kernel for some
obscure reason fails in its attempt to extend the stack. If this ever
happens, you should probably try using statically or dynamically
allocated memory instead of stack memory on that system.
The error code macros are defined in the header file `errno.h'. All of them expand into integer constant values. Some of these error codes can't occur on the GNU system, but they can occur using the GNU library on other systems.
You can choose to have functions resume after a signal that is handled,
rather than failing with EINTR; see section Primitives Interrupted by Signals.
exec functions (see section Executing a File) occupy too much memory space. This condition never arises in the
GNU system.
exec functions; see section Executing a File.
link (see section Hard Links) but
also when you rename a file with rename (see section Renaming Files).
In BSD and GNU, the number of open files is controlled by a resource
limit that can usually be increased. If you get this error, you might
want to increase the RLIMIT_NOFILE limit or make it unlimited;
see section Limiting Resource Usage.
rename can cause this error if the file being renamed already has
as many links as it can take (see section Renaming Files).
SIGPIPE signal; this signal terminates the program if not handled
or blocked. Thus, your program will never actually see EPIPE
unless it has handled or blocked SIGPIPE.
EWOULDBLOCK is another name for EAGAIN;
they are always the same in the GNU C library.
This error can happen in a few different situations:
select to find out
when the operation will be possible; see section Waiting for Input or Output.
Portability Note: In many older Unix systems, this condition
was indicated by EWOULDBLOCK, which was a distinct error code
different from EAGAIN. To make your program portable, you should
check for both codes and treat them the same.
fork
can return this error. It indicates that the shortage is expected to
pass, so your program can try the call again later and it may succeed.
It is probably a good idea to delay for a few seconds before trying it
again, to allow time for other processes to release scarce resources.
Such shortages are usually fairly serious and affect the whole system,
so usually an interactive program should report the error to the user
and return to its command loop.
EAGAIN (above).
The values are always the same, on every operating system.
C libraries in many older Unix systems have EWOULDBLOCK as a
separate error code.
connect; see section Making a Connection) never return
EAGAIN. Instead, they return EINPROGRESS to indicate that
the operation has begun and will take some time. Attempts to manipulate
the object before the call completes return EALREADY. You can
use the select function to find out when the pending operation
has completed; see section Waiting for Input or Output.
ENOMEM; you may get one or the
other from network operations.
EDESTADDRREQ instead.
connect.
PATH_MAX; see section Limits on File System Capacity) or host name too long (in gethostname or
sethostname; see section Host Identification).
fork. See section Limiting Resource Usage, for details on
the RLIMIT_NPROC limit.
On some systems chmod returns this error if you try to set the
sticky bit on a non-directory file; see section Assigning File Permissions.
term protocol return
this error for certain operations when the caller is not in the
foreground process group of the terminal. Users do not usually see this
error because functions such as read and write translate
it into a SIGTTIN or SIGTTOU signal. See section Job Control,
for information on process groups and these signals.
The following error codes are defined by the Linux/i386 kernel. They are not yet documented.
The library has functions and variables designed to make it easy for
your program to report informative error messages in the customary
format about the failure of a library call. The functions
strerror and perror give you the standard error message
for a given error code; the variable
program_invocation_short_name gives you convenient access to the
name of the program that encountered the error.
strerror function maps the error code (see section Checking for Errors) specified by the errnum argument to a descriptive error
message string. The return value is a pointer to this string.
The value errnum normally comes from the variable errno.
You should not modify the string returned by strerror. Also, if
you make subsequent calls to strerror, the string might be
overwritten. (But it's guaranteed that no library function ever calls
strerror behind your back.)
The function strerror is declared in `string.h'.
strerror_r function works like strerror but instead of
returning the error message in a statically allocated buffer shared by
all threads in the process, it writes the message string in the user
supplied buffer starting at buf with the length of n bytes.
At most n characters are written (including the NUL byte) so it is up to the user to select the buffer large enough.
This function should always be used in multi-threaded programs since
there is no way to guarantee the string returned by strerror
really belongs to the last call of the current thread.
This function strerror_r is a GNU extension and it is declared in
`string.h'.
stderr;
see section Standard Streams.
If you call perror with a message that is either a null
pointer or an empty string, perror just prints the error message
corresponding to errno, adding a trailing newline.
If you supply a non-null message argument, then perror
prefixes its output with this string. It adds a colon and a space
character to separate the message from the error string corresponding
to errno.
The function perror is declared in `stdio.h'.
strerror and perror produce the exact same message for any
given error code; the precise text varies from system to system. On the
GNU system, the messages are fairly short; there are no multi-line
messages or embedded newlines. Each error message begins with a capital
letter and does not include any terminating punctuation.
Compatibility Note: The strerror function is a new
feature of ISO C. Many older C systems do not support this function
yet.
Many programs that don't read input from the terminal are designed to
exit if any system call fails. By convention, the error message from
such a program should start with the program's name, sans directories.
You can find that name in the variable
program_invocation_short_name; the full file name is stored the
variable program_invocation_name:
argv[0]. Note
that this is not necessarily a useful file name; often it contains no
directory names. See section Program Arguments.
program_invocation_name minus
everything up to the last slash, if any.)
The library initialization code sets up both of these variables before
calling main.
Portability Note: These two variables are GNU extensions. If
you want your program to work with non-GNU libraries, you must save the
value of argv[0] in main, and then strip off the directory
names yourself. We added these extensions to make it possible to write
self-contained error-reporting subroutines that require no explicit
cooperation from main.
Here is an example showing how to handle failure to open a file
correctly. The function open_sesame tries to open the named file
for reading and returns a stream if successful. The fopen
library function returns a null pointer if it couldn't open the file for
some reason. In that situation, open_sesame constructs an
appropriate error message using the strerror function, and
terminates the program. If we were going to make some other library
calls before passing the error code to strerror, we'd have to
save it in a local variable instead, because those other library
functions might overwrite errno in the meantime.
#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
FILE *
open_sesame (char *name)
{
FILE *stream;
errno = 0;
stream = fopen (name, "r");
if (stream == NULL)
{
fprintf (stderr, "%s: Couldn't open file %s; %s\n",
program_invocation_short_name, name, strerror (errno));
exit (EXIT_FAILURE);
}
else
return stream;
}
The GNU system provides several methods for allocating memory space under explicit program control. They vary in generality and in efficiency.
malloc facility allows fully general dynamic allocation.
See section Unconstrained Allocation.
malloc but more
efficient and convenient for stacklike allocation. See section Obstacks.
alloca lets you allocate storage dynamically that
will be freed automatically. See section Automatic Storage with Variable Size.
Dynamic memory allocation is a technique in which programs determine as they are running where to store some information. You need dynamic allocation when the number of memory blocks you need, or how long you continue to need them, depends on the data you are working on.
For example, you may need a block to store a line read from an input file; since there is no limit to how long a line can be, you must allocate the storage dynamically and make it dynamically larger as you read more of the line.
Or, you may need a block for each record or each definition in the input data; since you can't know in advance how many there will be, you must allocate a new block for each record or definition as you read it.
When you use dynamic allocation, the allocation of a block of memory is an action that the program requests explicitly. You call a function or macro when you want to allocate space, and specify the size with an argument. If you want to free the space, you do so by calling another function or macro. You can do these things whenever you want, as often as you want.
The C language supports two kinds of memory allocation through the variables in C programs:
Dynamic allocation is not supported by C variables; there is no storage class "dynamic", and there can never be a C variable whose value is stored in dynamically allocated space. The only way to refer to dynamically allocated space is through a pointer. Because it is less convenient, and because the actual process of dynamic allocation requires more computation time, programmers generally use dynamic allocation only when neither static nor automatic allocation will serve.
For example, if you want to allocate dynamically some space to hold a
struct foobar, you cannot declare a variable of type struct
foobar whose contents are the dynamically allocated space. But you can
declare a variable of pointer type struct foobar * and assign it the
address of the space. Then you can use the operators `*' and
`->' on this pointer variable to refer to the contents of the space:
{
struct foobar *ptr
= (struct foobar *) malloc (sizeof (struct foobar));
ptr->name = x;
ptr->next = current_foobar;
current_foobar = ptr;
}
The most general dynamic allocation facility is malloc. It
allows you to allocate blocks of memory of any size at any time, make
them bigger or smaller at any time, and free the blocks individually at
any time (or never).
To allocate a block of memory, call malloc. The prototype for
this function is in `stdlib.h'.
The contents of the block are undefined; you must initialize it yourself
(or use calloc instead; see section Allocating Cleared Space).
Normally you would cast the value as a pointer to the kind of object
that you want to store in the block. Here we show an example of doing
so, and of initializing the space with zeros using the library function
memset (see section Copying and Concatenation):
struct foo *ptr; ... ptr = (struct foo *) malloc (sizeof (struct foo)); if (ptr == 0) abort (); memset (ptr, 0, sizeof (struct foo));
You can store the result of malloc into any pointer variable
without a cast, because ISO C automatically converts the type
void * to another type of pointer when necessary. But the cast
is necessary in contexts other than assignment operators or if you might
want your code to run in traditional C.
Remember that when allocating space for a string, the argument to
malloc must be one plus the length of the string. This is
because a string is terminated with a null character that doesn't count
in the "length" of the string but does need space. For example:
char *ptr; ... ptr = (char *) malloc (length + 1);
See section Representation of Strings, for more information about this.
malloc
If no more space is available, malloc returns a null pointer.
You should check the value of every call to malloc. It is
useful to write a subroutine that calls malloc and reports an
error if the value is a null pointer, returning only if the value is
nonzero. This function is conventionally called xmalloc. Here
it is:
void *
xmalloc (size_t size)
{
register void *value = malloc (size);
if (value == 0)
fatal ("virtual memory exhausted");
return value;
}
Here is a real example of using malloc (by way of xmalloc).
The function savestring will copy a sequence of characters into
a newly allocated null-terminated string:
char *
savestring (const char *ptr, size_t len)
{
register char *value = (char *) xmalloc (len + 1);
memcpy (value, ptr, len);
value[len] = '\0';
return value;
}
The block that malloc gives you is guaranteed to be aligned so
that it can hold any type of data. In the GNU system, the address is
always a multiple of eight on most systems, and a multiple of 16 on
64-bit systems. Only rarely is any higher boundary (such as a page
boundary) necessary; for those cases, use memalign or
valloc (see section Allocating Aligned Memory Blocks).
Note that the memory located after the end of the block is likely to be
in use for something else; perhaps a block already allocated by another
call to malloc. If you attempt to treat the block as longer than
you asked for it to be, you are liable to destroy the data that
malloc uses to keep track of its blocks, or you may destroy the
contents of another block. If you have already allocated a block and
discover you want it to be bigger, use realloc (see section Changing the Size of a Block).
malloc
When you no longer need a block that you got with malloc, use the
function free to make the block available to be allocated again.
The prototype for this function is in `stdlib.h'.
free function deallocates the block of storage pointed at
by ptr.
free. It's provided for
backward compatibility with SunOS; you should use free instead.
Freeing a block alters the contents of the block. Do not expect to find any data (such as a pointer to the next block in a chain of blocks) in the block after freeing it. Copy whatever you need out of the block before freeing it! Here is an example of the proper way to free all the blocks in a chain, and the strings that they point to:
struct chain
{
struct chain *next;
char *name;
}
void
free_chain (struct chain *chain)
{
while (chain != 0)
{
struct chain *next = chain->next;
free (chain->name);
free (chain);
chain = next;
}
}
Occasionally, free can actually return memory to the operating
system and make the process smaller. Usually, all it can do is allow a
later call to malloc to reuse the space. In the meantime, the
space remains in your program as part of a free-list used internally by
malloc.
There is no point in freeing blocks at the end of a program, because all of the program's space is given back to the system when the process terminates.
Often you do not know for certain how big a block you will ultimately need at the time you must begin to use the block. For example, the block might be a buffer that you use to hold a line being read from a file; no matter how long you make the buffer initially, you may encounter a line that is longer.
You can make the block longer by calling realloc. This function
is declared in `stdlib.h'.
realloc function changes the size of the block whose address is
ptr to be newsize.
Since the space after the end of the block may be in use, realloc
may find it necessary to copy the block to a new address where more free
space is available. The value of realloc is the new address of the
block. If the block needs to be moved, realloc copies the old
contents.
If you pass a null pointer for ptr, realloc behaves just
like `malloc (newsize)'. This can be convenient, but beware
that older implementations (before ISO C) may not support this
behavior, and will probably crash when realloc is passed a null
pointer.
Like malloc, realloc may return a null pointer if no
memory space is available to make the block bigger. When this happens,
the original block is untouched; it has not been modified or relocated.
In most cases it makes no difference what happens to the original block
when realloc fails, because the application program cannot continue
when it is out of memory, and the only thing to do is to give a fatal error
message. Often it is convenient to write and use a subroutine,
conventionally called xrealloc, that takes care of the error message
as xmalloc does for malloc:
void *
xrealloc (void *ptr, size_t size)
{
register void *value = realloc (ptr, size);
if (value == 0)
fatal ("Virtual memory exhausted");
return value;
}
You can also use realloc to make a block smaller. The reason you
is needed.
In several allocation implementations, making a block smaller sometimes
necessitates copying it, so it can fail if no other space is available.
If the new size you specify is the same as the old size, realloc
is guaranteed to change nothing and return the same address that you gave.
The function calloc allocates memory and clears it to zero. It
is declared in `stdlib.h'.
calloc returns.
You could define calloc as follows:
void *
calloc (size_t count, size_t eltsize)
{
size_t size = count * eltsize;
void *value = malloc (size);
if (value != 0)
memset (value, 0, size);
return value;
}
But in general, it is not guaranteed that calloc calls
malloc internally. Therefore, if an application provides its own
malloc/realloc/free outside the C library, it
should always define calloc, too.
malloc
As apposed to other versions, the malloc in GNU libc does not
round up block sizes to powers of two, neither for large nor for small
sizes. Neighboring chunks can be coalesced on a free no matter
what their size is. This makes the implementation suitable for all
kinds of allocation patterns without generally incurring high memory
waste through fragmentation.
Very large blocks (much larger than a page) are allocated with
mmap (anonymous or via /dev/zero) by this implementation.
This has the great advantage that these chunks are returned to the
system immediately when they are freed. Therefore, it cannot happen
that a large chunk becomes "locked" in between smaller ones and even
after calling free wastes memory. The size threshold for
mmap to be used can be adjusted with mallopt. The use of
mmap can also be disabled completely.
The address of a block returned by malloc or realloc in
the GNU system is always a multiple of eight (or sixteen on 64-bit
systems). If you need a block whose address is a multiple of a higher
power of two than that, use memalign or valloc. These
functions are declared in `stdlib.h'.
With the GNU library, you can use free to free the blocks that
memalign and valloc return. That does not work in BSD,
however--BSD does not provide any way to free such blocks.
memalign function allocates a block of size bytes whose
address is a multiple of boundary. The boundary must be a
power of two! The function memalign works by allocating a
somewhat larger block, and then returning an address within the block
that is on the specified boundary.
valloc is like using memalign and passing the page size
as the value of the second argument. It is implemented like this:
void *
valloc (size_t size)
{
return memalign (getpagesize (), size);
}
You can adjust some parameters for dynamic memory allocation with the
mallopt function. This function is the general SVID/XPG
interface, defined in `malloc.h'.
mallopt, the param argument specifies the
parameter to be set, and value the new value to be set. Possible
choices for param, as defined in `malloc.h', are:
M_TRIM_THRESHOLD
sbrk to be called with a negative argument in
order to return memory to the system.
M_TOP_PAD
sbrk is required. It also specifies the
number of bytes to retain when shrinking the heap by calling sbrk
with a negative argument. This provides the necessary hysteresis in
heap size such that excessive amounts of system calls can be avoided.
M_MMAP_THRESHOLD
mmap system call. This way it is guaranteed
that the memory for these chunks can be returned to the system on
free.
M_MMAP_MAX
mmap. Setting this
to zero disables all use of mmap.
You can ask malloc to check the consistency of dynamic storage by
using the mcheck function. This function is a GNU extension,
declared in `malloc.h'.
mcheck tells malloc to perform occasional
consistency checks. These will catch things such as writing
past the end of a block that was allocated with malloc.
The abortfn argument is the function to call when an inconsistency
is found. If you supply a null pointer, then mcheck uses a
default function which prints a message and calls abort
(see section Aborting a Program). The function you supply is called with
one argument, which says what sort of inconsistency was detected; its
type is described below.
It is too late to begin allocation checking once you have allocated
anything with malloc. So mcheck does nothing in that
case. The function returns -1 if you call it too late, and
0 otherwise (when it is successful).
The easiest way to arrange to call mcheck early enough is to use
the option `-lmcheck' when you link your program; then you don't
need to modify your program source at all.
mprobe function lets you explicitly check for inconsistencies
in a particular allocated block. You must have already called
mcheck at the beginning of the program, to do its occasional
checks; calling mprobe requests an additional consistency check
to be done at the time of the call.
The argument pointer must be a pointer returned by malloc
or realloc. mprobe returns a value that says what
inconsistency, if any, was found. The values are described below.
MCHECK_DISABLED
mcheck was not called before the first allocation.
No consistency checking can be done.
MCHECK_OK
MCHECK_HEAD
MCHECK_TAIL
MCHECK_FREE
The GNU C library lets you modify the behavior of malloc,
realloc, and free by specifying appropriate hook
functions. You can use these hooks to help you debug programs that use
dynamic storage allocation, for example.
The hook variables are declared in `malloc.h'.
malloc
uses whenever it is called. You should define this function to look
like malloc; that is, like:
void *function (size_t size)
realloc
uses whenever it is called. You should define this function to look
like realloc; that is, like:
void *function (void *ptr, size_t size)
free
uses whenever it is called. You should define this function to look
like free; that is, like:
void function (void *ptr)
You must make sure that the function you install as a hook for one of these functions does not call that function recursively without restoring the old value of the hook first! Otherwise, your program will get stuck in an infinite recursion.
Here is an example showing how to use __malloc_hook properly. It
installs a function that prints out information every time malloc
is called.
static void *(*old_malloc_hook) (size_t);
static void *
my_malloc_hook (size_t size)
{
void *result;
__malloc_hook = old_malloc_hook;
result = malloc (size);
/* printf might call malloc, so protect it too. */
printf ("malloc (%u) returns %p\n", (unsigned int) size, result);
__malloc_hook = my_malloc_hook;
return result;
}
main ()
{
...
old_malloc_hook = __malloc_hook;
__malloc_hook = my_malloc_hook;
...
}
The mcheck function (see section Heap Consistency Checking) works by
installing such hooks.
malloc
You can get information about dynamic storage allocation by calling the
mallinfo function. This function and its associated data type
are declared in `malloc.h'; they are an extension of the standard
SVID/XPG version.
int arena
sbrk by
malloc, in bytes.
int ordblks
malloc requests; see
section Efficiency Considerations for malloc.)
int smblks
int hblks
mmap.
int hblkhd
mmap, in bytes.
int usmblks
int fsmblks
int uordblks
malloc.
int fordblks
int keepcost
struct mallinfo.
malloc-Related Functions
Here is a summary of the functions that work with malloc:
void *malloc (size_t size)
void free (void *addr)
malloc. See section Freeing Memory Allocated with malloc.
void *realloc (void *addr, size_t size)
malloc larger or smaller,
possibly by copying it to a new location. See section Changing the Size of a Block.
void *calloc (size_t count, size_t eltsize)
malloc, and set its contents to zero. See section Allocating Cleared Space.
void *valloc (size_t size)
void *memalign (size_t size, size_t boundary)
int mallopt (int param, int value)
int mcheck (void (*abortfn) (void))
malloc to perform occasional consistency checks on
dynamically allocated memory, and to call abortfn when an
inconsistency is found. See section Heap Consistency Checking.
void *(*__malloc_hook) (size_t size)
malloc uses whenever it is called.
void *(*__realloc_hook) (void *ptr, size_t size)
realloc uses whenever it is called.
void (*__free_hook) (void *ptr)
free uses whenever it is called.
struct mallinfo mallinfo (void)
malloc.
An obstack is a pool of memory containing a stack of objects. You can create any number of separate obstacks, and then allocate objects in specified obstacks. Within each obstack, the last object allocated must always be the first one freed, but distinct obstacks are independent of each other.
Aside from this one constraint of order of freeing, obstacks are totally general: an obstack can contain any number of objects of any size. They are implemented with macros, so allocation is usually very fast as long as the objects are usually small. And the only space overhead per object is the padding needed to start each object on a suitable boundary.
The utilities for manipulating obstacks are declared in the header file `obstack.h'.
struct
obstack. This structure has a small fixed size; it records the status
of the obstack and how to find the space in which objects are allocated.
It does not contain any of the objects themselves. You should not try
to access the contents of the structure directly; use only the functions
described in this chapter.
You can declare variables of type struct obstack and use them as
obstacks, or you can allocate obstacks dynamically like any other kind
of object. Dynamic allocation of obstacks allows your program to have a
variable number of different stacks. (You can even allocate an
obstack structure in another obstack, but this is rarely useful.)
All the functions that work with obstacks require you to specify which
obstack to use. You do this with a pointer of type struct obstack
*. In the following, we often say "an obstack" when strictly
speaking the object at hand is such a pointer.
The objects in the obstack are packed into large blocks called
chunks. The struct obstack structure points to a chain of
the chunks currently in use.
The obstack library obtains a new chunk whenever you allocate an object
that won't fit in the previous chunk. Since the obstack library manages
chunks automatically, you don't need to pay much attention to them, but
you do need to supply a function which the obstack library should use to
get a chunk. Usually you supply a function which uses malloc
directly or indirectly. You must also supply a function to free a chunk.
These matters are described in the following section.
Each source file in which you plan to use the obstack functions must include the header file `obstack.h', like this:
#include <obstack.h>
Also, if the source file uses the macro obstack_init, it must
declare or define two functions or macros that will be called by the
obstack library. One, obstack_chunk_alloc, is used to allocate
the chunks of memory into which objects are packed. The other,
obstack_chunk_free, is used to return chunks when the objects in
them are freed. These macros should appear before any use of obstacks
in the source file.
Usually these are defined to use malloc via the intermediary
xmalloc (see section Unconstrained Allocation). This is done with
the following pair of macro definitions:
#define obstack_chunk_alloc xmalloc #define obstack_chunk_free free
Though the storage you get using obstacks really comes from malloc,
using obstacks is faster because malloc is called less often, for
larger blocks of memory. See section Obstack Chunks, for full details.
At run time, before the program can use a struct obstack object
as an obstack, it must initialize the obstack by calling
obstack_init.
obstack_chunk_alloc function. It
returns 0 if obstack_chunk_alloc returns a null pointer, meaning
that it is out of memory. Otherwise, it returns 1. If you supply an
obstack_chunk_alloc function that calls exit
(see section Program Termination) or longjmp (see section Non-Local Exits) when out of memory, you can safely ignore the value that
obstack_init returns.
Here are two examples of how to allocate the space for an obstack and initialize it. First, an obstack that is a static variable:
static struct obstack myobstack; ... obstack_init (&myobstack);
Second, an obstack that is itself dynamically allocated:
struct obstack *myobstack_ptr = (struct obstack *) xmalloc (sizeof (struct obstack)); obstack_init (myobstack_ptr);
The most direct way to allocate an object in an obstack is with
obstack_alloc, which is invoked almost like malloc.
struct obstack
object which represents the obstack. Each obstack function or macro
requires you to specify an obstack-ptr as the first argument.
This function calls the obstack's obstack_chunk_alloc function if
it needs to allocate a new chunk of memory; it returns a null pointer if
obstack_chunk_alloc returns one. In that case, it has not
changed the amount of memory allocated in the obstack. If you supply an
obstack_chunk_alloc function that calls exit
(see section Program Termination) or longjmp (see section Non-Local Exits) when out of memory, then obstack_alloc will never return
a null pointer.
For example, here is a function that allocates a copy of a string str
in a specific obstack, which is in the variable string_obstack:
struct obstack string_obstack;
char *
copystring (char *string)
{
size_t len = strlen (string) + 1;
char *s = (char *) obstack_alloc (&string_obstack, len);
memcpy (s, string, len);
return s;
}
To allocate a block with specified contents, use the function
obstack_copy, declared like this:
obstack_alloc.
obstack_copy, but appends an extra byte containing a null
character. This extra byte is not counted in the argument size.
The obstack_copy0 function is convenient for copying a sequence
of characters into an obstack as a null-terminated string. Here is an
example of its use:
char *
obstack_savestring (char *addr, int size)
{
return obstack_copy0 (&myobstack, addr, size);
}
Contrast this with the previous example of savestring using
malloc (see section Basic Storage Allocation).
To free an object allocated in an obstack, use the function
obstack_free. Since the obstack is a stack of objects, freeing
one object automatically frees all other objects allocated more recently
in the same obstack.
Note that if object is a null pointer, the result is an
uninitialized obstack. To free all storage in an obstack but leave it
valid for further allocation, call obstack_free with the address
of the first object allocated on the obstack:
obstack_free (obstack_ptr, first_object_allocated_ptr);
Recall that the objects in an obstack are grouped into chunks. When all the objects in a chunk become free, the obstack library automatically frees the chunk (see section Preparing for Using Obstacks). Then other obstacks, or non-obstack allocation, can reuse the space of the chunk.
The interfaces for using obstacks may be defined either as functions or as macros, depending on the compiler. The obstack facility works with all C compilers, including both ISO C and traditional C, but there are precautions you must take if you plan to use compilers other than GNU C.
If you are using an old-fashioned non-ISO C compiler, all the obstack "functions" are actually defined only as macros. You can call these macros like functions, but you cannot use them in any other way (for example, you cannot take their address).
Calling the macros requires a special precaution: namely, the first operand (the obstack pointer) may not contain any side effects, because it may be computed more than once. For example, if you write this:
obstack_alloc (get_obstack (), 4);
you will find that get_obstack may be called several times.
If you use *obstack_list_ptr++ as the obstack pointer argument,
you will get very strange results since the incrementation may occur
several times.
In ISO C, each function has both a macro definition and a function definition. The function definition is used if you take the address of the function without calling it. An ordinary call uses the macro definition by default, but you can request the function definition instead by writing the function name in parentheses, as shown here:
char *x; void *(*funcp) (); /* Use the macro. */ x = (char *) obstack_alloc (obptr, size); /* Call the function. */ x = (char *) (obstack_alloc) (obptr, size); /* Take the address of the function. */ funcp = obstack_alloc;
This is the same situation that exists in ISO C for the standard library functions. See section Macro Definitions of Functions.
Warning: When you do use the macros, you must observe the precaution of avoiding side effects in the first operand, even in ISO C.
If you use the GNU C compiler, this precaution is not necessary, because various language extensions in GNU C permit defining the macros so as to compute each argument only once.
Because storage in obstack chunks is used sequentially, it is possible to build up an object step by step, adding one or more bytes at a time to the end of the object. With this technique, you do not need to know how much data you will put in the object until you come to the end of it. We call this the technique of growing objects. The special functions for adding data to the growing object are described in this section.
You don't need to do anything special when you start to grow an object.
Using one of the functions to add data to the object automatically
starts it. However, it is necessary to say explicitly when the object is
finished. This is done with the function obstack_finish.
The actual address of the object thus built up is not known until the object is finished. Until then, it always remains possible that you will add so much data that the object must be copied into a new chunk.
While the obstack is in use for a growing object, you cannot use it for ordinary allocation of another object. If you try to do so, the space already added to the growing object will become part of the other object.
obstack_blank, which adds space without initializing it.
obstack_grow, which is
the growing-object analogue of obstack_copy. It adds size
bytes of data to the growing object, copying the contents from
data.
obstack_copy0. It adds
size bytes copied from data, followed by an additional null
character.
obstack_1grow.
It adds a single byte containing c to the growing object.
obstack_ptr_grow. It adds sizeof (void *) bytes
containing the value of data.
int can be added by using the
obstack_int_grow function. It adds sizeof (int) bytes to
the growing object and initializes them with the value of data.
obstack_finish to close it off and return its final address.
Once you have finished the object, the obstack is available for ordinary allocation or for growing another object.
This function can return a null pointer under the same conditions as
obstack_alloc (see section Allocation in an Obstack).
When you build an object by growing it, you will probably need to know
afterward how long it became. You need not keep track of this as you grow
the object, because you can find out the length from the obstack just
before finishing the object with the function obstack_object_size,
declared as follows:
obstack_object_size will return zero.
If you have started growing an object and wish to cancel it, you should finish it and then free it, like this:
obstack_free (obstack_ptr, obstack_finish (obstack_ptr));
This has no effect if no object was growing.
You can use obstack_blank with a negative size argument to make
the current object smaller. Just don't try to shrink it beyond zero
length--there's no telling what will happen if you do that.
The usual functions for growing objects incur overhead for checking whether there is room for the new growth in the current chunk. If you are frequently constructing objects in small steps of growth, this overhead can be significant.
You can reduce the overhead by using special "fast growth" functions that grow the object without checking. In order to have a robust program, you must do the checking yourself. If you do this checking in the simplest way each time you are about to add data to the object, you have not saved anything, because that is what the ordinary growth functions do. But if you can arrange to check less often, or check more efficiently, then you make the program faster.
The function obstack_room returns the amount of room available
in the current chunk. It is declared as follows:
While you know there is room, you can use these fast growth functions for adding data to a growing object:
obstack_1grow_fast adds one byte containing the
character c to the growing object in obstack obstack-ptr.
obstack_ptr_grow_fast adds sizeof (void *)
bytes containing the value of data to the growing object in
obstack obstack-ptr.
obstack_int_grow_fast adds sizeof (int) bytes
containing the value of data to the growing object in obstack
obstack-ptr.
obstack_blank_fast adds size bytes to the
growing object in obstack obstack-ptr without initializing them.
When you check for space using obstack_room and there is not
enough room for what you want to add, the fast growth functions
are not safe. In this case, simply use the corresponding ordinary
growth function instead. Very soon this will copy the object to a
new chunk; then there will be lots of room available again.
So, each time you use an ordinary growth function, check afterward for
sufficient space using obstack_room. Once the object is copied
to a new chunk, there will be plenty of space again, so the program will
start using the fast growth functions again.
Here is an example:
void
add_string (struct obstack *obstack, const char *ptr, int len)
{
while (len > 0)
{
int room = obstack_room (obstack);
if (room == 0)
{
/* Not enough room. Add one character slowly,
which may copy to a new chunk and make room. */
obstack_1grow (obstack, *ptr++);
len--;
}
else
{
if (room > len)
room = len;
/* Add fast as much as we have room for. */
len -= room;
while (room-- > 0)
obstack_1grow_fast (obstack, *ptr++);
}
}
}
Here are functions that provide information on the current status of allocation in an obstack. You can use them to learn about an object while still growing it.
If no object is growing, this value says where the next object you allocate will start (once again assuming it fits in the current chunk).
obstack_next_free
returns the same value as obstack_base.
obstack_next_free (obstack-ptr) - obstack_base (obstack-ptr)
Each obstack has an alignment boundary; each object allocated in the obstack automatically starts on an address that is a multiple of the specified boundary. By default, this boundary is 4 bytes.
To access an obstack's alignment boundary, use the macro
obstack_alignment_mask, whose function prototype looks like
this:
The expansion of the macro obstack_alignment_mask is an lvalue,
so you can alter the mask by assignment. For example, this statement:
obstack_alignment_mask (obstack_ptr) = 0;
has the effect of turning off alignment processing in the specified obstack.
Note that a change in alignment mask does not take effect until
after the next time an object is allocated or finished in the
obstack. If you are not growing an object, you can make the new
alignment mask take effect immediately by calling obstack_finish.
This will finish a zero-length object and then do proper alignment for
the next object.
Obstacks work by allocating space for themselves in large chunks, and then parceling out space in the chunks to satisfy your requests. Chunks are normally 4096 bytes long unless you specify a different chunk size. The chunk size includes 8 bytes of overhead that are not actually used for storing objects. Regardless of the specified size, longer chunks will be allocated when necessary for long objects.
The obstack library allocates chunks by calling the function
obstack_chunk_alloc, which you must define. When a chunk is no
longer needed because you have freed all the objects in it, the obstack
library frees the chunk by calling obstack_chunk_free, which you
must also define.
These two must be defined (as macros) or declared (as functions) in each
source file that uses obstack_init (see section Creating Obstacks).
Most often they are defined as macros like this:
#define obstack_chunk_alloc xmalloc #define obstack_chunk_free free
Note that these are simple macros (no arguments). Macro definitions with
arguments will not work! It is necessary that obstack_chunk_alloc
or obstack_chunk_free, alone, expand into a function name if it is
not itself a function name.
If you allocate chunks with malloc, the chunk size should be a
power of 2. The default chunk size, 4096, was chosen because it is long
enough to satisfy many typical requests on the obstack yet short enough
not to waste too much memory in the portion of the last chunk not yet used.
Since this macro expands to an lvalue, you can specify a new chunk size by assigning it a new value. Doing so does not affect the chunks already allocated, but will change the size of chunks allocated for that particular obstack in the future. It is unlikely to be useful to make the chunk size smaller, but making it larger might improve efficiency if you are allocating many objects whose size is comparable to the chunk size. Here is how to do so cleanly:
if (obstack_chunk_size (obstack_ptr) < new-chunk-size) obstack_chunk_size (obstack_ptr) = new-chunk-size;
Here is a summary of all the functions associated with obstacks. Each
takes the address of an obstack (struct obstack *) as its first
argument.
void obstack_init (struct obstack *obstack-ptr)
void *obstack_alloc (struct obstack *obstack-ptr, int size)
void *obstack_copy (struct obstack *obstack-ptr, void *address, int size)
void *obstack_copy0 (struct obstack *obstack-ptr, void *address, int size)
void obstack_free (struct obstack *obstack-ptr, void *object)
void obstack_blank (struct obstack *obstack-ptr, int size)
void obstack_grow (struct obstack *obstack-ptr, void *address, int size)
void obstack_grow0 (struct obstack *obstack-ptr, void *address, int size)
void obstack_1grow (struct obstack *obstack-ptr, char data-char)
void *obstack_finish (struct obstack *obstack-ptr)
int obstack_object_size (struct obstack *obstack-ptr)
void obstack_blank_fast (struct obstack *obstack-ptr, int size)
void obstack_1grow_fast (struct obstack *obstack-ptr, char data-char)
int obstack_room (struct obstack *obstack-ptr)
int obstack_alignment_mask (struct obstack *obstack-ptr)
int obstack_chunk_size (struct obstack *obstack-ptr)
void *obstack_base (struct obstack *obstack-ptr)
void *obstack_next_free (struct obstack *obstack-ptr)
The function alloca supports a kind of half-dynamic allocation in
which blocks are allocated dynamically but freed automatically.
Allocating a block with alloca is an explicit action; you can
allocate as many blocks as you wish, and compute the size at run time. But
all the blocks are freed when you exit the function that alloca was
called from, just as if they were automatic variables declared in that
function. There is no way to free the space explicitly.
The prototype for alloca is in `stdlib.h'. This function is
a BSD extension.
alloca is the address of a block of size
bytes of storage, allocated in the stack frame of the calling function.
Do not use alloca inside the arguments of a function call--you
will get unpredictable results, because the stack space for the
alloca would appear on the stack in the middle of the space for
the function arguments. An example of what to avoid is foo (x,
alloca (4), y).
alloca Example
As an example of use of alloca, here is a function that opens a file
name made from concatenating two argument strings, and returns a file
descriptor or minus one signifying failure:
int
open2 (char *str1, char *str2, int flags, int mode)
{
char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
stpcpy (stpcpy (name, str1), str2);
return open (name, flags, mode);
}
Here is how you would get the same results with malloc and
free:
int
open2 (char *str1, char *str2, int flags, int mode)
{
char *name = (char *) malloc (strlen (str1) + strlen (str2) + 1);
int desc;
if (name == 0)
fatal ("virtual memory exceeded");
stpcpy (stpcpy (name, str1), str2);
desc = open (name, flags, mode);
free (name);
return desc;
}
As you can see, it is simpler with alloca. But alloca has
other, more important advantages, and some disadvantages.
alloca
Here are the reasons why alloca may be preferable to malloc:
alloca wastes very little space and is very fast. (It is
open-coded by the GNU C compiler.)
alloca does not have separate pools for different sizes of
block, space used for any size block can be reused for any other size.
alloca does not cause storage fragmentation.
longjmp (see section Non-Local Exits)
automatically free the space allocated with alloca when they exit
through the function that called alloca. This is the most
important reason to use alloca.
To illustrate this, suppose you have a function
open_or_report_error which returns a descriptor, like
open, if it succeeds, but does not return to its caller if it
fails. If the file cannot be opened, it prints an error message and
jumps out to the command level of your program using longjmp.
Let's change open2 (see section alloca Example) to use this
subroutine:
int
open2 (char *str1, char *str2, int flags, int mode)
{
char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
stpcpy (stpcpy (name, str1), str2);
return open_or_report_error (name, flags, mode);
}
Because of the way alloca works, the storage it allocates is
freed even when an error occurs, with no special effort required.
By contrast, the previous definition of open2 (which uses
malloc and free) would develop a storage leak if it were
changed in this way. Even if you are willing to make more changes to
fix it, there is no easy way to do so.
alloca
These are the disadvantages of alloca in comparison with
malloc:
alloca, so it is less
portable. However, a slower emulation of alloca written in C
is available for use on systems with this deficiency.
In GNU C, you can replace most uses of alloca with an array of
variable size. Here is how open2 would look then:
int open2 (char *str1, char *str2, int flags, int mode)
{
char name[strlen (str1) + strlen (str2) + 1];
stpcpy (stpcpy (name, str1), str2);
return open (name, flags, mode);
}
But alloca is not always equivalent to a variable-sized array, for
several reasons:
alloca
remains until the end of the function.
alloca within a loop, allocating an
additional block on each iteration. This is impossible with
variable-sized arrays.
Note: If you mix use of alloca and variable-sized arrays
within one function, exiting a scope in which a variable-sized array was
declared frees all blocks allocated with alloca during the
execution of that scope.
Any system of dynamic memory allocation has overhead: the amount of space it uses is more than the amount the program asks for. The relocating memory allocator achieves very low overhead by moving blocks in memory as necessary, on its own initiative.
When you allocate a block with malloc, the address of the block
never changes unless you use realloc to change its size. Thus,
you can safely store the address in various places, temporarily or
permanently, as you like. This is not safe when you use the relocating
memory allocator, because any and all relocatable blocks can move
whenever you allocate memory in any fashion. Even calling malloc
or realloc can move the relocatable blocks.
For each relocatable block, you must make a handle---a pointer object in memory, designated to store the address of that block. The relocating allocator knows where each block's handle is, and updates the address stored there whenever it moves the block, so that the handle always points to the block. Each time you access the contents of the block, you should fetch its address anew from the handle.
To call any of the relocating allocator functions from a signal handler is almost certainly incorrect, because the signal could happen at any time and relocate all the blocks. The only way to make this safe is to block the signal around any access to the contents of any relocatable block--not a convenient mode of operation. See section Signal Handling and Nonreentrant Functions.
In the descriptions below, handleptr designates the address of the handle. All the functions are declared in `malloc.h'; all are GNU extensions.
*handleptr and returns
a non-null pointer to indicate success.
If r_alloc can't get the space needed, it stores a null pointer
in *handleptr, and returns a null pointer.
*handleptr points to, and stores a null pointer
in *handleptr to show it doesn't point to an allocated
block any more.
r_re_alloc adjusts the size of the block that
*handleptr points to, making it size bytes long. It
stores the address of the resized block in *handleptr and
returns a non-null pointer to indicate success.
If enough memory is not available, this function returns a null pointer
and does not modify *handleptr.
Programs that work with characters and strings often need to classify a character--is it alphabetic, is it a digit, is it whitespace, and so on--and perform case conversion operations on characters. The functions in the header file `ctype.h' are provided for this purpose.
Since the choice of locale and character set can alter the
classifications of particular character codes, all of these functions
are affected by the current locale. (More precisely, they are affected
by the locale currently selected for character classification--the
LC_CTYPE category; see section Categories of Activities that Locales Affect.)
This section explains the library functions for classifying characters.
For example, isalpha is the function to test for an alphabetic
character. It takes one argument, the character to test, and returns a
nonzero integer if the character is alphabetic, and zero otherwise. You
would use it like this:
if (isalpha (c))
printf ("The character `%c' is alphabetic.\n", c);
Each of the functions in this section tests for membership in a
particular class of characters; each has a name starting with `is'.
Each of them takes one argument, which is a character to test, and
returns an int which is treated as a boolean value. The
character argument is passed as an int, and it may be the
constant value EOF instead of a real character.
The attributes of any given character can vary between locales. See section Locales and Internationalization, for more information on locales.
These functions are declared in the header file `ctype.h'.
islower or isupper is true of a character, then
isalpha is also true.
In some locales, there may be additional characters for which
isalpha is true--letters which are neither upper case nor lower
case. But in the standard "C" locale, there are no such
additional characters.
isalpha or isdigit is
true of a character, then isalnum is also true.
"C" locale, isspace returns true for only the standard
whitespace characters:
' '
'\f'
'\n'
'\r'
'\t'
'\v'
unsigned char value that fits
into the US/UK ASCII character set. This function is a BSD extension
and is also an SVID extension.
This section explains the library functions for performing conversions
such as case mappings on characters. For example, toupper
converts any character to upper case if possible. If the character
can't be converted, toupper returns it unchanged.
These functions take one argument of type int, which is the
character to convert, and return the converted character as an
int. If the conversion is not applicable to the argument given,
the argument is returned unchanged.
Compatibility Note: In pre-ISO C dialects, instead of
returning the argument unchanged, these functions may fail when the
argument is not suitable for the conversion. Thus for portability, you
may need to write islower(c) ? toupper(c) : c rather than just
toupper(c).
These functions are declared in the header file `ctype.h'.
tolower returns the corresponding
lower-case letter. If c is not an upper-case letter,
c is returned unchanged.
tolower returns the corresponding
upper-case letter. Otherwise c is returned unchanged.
unsigned char value
that fits into the US/UK ASCII character set, by clearing the high-order
bits. This function is a BSD extension and is also an SVID extension.
tolower, and is provided for compatibility
with the SVID. See section SVID (The System V Interface Description).
toupper, and is provided for compatibility
with the SVID.
Operations on strings (or arrays of characters) are an important part of
many programs. The GNU C library provides an extensive set of string
utility functions, including functions for copying, concatenating,
comparing, and searching strings. Many of these functions can also
operate on arbitrary regions of storage; for example, the memcpy
function can be used to copy the contents of any kind of array.
It's fairly common for beginning C programmers to "reinvent the wheel" by duplicating this functionality in their own code, but it pays to become familiar with the library functions and to make use of them, since this offers benefits in maintenance, efficiency, and portability.
For instance, you could easily compare one string to another in two
lines of C code, but if you use the built-in strcmp function,
you're less likely to make a mistake. And, since these library
functions are typically highly optimized, your program may run faster
too.
This section is a quick summary of string concepts for beginning C programmers. It describes how character strings are represented in C and some common pitfalls. If you are already familiar with this material, you can skip this section.
A string is an array of char objects. But string-valued
variables are usually declared to be pointers of type char *.
Such variables do not include space for the text of a string; that has
to be stored somewhere else--in an array variable, a string constant,
or dynamically allocated memory (see section Memory Allocation). It's up to
you to store the address of the chosen memory space into the pointer
variable. Alternatively you can store a null pointer in the
pointer variable. The null pointer does not point anywhere, so
attempting to reference the string it points to gets an error.
By convention, a null character, '\0', marks the end of a
string. For example, in testing to see whether the char *
variable p points to a null character marking the end of a string,
you can write !*p or *p == '\0'.
A null character is quite different conceptually from a null pointer,
although both are represented by the integer 0.
String literals appear in C program source as strings of
characters between double-quote characters (`"'). In ISO C,
string literals can also be formed by string concatenation:
"a" "b" is the same as "ab". Modification of string
literals is not allowed by the GNU C compiler, because literals
are placed in read-only storage.
Character arrays that are declared const cannot be modified
either. It's generally good style to declare non-modifiable string
pointers to be of type const char *, since this often allows the
C compiler to detect accidental modifications as well as providing some
amount of documentation about what your program intends to do with the
string.
The amount of memory allocated for the character array may extend past the null character that normally marks the end of the string. In this document, the term allocation size is always used to refer to the total amount of memory allocated for the string, while the term length refers to the number of characters up to (but not including) the terminating null character.
A notorious source of program bugs is trying to put more characters in a string than fit in its allocated size. When writing code that extends strings or moves characters into a pre-allocated array, you should be very careful to keep track of the length of the text and make explicit checks for overflowing the array. Many of the library functions do not do this for you! Remember also that you need to allocate an extra byte to hold the null character that marks the end of the string.
This chapter describes both functions that work on arbitrary arrays or blocks of memory, and functions that are specific to null-terminated arrays of characters.
Functions that operate on arbitrary blocks of memory have names
beginning with `mem' (such as memcpy) and invariably take an
argument which specifies the size (in bytes) of the block of memory to
operate on. The array arguments and return values for these functions
have type void *, and as a matter of style, the elements of these
arrays are referred to as "bytes". You can pass any kind of pointer
to these functions, and the sizeof operator is useful in
computing the value for the size argument.
In contrast, functions that operate specifically on strings have names
beginning with `str' (such as strcpy) and look for a null
character to terminate the string instead of requiring an explicit size
argument to be passed. (Some of these functions accept a specified
maximum length, but they also check for premature termination with a
null character.) The array arguments and return values for these
functions have type char *, and the array elements are referred
to as "characters".
In many cases, there are both `mem' and `str' versions of a function. The one that is more appropriate to use depends on the exact situation. When your program is manipulating arbitrary arrays or blocks of storage, then you should always use the `mem' functions. On the other hand, when you are manipulating null-terminated strings it is usually more convenient to use the `str' functions, unless you already know the length of the string in advance.
You can get the length of a string using the strlen function.
This function is declared in the header file `string.h'.
strlen function returns the length of the null-terminated
string s. (In other words, it returns the offset of the terminating
null character within the array.)
For example,
strlen ("hello, world")
=> 12
When applied to a character array, the strlen function returns
the length of the string stored there, not its allocation size. You can
get the allocation size of the character array that holds a string using
the sizeof operator:
char string[32] = "hello, world";
sizeof (string)
=> 32
strlen (string)
=> 12
You can use the functions described in this section to copy the contents of strings and arrays, or to append the contents of one string to another. These functions are declared in the header file `string.h'.
A helpful way to remember the ordering of the arguments to the functions in this section is that it corresponds to an assignment expression, with the destination array specified to the left of the source array. All of these functions return the address of the destination array.
Most of these functions do not work properly if the source and destination arrays overlap. For example, if the beginning of the destination array overlaps the end of the source array, the original contents of that part of the source array may get overwritten before it is copied. Even worse, in the case of the string functions, the null character marking the end of the string may be lost, and the copy function might get stuck in a loop trashing all the memory allocated to your program.
All functions that have problems copying between overlapping arrays are
explicitly identified in this manual. In addition to functions in this
section, there are a few others like sprintf (see section Formatted Output Functions) and scanf (see section Formatted Input Functions).
memcpy function copies size bytes from the object
beginning at from into the object beginning at to. The
behavior of this function is undefined if the two arrays to and
from overlap; use memmove instead if overlapping is possible.
The value returned by memcpy is the value of to.
Here is an example of how you might use memcpy to copy the
contents of an array:
struct foo *oldarray, *newarray; int arraysize; ... memcpy (new, old, arraysize * sizeof (struct foo));
memmove copies the size bytes at from into the
size bytes at to, even if those two blocks of space
overlap. In the case of overlap, memmove is careful to copy the
original values of the bytes in the block at from, including those
bytes which also belong to the block at to.
unsigned char) into each of the first size bytes of the
object beginning at block. It returns the value of block.
memcpy, this function has undefined results if the strings
overlap. The return value is the value of to.
strcpy but always copies exactly
size characters into to.
If the length of from is more than size, then strncpy
copies just the first size characters. Note that in this case
there is no null terminator written into to.
If the length of from is less than size, then strncpy
copies all of from, followed by enough null characters to add up
to size characters in all. This behavior is rarely useful, but it
is specified by the ISO C standard.
The behavior of strncpy is undefined if the strings overlap.
Using strncpy as opposed to strcpy is a way to avoid bugs
relating to writing past the end of the allocated space for to.
However, it can also make your program much slower in one common case:
copying a string which is probably small into a potentially large buffer.
In this case, size may be large, and when it is, strncpy will
waste a considerable amount of time copying null characters.
malloc; see
section Unconstrained Allocation. If malloc cannot allocate space
for the new string, strdup returns a null pointer. Otherwise it
returns a pointer to the new string.
strdup but always copies at most
size characters into the newly allocated string.
If the length of s is more than size, then strndup
copies just the first size characters and adds a closing null
terminator. Otherwise all characters are copied and the string is
terminated.
This function is different to strncpy in that it always
terminates the destination string.
strcpy, except that it returns a pointer to
the end of the string to (that is, the address of the terminating
null character) rather than the beginning.
For example, this program uses stpcpy to concatenate `foo'
and `bar' to produce `foobar', which it then prints.
#include <string.h>
#include <stdio.h>
int
main (void)
{
char buffer[10];
char *to = buffer;
to = stpcpy (to, "foo");
to = stpcpy (to, "bar");
puts (buffer);
return 0;
}
This function is not part of the ISO or POSIX standards, and is not customary on Unix systems, but we did not invent it either. Perhaps it comes from MS-DOG.
Its behavior is undefined if the strings overlap.
stpcpy but copies always exactly
size characters into to.
If the length of from is more then size, then stpncpy
copies just the first size characters and returns a pointer to the
character directly following the one which was copied last. Note that in
this case there is no null terminator written into to.
If the length of from is less than size, then stpncpy
copies all of from, followed by enough null characters to add up
to size characters in all. This behaviour is rarely useful, but it
is implemented to be useful in contexts where this behaviour of the
strncpy is used. stpncpy returns a pointer to the
first written null character.
This function is not part of ISO or POSIX but was found useful while developing GNU C Library itself.
Its behaviour is undefined if the strings overlap.
strdup but allocates the new string
using alloca instead of malloc
see section Automatic Storage with Variable Size. This means of course the returned
string has the same limitations as any block of memory allocated using
alloca.
For obvious reasons strdupa is implemented only as a macro. I.e.,
you cannot get the address of this function. Despite this limitations
it is a useful function. The following code shows a situation where
using malloc would be a lot more expensive.
#include <paths.h>
#include <string.h>
#include <stdio.h>
const char path[] = _PATH_STDPATH;
int
main (void)
{
char *wr_path = strdupa (path);
char *cp = strtok (wr_path, ":");
while (cp != NULL)
{
puts (cp);
cp = strtok (NULL, ":");
}
return 0;
}
Please note that calling strtok using path directly is
illegal.
This function is only available if GNU CC is used.
strndup but like strdupa it
allocates the new string using alloca
see section Automatic Storage with Variable Size. The same advantages and limitations
of strdupa are valid for strndupa, too.
This function is implemented only as a macro which means one cannot get the address of it.
strndupa is only available if GNU CC is used.
strcat function is similar to strcpy, except that the
characters from from are concatenated or appended to the end of
to, instead of overwriting it. That is, the first character from
from overwrites the null character marking the end of to.
An equivalent definition for strcat would be:
char *
strcat (char *to, const char *from)
{
strcpy (to + strlen (to), from);
return to;
}
This function has undefined results if the strings overlap.
strcat except that not more than size
characters from from are appended to the end of to. A
single null character is also always appended to to, so the total
allocated size of to must be at least size + 1 bytes
longer than its initial length.
The strncat function could be implemented like this:
char *
strncat (char *to, const char *from, size_t size)
{
strncpy (to + strlen (to), from, size);
return to;
}
The behavior of strncat is undefined if the strings overlap.
Here is an example showing the use of strncpy and strncat.
Notice how, in the call to strncat, the size parameter
is computed to avoid overflowing the character array buffer.
#include <string.h>
#include <stdio.h>
#define SIZE 10
static char buffer[SIZE];
main ()
{
strncpy (buffer, "hello", SIZE);
puts (buffer);
strncat (buffer, ", world", SIZE - strlen (buffer) - 1);
puts (buffer);
}
The output produced by this program looks like:
hello hello, wo
memmove, derived from
BSD. Note that it is not quite equivalent to memmove, because the
arguments are not in the same order.
memset, derived from
BSD. Note that it is not as general as memset, because the only
value it can store is zero.
You can use the functions in this section to perform comparisons on the contents of strings and arrays. As well as checking for equality, these functions can also be used as the ordering functions for sorting operations. See section Searching and Sorting, for an example of this.
Unlike most comparison operations in C, the string comparison functions return a nonzero value if the strings are not equivalent rather than if they are. The sign of the value indicates the relative ordering of the first characters in the strings that are not equivalent: a negative value indicates that the first string is "less" than the second, while a positive value indicates that the first string is "greater".
The most common use of these functions is to check only for equality. This is canonically done with an expression like `! strcmp (s1, s2)'.
All of these functions are declared in the header file `string.h'.
memcmp compares the size bytes of memory
beginning at a1 against the size bytes of memory beginning
at a2. The value returned has the same sign as the difference
between the first differing pair of bytes (interpreted as unsigned
char objects, then promoted to int).
If the contents of the two blocks are equal, memcmp returns
0.
On arbitrary arrays, the memcmp function is mostly useful for
testing equality. It usually isn't meaningful to do byte-wise ordering
comparisons on arrays of things other than bytes. For example, a
byte-wise comparison on the bytes that make up floating-point numbers
isn't likely to tell you anything about the relationship between the
values of the floating-point numbers.
You should also be careful about using memcmp to compare objects
that can contain "holes", such as the padding inserted into structure
objects to enforce alignment requirements, extra space at the end of
unions, and extra characters at the ends of strings whose length is less
than their allocated size. The contents of these "holes" are
indeterminate and may cause strange behavior when performing byte-wise
comparisons. For more predictable results, perform an explicit
component-wise comparison.
For example, given a structure type definition like:
struct foo
{
unsigned char tag;
union
{
double f;
long i;
char *p;
} value;
};
you are better off writing a specialized comparison function to compare
struct foo objects instead of comparing them with memcmp.
strcmp function compares the string s1 against
s2, returning a value that has the same sign as the difference
between the first differing pair of characters (interpreted as
unsigned char objects, then promoted to int).
If the two strings are equal, strcmp returns 0.
A consequence of the ordering used by strcmp is that if s1
is an initial substring of s2, then s1 is considered to be
"less than" s2.
strcmp, except that differences in case
are ignored.
strcasecmp is derived from BSD.
strncmp, except that differences in case
are ignored.
strncasecmp is a GNU extension.
strcmp, except that no more than
size characters are compared. In other words, if the two strings are
the same in their first size characters, the return value is zero.
Here are some examples showing the use of strcmp and strncmp.
These examples assume the use of the ASCII character set. (If some
other character set--say, EBCDIC--is used instead, then the glyphs
are associated with different numeric codes, and the return values
and ordering may differ.)
strcmp ("hello", "hello")
=> 0 /* These two strings are the same. */
strcmp ("hello", "Hello")
=> 32 /* Comparisons are case-sensitive. */
strcmp ("hello", "world")
=> -15 /* The character 'h' comes before 'w'. */
strcmp ("hello", "hello, world")
=> -44 /* Comparing a null character against a comma. */
strncmp ("hello", "hello, world", 5)
=> 0 /* The initial 5 characters are the same. */
strncmp ("hello, world", "hello, stupid world!!!", 5)
=> 0 /* The initial 5 characters are the same. */
memcmp, derived from BSD.
In some locales, the conventions for lexicographic ordering differ from the strict numeric ordering of character codes. For example, in Spanish most glyphs with diacritical marks such as accents are not considered distinct letters for the purposes of collation. On the other hand, the two-character sequence `ll' is treated as a single letter that is collated immediately after `l'.
You can use the functions strcoll and strxfrm (declared in
the header file `string.h') to compare strings using a collation
ordering appropriate for the current locale. The locale used by these
functions in particular can be specified by setting the locale for the
LC_COLLATE category; see section Locales and Internationalization.
In the standard C locale, the collation sequence for strcoll is
the same as that for strcmp.
Effectively, the way these functions work is by applying a mapping to transform the characters in a string to a byte sequence that represents the string's position in the collating sequence of the current locale. Comparing two such byte sequences in a simple fashion is equivalent to comparing the strings with the locale's collating sequence.
The function strcoll performs this translation implicitly, in
order to do one comparison. By contrast, strxfrm performs the
mapping explicitly. If you are making multiple comparisons using the
same string or set of strings, it is likely to be more efficient to use
strxfrm to transform all the strings just once, and subsequently
compare the transformed strings with strcmp.
strcoll function is similar to strcmp but uses the
collating sequence of the current locale for collation (the
LC_COLLATE locale).
Here is an example of sorting an array of strings, using strcoll
to compare them. The actual sort algorithm is not written here; it
comes from qsort (see section Array Sort Function). The job of the
code shown here is to say how to compare the strings while sorting them.
(Later on in this section, we will show a way to do this more
efficiently using strxfrm.)
/* This is the comparison function used withqsort. */ int compare_elements (char **p1, char **p2) { return strcoll (*p1, *p2); } /* This is the entry point---the function to sort strings using the locale's collating sequence. */ void sort_strings (char **array, int nstrings) { /* Sorttemp_arrayby comparing the strings. */ qsort (array, sizeof (char *), nstrings, compare_elements); }
strxfrm transforms string using the collation
transformation determined by the locale currently selected for
collation, and stores the transformed string in the array to. Up
to size characters (including a terminating null character) are
stored.
The behavior is undefined if the strings to and from overlap; see section Copying and Concatenation.
The return value is the length of the entire transformed string. This
value is not affected by the value of size, but if it is greater
or equal than size, it means that the transformed string did not
entirely fit in the array to. In this case, only as much of the
string as actually fits was stored. To get the whole transformed
string, call strxfrm again with a bigger output array.
The transformed string may be longer than the original string, and it may also be shorter.
If size is zero, no characters are stored in to. In this
case, strxfrm simply returns the number of characters that would
be the length of the transformed string. This is useful for determining
what size string to allocate. It does not matter what to is if
size is zero; to may even be a null pointer.
Here is an example of how you can use strxfrm when
you plan to do many comparisons. It does the same thing as the previous
example, but much faster, because it has to transform each string only
once, no matter how many times it is compared with other strings. Even
the time needed to allocate and free storage is much less than the time
we save, when there are many strings.
struct sorter { char *input; char *transformed; };
/* This is the comparison function used with qsort
to sort an array of struct sorter. */
int
compare_elements (struct sorter *p1, struct sorter *p2)
{
return strcmp (p1->transformed, p2->transformed);
}
/* This is the entry point---the function to sort
strings using the locale's collating sequence. */
void
sort_strings_fast (char **array, int nstrings)
{
struct sorter temp_array[nstrings];
int i;
/* Set up temp_array. Each element contains
one input string and its transformed string. */
for (i = 0; i < nstrings; i++)
{
size_t length = strlen (array[i]) * 2;
char *transformed;
size_t transformed_lenght;
temp_array[i].input = array[i];
/* First try a buffer perhaps big enough. */
transformed = (char *) xmalloc (length);
/* Transform array[i]. */
transformed_length = strxfrm (transformed, array[i], length);
/* If the buffer was not large enough, resize it
and try again. */
if (transformed_length >= length)
{
/* Allocate the needed space. +1 for terminating
NUL character. */
transformed = (char *) xrealloc (transformed,
transformed_length + 1);
/* The return value is not interesting because we know
how long the transformed string is. */
(void) strxfrm (transformed, array[i], transformed_length + 1);
}
temp_array[i].transformed = transformed;
}
/* Sort temp_array by comparing transformed strings. */
qsort (temp_array, sizeof (struct sorter),
nstrings, compare_elements);
/* Put the elements back in the permanent array
in their sorted order. */
for (i = 0; i < nstrings; i++)
array[i] = temp_array[i].input;
/* Free the strings we allocated. */
for (i = 0; i < nstrings; i++)
free (temp_array[i].transformed);
}
Compatibility Note: The string collation functions are a new feature of ISO C. Older C dialects have no equivalent feature.
This section describes library functions which perform various kinds of searching operations on strings and arrays. These functions are declared in the header file `string.h'.
unsigned char) in the initial size bytes of the
object beginning at block. The return value is a pointer to the
located byte, or a null pointer if no match was found.
strchr function finds the first occurrence of the character
c (converted to a char) in the null-terminated string
beginning at string. The return value is a pointer to the located
character, or a null pointer if no match was found.
For example,
strchr ("hello, world", 'l')
=> "llo, world"
strchr ("hello, world", '?')
=> NULL
The terminating null character is considered to be part of the string, so you can use this function get a pointer to the end of a string by specifying a null character as the value of the c argument.
index is another name for strchr; they are exactly the same.
strrchr is like strchr, except that it searches
backwards from the end of the string string (instead of forwards
from the front).
For example,
strrchr ("hello, world", 'l')
=> "ld"
rindex is another name for strrchr; they are exactly the same.
strchr, except that it searches haystack for a
substring needle rather than just a single character. It
returns a pointer into the string haystack that is the first
character of the substring, or a null pointer if no match was found. If
needle is an empty string, the function returns haystack.
For example,
strstr ("hello, world", "l")
=> "llo, world"
strstr ("hello, world", "wo")
=> "world"
strstr, but needle and haystack are byte
arrays rather than null-terminated strings. needle-len is the
length of needle and haystack-len is the length of
haystack.
This function is a GNU extension.
strspn ("string span") function returns the length of the
initial substring of string that consists entirely of characters that
are members of the set specified by the string skipset. The order
of the characters in skipset is not important.
For example,
strspn ("hello, world", "abcdefghijklmnopqrstuvwxyz")
=> 5
strcspn ("string complement span") function returns the length
of the initial substring of string that consists entirely of characters
that are not members of the set specified by the string stopset.
(In other words, it returns the offset of the first character in string
that is a member of the set stopset.)
For example,
strcspn ("hello, world", " \t\n,.;!?")
=> 5
strpbrk ("string pointer break") function is related to
strcspn, except that it returns a pointer to the first character
in string that is a member of the set stopset instead of the
length of the initial substring. It returns a null pointer if no such
character from stopset is found.
For example,
strpbrk ("hello, world", " \t\n,.;!?")
=> ", world"
It's fairly common for programs to have a need to do some simple kinds
of lexical analysis and parsing, such as splitting a command string up
into tokens. You can do this with the strtok function, declared
in the header file `string.h'.
strtok.
The string to be split up is passed as the newstring argument on
the first call only. The strtok function uses this to set up
some internal state information. Subsequent calls to get additional
tokens from the same string are indicated by passing a null pointer as
the newstring argument. Calling strtok with another
non-null newstring argument reinitializes the state information.
It is guaranteed that no other library function ever calls strtok
behind your back (which would mess up this internal state information).
The delimiters argument is a string that specifies a set of delimiters that may surround the token being extracted. All the initial characters that are members of this set are discarded. The first character that is not a member of this set of delimiters marks the beginning of the next token. The end of the token is found by looking for the next character that is a member of the delimiter set. This character in the original string newstring is overwritten by a null character, and the pointer to the beginning of the token in newstring is returned.
On the next call to strtok, the searching begins at the next
character beyond the one that marked the end of the previous token.
Note that the set of delimiters delimiters do not have to be the
same on every call in a series of calls to strtok.
If the end of the string newstring is reached, or if the remainder of
string consists only of delimiter characters, strtok returns
a null pointer.
Warning: Since strtok alters the string it is parsing,
you always copy the string to a temporary buffer before parsing it with
strtok. If you allow strtok to modify a string that came
from another part of your program, you are asking for trouble; that
string may be part of a data structure that could be used for other
purposes during the parsing, when alteration by strtok makes the
data structure temporarily inaccurate.
The string that you are operating on might even be a constant. Then
when strtok tries to modify it, your program will get a fatal
signal for writing in read-only memory. See section Program Error Signals.
This is a special case of a general principle: if a part of a program does not have as its purpose the modification of a certain data structure, then it is error-prone to modify the data structure temporarily.
The function strtok is not reentrant. See section Signal Handling and Nonreentrant Functions, for
a discussion of where and why reentrancy is important.
Here is a simple example showing the use of strtok.
#include <string.h> #include <stddef.h> ... char string[] = "words separated by spaces -- and, punctuation!"; const char delimiters[] = " .,;:!-"; char *token; ... token = strtok (string, delimiters); /* token => "words" */ token = strtok (NULL, delimiters); /* token => "separated" */ token = strtok (NULL, delimiters); /* token => "by" */ token = strtok (NULL, delimiters); /* token => "spaces" */ token = strtok (NULL, delimiters); /* token => "and" */ token = strtok (NULL, delimiters); /* token => "punctuation" */ token = strtok (NULL, delimiters); /* token => NULL */
The GNU C library contains two more functions for tokenizing a string which overcome the limitation of non-reentrancy.
strtok this function splits the string into several
tokens which can be accessed be successive calls to strtok_r.
The difference is that the information about the next token is not set
up in some internal state information. Instead the caller has to
provide another argument save_ptr which is a pointer to a string
pointer. Calling strtok_r with a null pointer for
newstring and leaving save_ptr between the calls unchanged
does the job without limiting reentrancy.
This function was proposed for POSIX.1b and can be found on many systems which support multi-threading.
strsep move the pointer along the tokens
separated by delimiter, returning the address of the next token
and updating string_ptr to point to the beginning of the next
token.
This function was introduced in 4.3BSD and therefore is widely available.
Here is how the above example looks like when strsep is used.
#include <string.h> #include <stddef.h> ... char string[] = "words separated by spaces -- and, punctuation!"; const char delimiters[] = " .,;:!-"; char *running; char *token; ... running = string; token = strsep (&running, delimiters); /* token => "words" */ token = strsep (&running, delimiters); /* token => "separated" */ token = strsep (&running, delimiters); /* token => "by" */ token = strsep (&running, delimiters); /* token => "spaces" */ token = strsep (&running, delimiters); /* token => "and" */ token = strsep (&running, delimiters); /* token => "punctuation" */ token = strsep (&running, delimiters); /* token => NULL */
Most programs need to do either input (reading data) or output (writing data), or most frequently both, in order to do anything useful. The GNU C library provides such a large selection of input and output functions that the hardest part is often deciding which function is most appropriate!
This chapter introduces concepts and terminology relating to input and output. Other chapters relating to the GNU I/O facilities are:
Before you can read or write the contents of a file, you must establish a connection or communications channel to the file. This process is called opening the file. You can open a file for reading, writing, or both.
The connection to an open file is represented either as a stream or as a file descriptor. You pass this as an argument to the functions that do the actual read or write operations, to tell them which file to operate on. Certain functions expect streams, and others are designed to operate on file descriptors.
When you have finished reading to or writing from the file, you can terminate the connection by closing the file. Once you have closed a stream or file descriptor, you cannot do any more input or output operations on it.
When you want to do input or output to a file, you have a choice of two
basic mechanisms for representing the connection between your program
and the file: file descriptors and streams. File descriptors are
represented as objects of type int, while streams are represented
as FILE * objects.
File descriptors provide a primitive, low-level interface to input and output operations. Both file descriptors and streams can represent a connection to a device (such as a terminal), or a pipe or socket for communicating with another process, as well as a normal file. But, if you want to do control operations that are specific to a particular kind of device, you must use a file descriptor; there are no facilities to use streams in this way. You must also use file descriptors if your program needs to do input or output in special modes, such as nonblocking (or polled) input (see section File Status Flags).
Streams provide a higher-level interface, layered on top of the primitive file descriptor facilities. The stream interface treats all kinds of files pretty much alike--the sole exception being the three styles of buffering that you can choose (see section Stream Buffering).
The main advantage of using the stream interface is that the set of
functions for performing actual input and output operations (as opposed
to control operations) on streams is much richer and more powerful than
the corresponding facilities for file descriptors. The file descriptor
interface provides only simple functions for transferring blocks of
characters, but the stream interface also provides powerful formatted
input and output functions (printf and scanf) as well as
functions for character- and line-oriented input and output.
Since streams are implemented in terms of file descriptors, you can extract the file descriptor from a stream and perform low-level operations directly on the file descriptor. You can also initially open a connection as a file descriptor and then make a stream associated with that file descriptor.
In general, you should stick with using streams rather than file descriptors, unless there is some specific operation you want to do that can only be done on a file descriptor. If you are a beginning programmer and aren't sure what functions to use, we suggest that you concentrate on the formatted input functions (see section Formatted Input) and formatted output functions (see section Formatted Output).
If you are concerned about portability of your programs to systems other than GNU, you should also be aware that file descriptors are not as portable as streams. You can expect any system running ISO C to support streams, but non-GNU systems may not support file descriptors at all, or may only implement a subset of the GNU functions that operate on file descriptors. Most of the file descriptor functions in the GNU library are included in the POSIX.1 standard, however.
One of the attributes of an open file is its file position that keeps track of where in the file the next character is to be read or written. In the GNU system, and all POSIX.1 systems, the file position is simply an integer representing the number of bytes from the beginning of the file.
The file position is normally set to the beginning of the file when it is opened, and each time a character is read or written, the file position is incremented. In other words, access to the file is normally sequential.
Ordinary files permit read or write operations at any position within
the file. Some other kinds of files may also permit this. Files which
do permit this are sometimes referred to as random-access files.
You can change the file position using the fseek function on a
stream (see section File Positioning) or the lseek function on a file
descriptor (see section Input and Output Primitives). If you try to change the file
position on a file that doesn't support random access, you get the
ESPIPE error.
Streams and descriptors that are opened for append access are treated specially for output: output to such files is always appended sequentially to the end of the file, regardless of the file position. However, the file position is still used to control where in the file reading is done.
If you think about it, you'll realize that several programs can read a given file at the same time. In order for each program to be able to read the file at its own pace, each program must have its own file pointer, which is not affected by anything the other programs do.
In fact, each opening of a file creates a separate file position. Thus, if you open a file twice even in the same program, you get two streams or descriptors with independent file positions.
By contrast, if you open a descriptor and then duplicate it to get another descriptor, these two descriptors share the same file position: changing the file position of one descriptor will affect the other.
In order to open a connection to a file, or to perform other operations such as deleting a file, you need some way to refer to the file. Nearly all files have names that are strings--even files which are actually devices such as tape drives or terminals. These strings are called file names. You specify the file name to say which file you want to open or operate on.
This section describes the conventions for file names and how the operating system works with them.
In order to understand the syntax of file names, you need to understand how the file system is organized into a hierarchy of directories.
A directory is a file that contains information to associate other files with names; these associations are called links or directory entries. Sometimes, people speak of "files in a directory", but in reality, a directory only contains pointers to files, not the files themselves.
The name of a file contained in a directory entry is called a file name component. In general, a file name consists of a sequence of one or more such components, separated by the slash character (`/'). A file name which is just one component names a file with respect to its directory. A file name with multiple components names a directory, and then a file in that directory, and so on.
Some other documents, such as the POSIX standard, use the term
pathname for what we call a file name, and either filename
or pathname component for what this manual calls a file name
component. We don't use this terminology because a "path" is
something completely different (a list of directories to search), and we
think that "pathname" used for something else will confuse users. We
always use "file name" and "file name component" (or sometimes just
"component", where the context is obvious) in GNU documentation. Some
macros use the POSIX terminology in their names, such as
PATH_MAX. These macros are defined by the POSIX standard, so we
cannot change their names.
You can find more detailed information about operations on directories in section File System Interface.
A file name consists of file name components separated by slash (`/') characters. On the systems that the GNU C library supports, multiple successive `/' characters are equivalent to a single `/' character.
The process of determining what file a file name refers to is called file name resolution. This is performed by examining the components that make up a file name in left-to-right order, and locating each successive component in the directory named by the previous component. Of course, each of the files that are referenced as directories must actually exist, be directories instead of regular files, and have the appropriate permissions to be accessible by the process; otherwise the file name resolution fails.
If a file name begins with a `/', the first component in the file name is located in the root directory of the process (usually all processes on the system have the same root directory). Such a file name is called an absolute file name.
Otherwise, the first component in the file name is located in the current working directory (see section Working Directory). This kind of file name is called a relative file name.
The file name components `.' ("dot") and `..' ("dot-dot") have special meanings. Every directory has entries for these file name components. The file name component `.' refers to the directory itself, while the file name component `..' refers to its parent directory (the directory that contains the link for the directory in question). As a special case, `..' in the root directory refers to the root directory itself, since it has no parent; thus `/..' is the same as `/'.
Here are some examples of file names:
A file name that names a directory may optionally end in a `/'. You can specify a file name of `/' to refer to the root directory, but the empty string is not a meaningful file name. If you want to refer to the current working directory, use a file name of `.' or `./'.
Unlike some other operating systems, the GNU system doesn't have any built-in support for file types (or extensions) or file versions as part of its file name syntax. Many programs and utilities use conventions for file names--for example, files containing C source code usually have names suffixed with `.c'---but there is nothing in the file system itself that enforces this kind of convention.
Functions that accept file name arguments usually detect these
errno error conditions relating to the file name syntax or
trouble finding the named file. These errors are referred to throughout
this manual as the usual file name errors.
EACCES
ENAMETOOLONG
PATH_MAX, or when an individual file name component
has a length greater than NAME_MAX. See section Limits on File System Capacity.
In the GNU system, there is no imposed limit on overall file name
length, but some file systems may place limits on the length of a
component.
ENOENT
ENOTDIR
ELOOP
The rules for the syntax of file names discussed in section File Names, are the rules normally used by the GNU system and by other POSIX systems. However, other operating systems may use other conventions.
There are two reasons why it can be important for you to be aware of file name portability issues:
The ISO C standard says very little about file name syntax, only that file names are strings. In addition to varying restrictions on the length of file names and what characters can validly appear in a file name, different operating systems use different conventions and syntax for concepts such as structured directories and file types or extensions. Some concepts such as file versions might be supported in some operating systems and not by others.
The POSIX.1 standard allows implementations to put additional restrictions on file name syntax, concerning what characters are permitted in file names and on the length of file name and file name component strings. However, in the GNU system, you do not need to worry about these restrictions; any character except the null character is permitted in a file name string, and there are no limits on the length of file name strings.
This chapter describes the functions for creating streams and performing input and output operations on them. As discussed in section Input/Output Overview, a stream is a fairly abstract, high-level concept representing a communications channel to a file, device, or process.
For historical reasons, the type of the C data structure that represents
a stream is called FILE rather than "stream". Since most of
the library functions deal with objects of type FILE *, sometimes
the term file pointer is also used to mean "stream". This leads
to unfortunate confusion over terminology in many books on C. This
manual, however, is careful to use the terms "file" and "stream"
only in the technical sense.
The FILE type is declared in the header file `stdio.h'.
FILE
object holds all of the internal state information about the connection
to the associated file, including such things as the file position
indicator and buffering information. Each stream also has error and
end-of-file status indicators that can be tested with the ferror
and feof functions; see section End-Of-File and Errors.
FILE objects are allocated and managed internally by the
input/output library functions. Don't try to create your own objects of
type FILE; let the library do it. Your programs should
deal only with pointers to these objects (that is, FILE * values)
rather than the objects themselves.
When the main function of your program is invoked, it already has
three predefined streams open and available for use. These represent
the "standard" input and output channels that have been established
for the process.
These streams are declared in the header file `stdio.h'.
In the GNU system, you can specify what files or processes correspond to these streams using the pipe and redirection facilities provided by the shell. (The primitives shells use to implement these facilities are described in section File System Interface.) Most other operating systems provide similar mechanisms, but the details of how to use them can vary.
In the GNU C library, stdin, stdout, and stderr are
normal variables which you can set just like any others. For example, to redirect
the standard output to a file, you could do:
fclose (stdout);
stdout = fopen ("standard-output-file", "w");
Note however, that in other systems stdin, stdout, and
stderr are macros that you cannot assign to in the normal way.
But you can use freopen to get the effect of closing one and
reopening it. See section Opening Streams.
Opening a file with the fopen function creates a new stream and
establishes a connection between the stream and a file. This may
involve creating a new file.
Everything described in this section is declared in the header file `stdio.h'.
fopen function opens a stream for I/O to the file
filename, and returns a pointer to the stream.
The opentype argument is a string that controls how the file is opened and specifies attributes of the resulting stream. It must begin with one of the following sequences of characters:
As you can see, `+' requests a stream that can do both input and
output. The ISO standard says that when using such a stream, you must
call fflush (see section Stream Buffering) or a file positioning
function such as fseek (see section File Positioning) when switching
from reading to writing or vice versa. Otherwise, internal buffers
might not be emptied properly. The GNU C library does not have this
limitation; you can do arbitrary reading and writing operations on a
stream in whatever order.
Additional characters may appear after these to specify flags for the call. Always put the mode (`r', `w+', etc.) first; that is the only part you are guaranteed will be understood by all systems.
The GNU C library defines one additional character for use in
opentype: the character `x' insists on creating a new
file--if a file filename already exists, fopen fails
rather than opening it. If you use `x' you can are guaranteed that
you will not clobber an existing file. This is equivalent to the
O_EXCL option to the open function (see section Opening and Closing Files).
The character `b' in opentype has a standard meaning; it requests a binary stream rather than a text stream. But this makes no difference in POSIX systems (including the GNU system). If both `+' and `b' are specified, they can appear in either order. See section Text and Binary Streams.
Any other characters in opentype are simply ignored. They may be meaningful in other systems.
If the open fails, fopen returns a null pointer.
You can have multiple streams (or file descriptors) pointing to the same file open at the same time. If you do only input, this works straightforwardly, but you must be careful if any output streams are included. See section Dangers of Mixing Streams and Descriptors. This is equally true whether the streams are in one program (not usual) or in several programs (which can easily happen). It may be advantageous to use the file locking facilities to avoid simultaneous access. See section File Locks.
stdin, stdout, and stderr. In POSIX.1 systems this
value is determined by the OPEN_MAX parameter; see section General Capacity Limits. In BSD and GNU, it is controlled by the RLIMIT_NOFILE
resource limit; see section Limiting Resource Usage.
fclose and fopen.
It first closes the stream referred to by stream, ignoring any
errors that are detected in the process. (Because errors are ignored,
you should not use freopen on an output stream if you have
actually done any output using the stream.) Then the file named by
filename is opened with mode opentype as for fopen,
and associated with the same stream object stream.
If the operation fails, a null pointer is returned; otherwise,
freopen returns stream.
freopen has traditionally been used to connect a standard stream
such as stdin with a file of your own choice. This is useful in
programs in which use of a standard stream for certain purposes is
hard-coded. In the GNU C library, you can simply close the standard
streams and open new ones with fopen. But other systems lack
this ability, so using freopen is more portable.
When a stream is closed with fclose, the connection between the
stream and the file is cancelled. After you have closed a stream, you
cannot perform any additional operations on it.
fclose function returns
a value of 0 if the file was closed successfully, and EOF
if an error was detected.
It is important to check for errors when you call fclose to close
an output stream, because real, everyday errors can be detected at this
time. For example, when fclose writes the remaining buffered
output, it might get an error because the disk is full. Even if you
know the buffer is empty, errors can still occur when closing a file if
you are using NFS.
The function fclose is declared in `stdio.h'.
To close all streams currently available the GNU C Library provides another function.
fcloseall
function returns a value of 0 if all the files were closed
successfully, and EOF if an error was detected.
This function should be used in only in special situation, e.g., when an error occurred and the program must be aborted. Normally each single stream should be closed separately so that problems with one stream can be identifier. It is also problematic since the standard streams (see section Standard Streams) will also be closed.
The function fcloseall is declared in `stdio.h'.
If the main function to your program returns, or if you call the
exit function (see section Normal Termination), all open streams are
automatically closed properly. If your program terminates in any other
manner, such as by calling the abort function (see section Aborting a Program) or from a fatal signal (see section Signal Handling), open streams
might not be closed properly. Buffered output might not be flushed and
files may be incomplete. For more information on buffering of streams,
see section Stream Buffering.
This section describes functions for performing character- and line-oriented output.
These functions are declared in the header file `stdio.h'.
fputc function converts the character c to type
unsigned char, and writes it to the stream stream.
EOF is returned if a write error occurs; otherwise the
character c is returned.
fputc, except that most systems implement it as
a macro, making it faster. One consequence is that it may evaluate the
stream argument more than once, which is an exception to the
general rule for macros. putc is usually the best function to
use for writing a single character.
putchar function is equivalent to putc with
stdout as the value of the stream argument.
fputs writes the string s to the stream
stream. The terminating null character is not written.
This function does not add a newline character, either.
It outputs only the characters in the string.
This function returns EOF if a write error occurs, and otherwise
a non-negative value.
For example:
fputs ("Are ", stdout);
fputs ("you ", stdout);
fputs ("hungry?\n", stdout);
outputs the text `Are you hungry?' followed by a newline.
puts function writes the string s to the stream
stdout followed by a newline. The terminating null character of
the string is not written. (Note that fputs does not
write a newline as this function does.)
puts is the most convenient function for printing simple
messages. For example:
puts ("This is a message.");
int) to
stream. It is provided for compatibility with SVID, but we
recommend you use fwrite instead (see section Block Input/Output).
This section describes functions for performing character-oriented input. These functions are declared in the header file `stdio.h'.
These functions return an int value that is either a character of
input, or the special value EOF (usually -1). It is important to
store the result of these functions in a variable of type int
instead of char, even when you plan to use it only as a
character. Storing EOF in a char variable truncates its
value to the size of a character, so that it is no longer
distinguishable from the valid character `(char) -1'. So always
use an int for the result of getc and friends, and check
for EOF after the call; once you've verified that the result is
not EOF, you can be sure that it will fit in a `char'
variable without loss of information.
unsigned char from
the stream stream and returns its value, converted to an
int. If an end-of-file condition or read error occurs,
EOF is returned instead.
fgetc, except that it is permissible (and
typical) for it to be implemented as a macro that evaluates the
stream argument more than once. getc is often highly
optimized, so it is usually the best function to use to read a single
character.
getchar function is equivalent to getc with stdin
as the value of the stream argument.
Here is an example of a function that does input using fgetc. It
would work just as well using getc instead, or using
getchar () instead of fgetc (stdin).
int
y_or_n_p (const char *question)
{
fputs (question, stdout);
while (1)
{
int c, answer;
/* Write a space to separate answer from question. */
fputc (' ', stdout);
/* Read the first character of the line.
This should be the answer character, but might not be. */
c = tolower (fgetc (stdin));
answer = c;
/* Discard rest of input line. */
while (c != '\n' && c != EOF)
c = fgetc (stdin);
/* Obey the answer if it was valid. */
if (answer == 'y')
return 1;
if (answer == 'n')
return 0;
/* Answer was invalid: ask for valid answer. */
fputs ("Please answer y or n:", stdout);
}
}
int) from stream.
It's provided for compatibility with SVID. We recommend you use
fread instead (see section Block Input/Output). Unlike getc,
any int value could be a valid result. getw returns
EOF when it encounters end-of-file or an error, but there is no
way to distinguish this from an input word with value -1.
Since many programs interpret input on the basis of lines, it's convenient to have functions to read a line of text from a stream.
Standard C has functions to do this, but they aren't very safe: null
characters and even (for gets) long lines can confuse them. So
the GNU library provides the nonstandard getline function that
makes it easy to read lines reliably.
Another GNU extension, getdelim, generalizes getline. It
reads a delimited record, defined as everything through the next
occurrence of a specified delimiter character.
All these functions are declared in `stdio.h'.
*lineptr.
Before calling getline, you should place in *lineptr
the address of a buffer *n bytes long, allocated with
malloc. If this buffer is long enough to hold the line,
getline stores the line in this buffer. Otherwise,
getline makes the buffer bigger using realloc, storing the
new buffer address back in *lineptr and the increased size
back in *n.
See section Unconstrained Allocation.
If you set *lineptr to a null pointer, and *n
to zero, before the call, then getline allocates the initial
buffer for you by calling malloc.
In either case, when getline returns, *lineptr is
a char * which points to the text of the line.
When getline is successful, it returns the number of characters
read (including the newline, but not including the terminating null).
This value enables you to distinguish null characters that are part of
the line from the null character inserted as a terminator.
This function is a GNU extension, but it is the recommended way to read lines from a stream. The alternative standard functions are unreliable.
If an error occurs or end of file is reached, getline returns
-1.
getline except that the character which
tells it to stop reading is not necessarily newline. The argument
delimiter specifies the delimiter character; getdelim keeps
reading until it sees that character (or end of file).
The text is stored in lineptr, including the delimiter character
and a terminating null. Like getline, getdelim makes
lineptr bigger if it isn't big enough.
getline is in fact implemented in terms of getdelim, just
like this:
ssize_t
getline (char **lineptr, size_t *n, FILE *stream)
{
return getdelim (lineptr, n, '\n', stream);
}
fgets function reads characters from the stream stream
up to and including a newline character and stores them in the string
s, adding a null character to mark the end of the string. You
must supply count characters worth of space in s, but the
number of characters read is at most count - 1. The extra
character space is used to hold the null character at the end of the
string.
If the system is already at end of file when you call fgets, then
the contents of the array s are unchanged and a null pointer is
returned. A null pointer is also returned if a read error occurs.
Otherwise, the return value is the pointer s.
Warning: If the input data has a null character, you can't tell.
So don't use fgets unless you know the data cannot contain a null.
Don't use it to read files edited by the user because, if the user inserts
a null character, you should either handle it properly or print a clear
error message. We recommend using getline instead of fgets.
gets reads characters from the stream stdin
up to the next newline character, and stores them in the string s.
The newline character is discarded (note that this differs from the
behavior of fgets, which copies the newline character into the
string). If gets encounters a read error or end-of-file, it
returns a null pointer; otherwise it returns s.
Warning: The gets function is very dangerous
because it provides no protection against overflowing the string
s. The GNU library includes it for compatibility only. You
should always use fgets or getline instead. To
remind you of this, the linker (if using GNU ld) will issue a
warning whenever you use gets.
In parser programs it is often useful to examine the next character in the input stream without removing it from the stream. This is called "peeking ahead" at the input because your program gets a glimpse of the input it will read next.
Using stream I/O, you can peek ahead at input by first reading it and
then unreading it (also called pushing it back on the stream).
Unreading a character makes it available to be input again from the stream,
by the next call to fgetc or other input function on that stream.
Here is a pictorial explanation of unreading. Suppose you have a stream reading a file that contains just six characters, the letters `foobar'. Suppose you have read three characters so far. The situation looks like this:
f o o b a r
^
so the next input character will be `b'.
If instead of reading `b' you unread the letter `o', you get a situation like this:
f o o b a r
|
o--
^
so that the next input characters will be `o' and `b'.
If you unread `9' instead of `o', you get this situation:
f o o b a r
|
9--
^
so that the next input characters will be `9' and `b'.
ungetc To Do Unreading
The function to unread a character is called ungetc, because it
reverses the action of getc.
ungetc function pushes back the character c onto the
input stream stream. So the next input from stream will
read c before anything else.
If c is EOF, ungetc does nothing and just returns
EOF. This lets you call ungetc with the return value of
getc without needing to check for an error from getc.
The character that you push back doesn't have to be the same as the last
character that was actually read from the stream. In fact, it isn't
necessary to actually read any characters from the stream before
unreading them with ungetc! But that is a strange way to write
a program; usually ungetc is used only to unread a character
that was just read from the same stream.
The GNU C library only supports one character of pushback--in other
words, it does not work to call ungetc twice without doing input
in between. Other systems might let you push back multiple characters;
then reading from the stream retrieves the characters in the reverse
order that they were pushed.
Pushing back characters doesn't alter the file; only the internal
buffering for the stream is affected. If a file positioning function
(such as fseek or rewind; see section File Positioning) is
called, any pending pushed-back characters are discarded.
Unreading a character on a stream that is at end of file clears the end-of-file indicator for the stream, because it makes the character of input available. After you read that character, trying to read again will encounter end of file.
Here is an example showing the use of getc and ungetc to
skip over whitespace characters. When this function reaches a
non-whitespace character, it unreads that character to be seen again on
the next read operation on the stream.
#include <stdio.h>
#include <ctype.h>
void
skip_whitespace (FILE *stream)
{
int c;
do
/* No need to check for EOF because it is not
isspace, and ungetc ignores EOF. */
c = getc (stream);
while (isspace (c));
ungetc (c, stream);
}
This section describes how to do input and output operations on blocks of data. You can use these functions to read and write binary data, as well as to read and write text in fixed-size blocks instead of by characters or lines.
Binary files are typically used to read and write blocks of data in the same format as is used to represent the data in a running program. In other words, arbitrary blocks of memory--not just character or string objects--can be written to a binary file, and meaningfully read in again by the same program.
Storing data in binary form is often considerably more efficient than using the formatted I/O functions. Also, for floating-point numbers, the binary form avoids possible loss of precision in the conversion process. On the other hand, binary files can't be examined or modified easily using many standard file utilities (such as text editors), and are not portable between different implementations of the language, or different kinds of computers.
These functions are declared in `stdio.h'.
If fread encounters end of file in the middle of an object, it
returns the number of complete objects read, and discards the partial
object. Therefore, the stream remains at the actual end of the file.
The functions described in this section (printf and related
functions) provide a convenient way to perform formatted output. You
call printf with a format string or template string
that specifies how to format the values of the remaining arguments.
Unless your program is a filter that specifically performs line- or
character-oriented processing, using printf or one of the other
related functions described in this section is usually the easiest and
most concise way to perform output. These functions are especially
useful for printing error messages, tables of data, and the like.
The printf function can be used to print any number of arguments.
The template string argument you supply in a call provides
information not only about the number of additional arguments, but also
about their types and what style should be used for printing them.
Ordinary characters in the template string are simply written to the output stream as-is, while conversion specifications introduced by a `%' character in the template cause subsequent arguments to be formatted and written to the output stream. For example,
int pct = 37;
char filename[] = "foo.txt";
printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n",
filename, pct);
produces output like
Processing of `foo.txt' is 37% finished. Please be patient.
This example shows the use of the `%d' conversion to specify that
an int argument should be printed in decimal notation, the
`%s' conversion to specify printing of a string argument, and
the `%%' conversion to print a literal `%' character.
There are also conversions for printing an integer argument as an unsigned value in octal, decimal, or hexadecimal radix (`%o', `%u', or `%x', respectively); or as a character value (`%c').
Floating-point numbers can be printed in normal, fixed-point notation using the `%f' conversion or in exponential notation using the `%e' conversion. The `%g' conversion uses either `%e' or `%f' format, depending on what is more appropriate for the magnitude of the particular number.
You can control formatting more precisely by writing modifiers between the `%' and the character that indicates which conversion to apply. These slightly alter the ordinary behavior of the conversion. For example, most conversion specifications permit you to specify a minimum field width and a flag indicating whether you want the result left- or right-justified within the field.
The specific flags and modifiers that are permitted and their interpretation vary depending on the particular conversion. They're all described in more detail in the following sections. Don't worry if this all seems excessively complicated at first; you can almost always get reasonable free-format output without using any of the modifiers at all. The modifiers are mostly used to make the output look "prettier" in tables.
This section provides details about the precise syntax of conversion
specifications that can appear in a printf template
string.
Characters in the template string that are not part of a conversion specification are printed as-is to the output stream. Multibyte character sequences (see section Extended Characters) are permitted in a template string.
The conversion specifications in a printf template string have
the general form:
% flags width [ . precision ] type conversion
For example, in the conversion specifier `%-10.8ld', the `-'
is a flag, `10' specifies the field width, the precision is
`8', the letter `l' is a type modifier, and `d' specifies
the conversion style. (This particular type specifier says to
print a long int argument in decimal notation, with a minimum of
8 digits left-justified in a field at least 10 characters wide.)
In more detail, output conversion specifications consist of an initial `%' character followed in sequence by:
int.
If the value is negative, this means to set the `-' flag (see
below) and to use the absolute value as the field width.
int, and is ignored
if it is negative. If you specify `*' for both the field width and
precision, the field width argument precedes the precision argument.
Other C library versions may not recognize this syntax.
int,
but you can specify `h', `l', or `L' for other integer
types.)
The exact options that are permitted and how they are interpreted vary between the different conversion specifiers. See the descriptions of the individual conversions for information about the particular options that they use.
With the `-Wformat' option, the GNU C compiler checks calls to
printf and related functions. It examines the format string and
verifies that the correct number and types of arguments are supplied.
There is also a GNU C syntax to tell the compiler that a function you
write uses a printf-style format string.
See section `Declaring Attributes of Functions' in Using GNU CC, for more information.
Here is a table summarizing what all the different conversions do:
scanf for input
(see section Table of Input Conversions).
errno.
(This is a GNU extension.)
See section Other Output Conversions.
If the syntax of a conversion specification is invalid, unpredictable things will happen, so don't do this. If there aren't enough function arguments provided to supply values for all the conversion specifications in the template string, or if the arguments are not of the correct types, the results are unpredictable. If you supply more arguments than conversion specifications, the extra argument values are simply ignored; this is sometimes useful.
This section describes the options for the `%d', `%i', `%o', `%u', `%x', and `%X' conversion specifications. These conversions print integers in various formats.
The `%d' and `%i' conversion specifications both print an
int argument as a signed decimal number; while `%o',
`%u', and `%x' print the argument as an unsigned octal,
decimal, or hexadecimal number (respectively). The `%X' conversion
specification is just like `%x' except that it uses the characters
`ABCDEF' as digits instead of `abcdef'.
The following flags are meaningful:
strtoul function (see section Parsing of Integers) and scanf with the `%i' conversion
(see section Numeric Input Conversions).
LC_NUMERIC category; see section Generic Numeric Formatting Parameters. This flag is a
GNU extension.
If a precision is supplied, it specifies the minimum number of digits to appear; leading zeros are produced if necessary. If you don't specify a precision, the number is printed with as many digits as it needs. If you convert a value of zero with an explicit precision of zero, then no characters at all are produced.
Without a type modifier, the corresponding argument is treated as an
int (for the signed conversions `%i' and `%d') or
unsigned int (for the unsigned conversions `%o', `%u',
`%x', and `%X'). Recall that since printf and friends
are variadic, any char and short arguments are
automatically converted to int by the default argument
promotions. For arguments of other integer types, you can use these
modifiers:
short int or unsigned
short int, as appropriate. A short argument is converted to an
int or unsigned int by the default argument promotions
anyway, but the `h' modifier says to convert it back to a
short again.
long int or unsigned long
int, as appropriate. Two `l' characters is like the `L'
modifier, below.
long long int. (This type is
an extension supported by the GNU C compiler. On systems that don't
support extra-long integers, this is the same as long int.)
The `q' modifier is another name for the same thing, which comes
from 4.4 BSD; a long long int is sometimes called a "quad"
int.
size_t. This is a GNU extension.
Here is an example. Using the template string:
"|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"
to print numbers using the different options for the `%d' conversion gives results like:
| 0|0 | +0|+0 | 0|00000| | 00|0| | 1|1 | +1|+1 | 1|00001| 1| 01|1| | -1|-1 | -1|-1 | -1|-0001| -1| -01|-1| |100000|100000|+100000| 100000|100000|100000|100000|100000|
In particular, notice what happens in the last case where the number is too large to fit in the minimum field width specified.
Here are some more examples showing how unsigned integers print under various format options, using the template string:
"|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n"
| 0| 0| 0| 0| 0| 0x0| 0X0|0x00000000| | 1| 1| 1| 1| 01| 0x1| 0X1|0x00000001| |100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0|
This section discusses the conversion specifications for floating-point numbers: the `%f', `%e', `%E', `%g', and `%G' conversions.
The `%f' conversion prints its argument in fixed-point notation,
producing output of the form
[-]ddd.ddd,
where the number of digits following the decimal point is controlled
by the precision you specify.
The `%e' conversion prints its argument in exponential notation,
producing output of the form
[-]d.ddde[+|-]dd.
Again, the number of digits following the decimal point is controlled by
the precision. The exponent always contains at least two digits. The
`%E' conversion is similar but the exponent is marked with the letter
`E' instead of `e'.
The `%g' and `%G' conversions print the argument in the style of `%e' or `%E' (respectively) if the exponent would be less than -4 or greater than or equal to the precision; otherwise they use the `%f' style. Trailing zeros are removed from the fractional portion of the result and a decimal-point character appears only if it is followed by a digit.
The following flags can be used to modify the behavior:
LC_NUMERIC category;
see section Generic Numeric Formatting Parameters. This flag is a GNU extension.
The precision specifies how many digits follow the decimal-point
character for the `%f', `%e', and `%E' conversions. For
these conversions, the default precision is 6. If the precision
is explicitly 0, this suppresses the decimal point character
entirely. For the `%g' and `%G' conversions, the precision
specifies how many significant digits to print. Significant digits are
the first digit before the decimal point, and all the digits after it.
If the precision 0 or not specified for `%g' or `%G',
it is treated like a value of 1. If the value being printed
cannot be expressed accurately in the specified number of digits, the
value is rounded to the nearest number that fits.
Without a type modifier, the floating-point conversions use an argument
of type double. (By the default argument promotions, any
float arguments are automatically converted to double.)
The following type modifier is supported:
long
double.
Here are some examples showing how numbers print using the various floating-point conversions. All of the numbers were printed using this template string:
"|%12.4f|%12.4e|%12.4g|\n"
Here is the output:
| 0.0000| 0.0000e+00| 0| | 1.0000| 1.0000e+00| 1| | -1.0000| -1.0000e+00| -1| | 100.0000| 1.0000e+02| 100| | 1000.0000| 1.0000e+03| 1000| | 10000.0000| 1.0000e+04| 1e+04| | 12345.0000| 1.2345e+04| 1.234e+04| | 100000.0000| 1.0000e+05| 1e+05| | 123456.0000| 1.2346e+05| 1.234e+05|
Notice how the `%g' conversion drops trailing zeros.
This section describes miscellaneous conversions for printf.
The `%c' conversion prints a single character. The int
argument is first converted to an unsigned char. The `-'
flag can be used to specify left-justification in the field, but no
other flags are defined, and no precision or type modifier can be given.
For example:
printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o');
prints `hello'.
The `%s' conversion prints a string. The corresponding argument
must be of type char * (or const char *). A precision can
be specified to indicate the maximum number of characters to write;
otherwise characters in the string up to but not including the
terminating null character are written to the output stream. The
`-' flag can be used to specify left-justification in the field,
but no other flags or type modifiers are defined for this conversion.
For example:
printf ("%3s%-6s", "no", "where");
prints ` nowhere '.
If you accidentally pass a null pointer as the argument for a `%s' conversion, the GNU library prints it as `(null)'. We think this is more useful than crashing. But it's not good practice to pass a null argument intentionally.
The `%m' conversion prints the string corresponding to the error
code in errno. See section Error Messages. Thus:
fprintf (stderr, "can't open `%s': %m\n", filename);
is equivalent to:
fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno));
The `%m' conversion is a GNU C library extension.
The `%p' conversion prints a pointer value. The corresponding
argument must be of type void *. In practice, you can use any
type of pointer.
In the GNU system, non-null pointers are printed as unsigned integers, as if a `%#x' conversion were used. Null pointers print as `(nil)'. (Pointers might print differently in other systems.)
For example:
printf ("%p", "testing");
prints `0x' followed by a hexadecimal number--the address of the
string constant "testing". It does not print the word
`testing'.
You can supply the `-' flag with the `%p' conversion to specify left-justification, but no other flags, precision, or type modifiers are defined.
The `%n' conversion is unlike any of the other output conversions.
It uses an argument which must be a pointer to an int, but
instead of printing anything it stores the number of characters printed
so far by this call at that location. The `h' and `l' type
modifiers are permitted to specify that the argument is of type
short int * or long int * instead of int *, but no
flags, field width, or precision are permitted.
For example,
int nchar;
printf ("%d %s%n\n", 3, "bears", &nchar);
prints:
3 bears
and sets nchar to 7, because `3 bears' is seven
characters.
The `%%' conversion prints a literal `%' character. This conversion doesn't use an argument, and no flags, field width, precision, or type modifiers are permitted.
This section describes how to call printf and related functions.
Prototypes for these functions are in the header file `stdio.h'.
Because these functions take a variable number of arguments, you
must declare prototypes for them before using them. Of course,
the easiest way to make sure you have all the right prototypes is to
just include `stdio.h'.
printf function prints the optional arguments under the
control of the template string template to the stream
stdout. It returns the number of characters printed, or a
negative value if there was an output error.
printf, except that the output is
written to the stream stream instead of stdout.
printf, except that the output is stored in the character
array s instead of written to a stream. A null character is written
to mark the end of the string.
The sprintf function returns the number of characters stored in
the array s, not including the terminating null character.
The behavior of this function is undefined if copying takes place between objects that overlap--for example, if s is also given as an argument to be printed under control of the `%s' conversion. See section Copying and Concatenation.
Warning: The sprintf function can be dangerous
because it can potentially output more characters than can fit in the
allocation size of the string s. Remember that the field width
given in a conversion specification is only a minimum value.
To avoid this problem, you can use snprintf or asprintf,
described below.
snprintf function is similar to sprintf, except that
the size argument specifies the maximum number of characters to
produce. The trailing null character is counted towards this limit, so
you should allocate at least size characters for the string s.
The return value is the number of characters stored, not including the
terminating null. If this value equals size - 1, then
there was not enough space in s for all the output. You should
try again with a bigger output string. Here is an example of doing
this:
/* Construct a message describing the value of a variable
whose name is name and whose value is value. */
char *
make_message (char *name, char *value)
{
/* Guess we need no more than 100 chars of space. */
int size = 100;
char *buffer = (char *) xmalloc (size);
while (1)
{
/* Try to print in the allocated space. */
int nchars = snprintf (buffer, size,
"value of %s is %s",
name, value);
/* If that worked, return the string. */
if (nchars < size)
return buffer;
/* Else try again with twice as much space. */
size *= 2;
buffer = (char *) xrealloc (size, buffer);
}
}
In practice, it is often easier just to use asprintf, below.
The functions in this section do formatted output and place the results in dynamically allocated memory.
sprintf, except that it dynamically
allocates a string (as with malloc; see section Unconstrained Allocation) to hold the output, instead of putting the output in a
buffer you allocate in advance. The ptr argument should be the
address of a char * object, and asprintf stores a pointer
to the newly allocated string at that location.
Here is how to use asprintf to get the same result as the
snprintf example, but more easily:
/* Construct a message describing the value of a variable
whose name is name and whose value is value. */
char *
make_message (char *name, char *value)
{
char *result;
asprintf (&result, "value of %s is %s", name, value);
return result;
}
asprintf, except that it uses the
obstack obstack to allocate the space. See section Obstacks.
The characters are written onto the end of the current object.
To get at them, you must finish the object with obstack_finish
(see section Growing Objects).
The functions vprintf and friends are provided so that you can
define your own variadic printf-like functions that make use of
the same internals as the built-in formatted output functions.
The most natural way to define such functions would be to use a language
construct to say, "Call printf and pass this template plus all
of my arguments after the first five." But there is no way to do this
in C, and it would be hard to provide a way, since at the C language
level there is no way to tell how many arguments your function received.
Since that method is impossible, we provide alternative functions, the
vprintf series, which lets you pass a va_list to describe
"all of my arguments after the first five."
When it is sufficient to define a macro rather than a real function, the GNU C compiler provides a way to do this much more easily with macros. For example:
#define myprintf(a, b, c, d, e, rest...) printf (mytemplate , ## rest...)
See section `Macros with Variable Numbers of Arguments' in Using GNU CC, for details. But this is limited to macros, and does not apply to real functions at all.
Before calling vprintf or the other functions listed in this
section, you must call va_start (see section Variadic Functions) to initialize a pointer to the variable arguments. Then you
can call va_arg to fetch the arguments that you want to handle
yourself. This advances the pointer past those arguments.
Once your va_list pointer is pointing at the argument of your
choice, you are ready to call vprintf. That argument and all
subsequent arguments that were passed to your function are used by
vprintf along with the template that you specified separately.
In some other systems, the va_list pointer may become invalid
after the call to vprintf, so you must not use va_arg
after you call vprintf. Instead, you should call va_end
to retire the pointer from service. However, you can safely call
va_start on another pointer variable and begin fetching the
arguments again through that pointer. Calling vprintf does not
destroy the argument list of your function, merely the particular
pointer that you passed to it.
GNU C does not have such restrictions. You can safely continue to fetch
arguments from a va_list pointer after passing it to
vprintf, and va_end is a no-op. (Note, however, that
subsequent va_arg calls will fetch the same arguments which
vprintf previously used.)
Prototypes for these functions are declared in `stdio.h'.
printf except that, instead of taking
a variable number of arguments directly, it takes an argument list
pointer ap.
fprintf with the variable argument list
specified directly as for vprintf.
sprintf with the variable argument list
specified directly as for vprintf.
snprintf with the variable argument list
specified directly as for vprintf.
vasprintf function is the equivalent of asprintf with the
variable argument list specified directly as for vprintf.
obstack_vprintf function is the equivalent of
obstack_printf with the variable argument list specified directly
as for vprintf.
Here's an example showing how you might use vfprintf. This is a
function that prints error messages to the stream stderr, along
with a prefix indicating the name of the program
(see section Error Messages, for a description of
program_invocation_short_name).
#include <stdio.h>
#include <stdarg.h>
void
eprintf (const char *template, ...)
{
va_list ap;
extern char *program_invocation_short_name;
fprintf (stderr, "%s: ", program_invocation_short_name);
va_start (ap, count);
vfprintf (stderr, template, ap);
va_end (ap);
}
You could call eprintf like this:
eprintf ("file `%s' does not exist\n", filename);
In GNU C, there is a special construct you can use to let the compiler
know that a function uses a printf-style format string. Then it
can check the number and types of arguments in each call to the
function, and warn you when they do not match the format string.
For example, take this declaration of eprintf:
void eprintf (const char *template, ...)
__attribute__ ((format (printf, 1, 2)));
This tells the compiler that eprintf uses a format string like
printf (as opposed to scanf; see section Formatted Input);
the format string appears as the first argument;
and the arguments to satisfy the format begin with the second.
See section `Declaring Attributes of Functions' in Using GNU CC, for more information.
You can use the function parse_printf_format to obtain
information about the number and types of arguments that are expected by
a given template string. This function permits interpreters that
provide interfaces to printf to avoid passing along invalid
arguments from the user's program, which could cause a crash.
All the symbols described in this section are declared in the header file `printf.h'.
printf template string template.
The information is stored in the array argtypes; each element of
this array describes one argument. This information is encoded using
the various `PA_' macros, listed below.
The n argument specifies the number of elements in the array
argtypes. This is the most elements that
parse_printf_format will try to write.
parse_printf_format returns the total number of arguments required
by template. If this number is greater than n, then the
information returned describes only the first n arguments. If you
want information about more than that many arguments, allocate a bigger
array and call parse_printf_format again.
The argument types are encoded as a combination of a basic type and modifier flag bits.
(argtypes[i] & PA_FLAG_MASK) to extract just the
flag bits for an argument, or (argtypes[i] & ~PA_FLAG_MASK) to
extract just the basic type code.
Here are symbolic constants that represent the basic types; they stand for integer values.
PA_INT
int.
PA_CHAR
int, cast to char.
PA_STRING
char *, a null-terminated string.
PA_POINTER
void *, an arbitrary pointer.
PA_FLOAT
float.
PA_DOUBLE
double.
PA_LAST
PA_LAST. For example, if you have data types `foo'
and `bar' with their own specialized printf conversions,
you could define encodings for these types as:
#define PA_FOO PA_LAST #define PA_BAR (PA_LAST + 1)
Here are the flag bits that modify a basic type. They are combined with the code for the basic type using inclusive-or.
PA_FLAG_PTR
PA_FLAG_SHORT
short. (This corresponds to the `h' type modifier.)
PA_FLAG_LONG
long. (This corresponds to the `l' type modifier.)
PA_FLAG_LONG_LONG
long long. (This corresponds to the `L' type modifier.)
PA_FLAG_LONG_DOUBLE
PA_FLAG_LONG_LONG, used by convention with
a base type of PA_DOUBLE to indicate a type of long double.
Here is an example of decoding argument types for a format string. We
assume this is part of an interpreter which contains arguments of type
NUMBER, CHAR, STRING and STRUCTURE (and
perhaps others which are not valid here).
/* Test whether the nargs specified objects
in the vector args are valid
for the format string format:
if so, return 1.
If not, return 0 after printing an error message. */
int
validate_args (char *format, int nargs, OBJECT *args)
{
int *argtypes;
int nwanted;
/* Get the information about the arguments.
Each conversion specification must be at least two characters
long, so there cannot be more specifications than half the
length of the string. */
argtypes = (int *) alloca (strlen (format) / 2 * sizeof (int));
nwanted = parse_printf_format (string, nelts, argtypes);
/* Check the number of arguments. */
if (nwanted > nargs)
{
error ("too few arguments (at least %d required)", nwanted);
return 0;
}
/* Check the C type wanted for each argument
and see if the object given is suitable. */
for (i = 0; i < nwanted; i++)
{
int wanted;
if (argtypes[i] & PA_FLAG_PTR)
wanted = STRUCTURE;
else
switch (argtypes[i] & ~PA_FLAG_MASK)
{
case PA_INT:
case PA_FLOAT:
case PA_DOUBLE:
wanted = NUMBER;
break;
case PA_CHAR:
wanted = CHAR;
break;
case PA_STRING:
wanted = STRING;
break;
case PA_POINTER:
wanted = STRUCTURE;
break;
}
if (TYPE (args[i]) != wanted)
{
error ("type mismatch for arg number %d", i);
return 0;
}
}
return 1;
}
printf
The GNU C library lets you define your own custom conversion specifiers
for printf template strings, to teach printf clever ways
to print the important data structures of your program.
The way you do this is by registering the conversion with the function
register_printf_function; see section Registering New Conversions.
One of the arguments you pass to this function is a pointer to a handler
function that produces the actual output; see section Defining the Output Handler, for information on how to write this function.
You can also install a function that just returns information about the number and type of arguments expected by the conversion specifier. See section Parsing a Template String, for information about this.
The facilities of this section are declared in the header file `printf.h'.
Portability Note: The ability to extend the syntax of
printf template strings is a GNU extension. ISO standard C has
nothing similar.
The function to register a new output conversion is
register_printf_function, declared in `printf.h'.
'z', it defines the conversion `%z'.
You can redefine the built-in conversions like `%s', but flag
characters like `#' and type modifiers like `l' can never be
used as conversions; calling register_printf_function for those
characters has no effect.
The handler-function is the function called by printf and
friends when this conversion appears in a template string.
See section Defining the Output Handler, for information about how to define
a function to pass as this argument. If you specify a null pointer, any
existing handler function for spec is removed.
The arginfo-function is the function called by
parse_printf_format when this conversion appears in a
template string. See section Parsing a Template String, for information
about this.
Attention: In the GNU C library version before 2.0 the
arginfo-function function did not need to be installed unless
the user uses the parse_printf_format function. This changed.
Now a call to any of the printf functions will call this
function when this format specifier appears in the format string.
The return value is 0 on success, and -1 on failure
(which occurs if spec is out of range).
You can redefine the standard output conversions, but this is probably not a good idea because of the potential for confusion. Library routines written by other people could break if you do this.
If you define a meaning for `%A', what if the template contains `%+23A' or `%-#A'? To implement a sensible meaning for these, the handler when called needs to be able to get the options specified in the template.
Both the handler-function and arginfo-function arguments
to register_printf_function accept an argument that points to a
struct printf_info, which contains information about the options
appearing in an instance of the conversion specifier. This data type
is declared in the header file `printf.h'.
printf template
string to the handler and arginfo functions for that specifier. It
contains the following members:
int prec
-1 if no precision
was specified. If the precision was given as `*', the
printf_info structure passed to the handler function contains the
actual value retrieved from the argument list. But the structure passed
to the arginfo function contains a value of INT_MIN, since the
actual value is not known.
int width
0 if no
width was specified. If the field width was given as `*', the
printf_info structure passed to the handler function contains the
actual value retrieved from the argument list. But the structure passed
to the arginfo function contains a value of INT_MIN, since the
actual value is not known.
wchar_t spec
unsigned int is_long_double
long long int, as opposed to long double for floating
point conversions.
unsigned int is_short
unsigned int is_long
unsigned int alt
unsigned int space
unsigned int left
unsigned int showsign
unsigned int group
unsigned int extra
printf function this variable always contains the value
0.
wchar_t pad
'0' if the `0' flag was specified, and
' ' otherwise.
Now let's look at how to define the handler and arginfo functions
which are passed as arguments to register_printf_function.
Compatibility Note: The interface change in the GNU libc
version 2.0. Previously the third argument was of type
va_list *.
You should define your handler functions with a prototype like:
int function (FILE *stream, const struct printf_info *info,
const void *const *args)
The stream argument passed to the handler function is the stream to which it should write output.
The info argument is a pointer to a structure that contains information about the various options that were included with the conversion in the template string. You should not modify this structure inside your handler function. See section Conversion Specifier Options, for a description of this data structure.
The args is a vector of pointers to the arguments data. The number of arguments were determined by calling the argument information function provided by the user.
Your handler function should return a value just like printf
does: it should return the number of characters it has written, or a
negative value to indicate an error.
If you are going to use parse_printf_format in your
application, you must also define a function to pass as the
arginfo-function argument for each new conversion you install with
register_printf_function.
You have to define these functions with a prototype like:
int function (const struct printf_info *info,
size_t n, int *argtypes)
The return value from the function should be the number of arguments the
conversion expects. The function should also fill in no more than
n elements of the argtypes array with information about the
types of each of these arguments. This information is encoded using the
various `PA_' macros. (You will notice that this is the same
calling convention parse_printf_format itself uses.)
printf Extension Example
Here is an example showing how to define a printf handler function.
This program defines a data structure called a Widget and
defines the `%W' conversion to print information about Widget *
arguments, including the pointer value and the name stored in the data
structure. The `%W' conversion supports the minimum field width and
left-justification options, but ignores everything else.
#include <stdio.h>
#include <printf.h>
#include <stdarg.h>
typedef struct
{
char *name;
} Widget;
int
print_widget (FILE *stream, const struct printf_info *info, va_list *app)
{
Widget *w;
char *buffer;
int len;
/* Format the output into a string. */
w = va_arg (*app, Widget *);
len = asprintf (&buffer, "<Widget %p: %s>", w, w->name);
if (len == -1)
return -1;
/* Pad to the minimum field width and print to the stream. */
len = fprintf (stream, "%*s",
(info->left ? - info->width : info->width),
buffer);
/* Clean up and return. */
free (buffer);
return len;
}
int
print_widget_arginfo (const struct printf_info *info, size_t n,
int *argtypes)
{
/* We always take exactly one argument and this is a pointer to the
structure.. */
if (n > 0)
argtypes[0] = PA_POINTER;
return 1;
}
int
main (void)
{
/* Make a widget to print. */
Widget mywidget;
mywidget.name = "mywidget";
/* Register the print function for widgets. */
register_printf_function ('W', print_widget, print_widget_arginfo);
/* Now print the widget. */
printf ("|%W|\n", &mywidget);
printf ("|%35W|\n", &mywidget);
printf ("|%-35W|\n", &mywidget);
return 0;
}
The output produced by this program looks like:
|<Widget 0xffeffb7c: mywidget>| | <Widget 0xffeffb7c: mywidget>| |<Widget 0xffeffb7c: mywidget> |
The functions described in this section (scanf and related
functions) provide facilities for formatted input analogous to the
formatted output facilities. These functions provide a mechanism for
reading arbitrary values under the control of a format string or
template string.
Calls to scanf are superficially similar to calls to
printf in that arbitrary arguments are read under the control of
a template string. While the syntax of the conversion specifications in
the template is very similar to that for printf, the
interpretation of the template is oriented more towards free-format
input and simple pattern matching, rather than fixed-field formatting.
For example, most scanf conversions skip over any amount of
"white space" (including spaces, tabs, and newlines) in the input
file, and there is no concept of precision for the numeric input
conversions as there is for the corresponding output conversions.
Ordinarily, non-whitespace characters in the template are expected to
match characters in the input stream exactly, but a matching failure is
distinct from an input error on the stream.
Another area of difference between scanf and printf is
that you must remember to supply pointers rather than immediate values
as the optional arguments to scanf; the values that are read are
stored in the objects that the pointers point to. Even experienced
programmers tend to forget this occasionally, so if your program is
getting strange errors that seem to be related to scanf, you
might want to double-check this.
When a matching failure occurs, scanf returns immediately,
leaving the first non-matching character as the next character to be
read from the stream. The normal return value from scanf is the
number of values that were assigned, so you can use this to determine if
a matching error happened before all the expected values were read.
The scanf function is typically used for things like reading in
the contents of tables. For example, here is a function that uses
scanf to initialize an array of double:
void
readarray (double *array, int n)
{
int i;
for (i=0; i<n; i++)
if (scanf (" %lf", &(array[i])) != 1)
invalid_input_error ();
}
The formatted input functions are not used as frequently as the formatted output functions. Partly, this is because it takes some care to use them properly. Another reason is that it is difficult to recover from a matching error.
If you are trying to read input that doesn't match a single, fixed
pattern, you may be better off using a tool such as Flex to generate a
lexical scanner, or Bison to generate a parser, rather than using
scanf. For more information about these tools, see section `' in Flex: The Lexical Scanner Generator, and section `' in The Bison Reference Manual.
A scanf template string is a string that contains ordinary
multibyte characters interspersed with conversion specifications that
start with `%'.
Any whitespace character (as defined by the isspace function;
see section Classification of Characters) in the template causes any number
of whitespace characters in the input stream to be read and discarded.
The whitespace characters that are matched need not be exactly the same
whitespace characters that appear in the template string. For example,
write ` , ' in the template to recognize a comma with optional
whitespace before and after.
Other characters in the template string that are not part of conversion specifications must match characters in the input stream exactly; if this is not the case, a matching failure occurs.
The conversion specifications in a scanf template string
have the general form:
% flags width type conversion
In more detail, an input conversion specification consists of an initial `%' character followed in sequence by:
scanf finds a conversion
specification that uses this flag, it reads input as directed by the
rest of the conversion specification, but it discards this input, does
not use a pointer argument, and does not increment the count of
successful assignments.
long int
rather than a pointer to an int.
The exact options that are permitted and how they are interpreted vary between the different conversion specifiers. See the descriptions of the individual conversions for information about the particular options that they allow.
With the `-Wformat' option, the GNU C compiler checks calls to
scanf and related functions. It examines the format string and
verifies that the correct number and types of arguments are supplied.
There is also a GNU C syntax to tell the compiler that a function you
write uses a scanf-style format string.
See section `Declaring Attributes of Functions' in Using GNU CC, for more information.
Here is a table that summarizes the various conversion specifications:
printf. See section Other Input Conversions.
If the syntax of a conversion specification is invalid, the behavior is undefined. If there aren't enough function arguments provided to supply addresses for all the conversion specifications in the template strings that perform assignments, or if the arguments are not of the correct types, the behavior is also undefined. On the other hand, extra arguments are simply ignored.
This section describes the scanf conversions for reading numeric
values.
The `%d' conversion matches an optionally signed integer in decimal
radix. The syntax that is recognized is the same as that for the
strtol function (see section Parsing of Integers) with the value
10 for the base argument.
The `%i' conversion matches an optionally signed integer in any of
the formats that the C language defines for specifying an integer
constant. The syntax that is recognized is the same as that for the
strtol function (see section Parsing of Integers) with the value
0 for the base argument. (You can print integers in this
syntax with printf by using the `#' flag character with the
`%x', `%o', or `%d' conversion. See section Integer Conversions.)
For example, any of the strings `10', `0xa', or `012'
could be read in as integers under the `%i' conversion. Each of
these specifies a number with decimal value 10.
The `%o', `%u', and `%x' conversions match unsigned
integers in octal, decimal, and hexadecimal radices, respectively. The
syntax that is recognized is the same as that for the strtoul
function (see section Parsing of Integers) with the appropriate value
(8, 10, or 16) for the base argument.
The `%X' conversion is identical to the `%x' conversion. They both permit either uppercase or lowercase letters to be used as digits.
The default type of the corresponding argument for the %d and
%i conversions is int *, and unsigned int * for the
other integer conversions. You can use the following type modifiers to
specify other sizes of integer:
short int * or unsigned
short int *.
long int * or unsigned
long int *. Two `l' characters is like the `L' modifier, below.
long long int * or unsigned long long int *. (The long long type is an extension supported by the
GNU C compiler. For systems that don't provide extra-long integers, this
is the same as long int.)
The `q' modifier is another name for the same thing, which comes
from 4.4 BSD; a long long int is sometimes called a "quad"
int.
All of the `%e', `%f', `%g', `%E', and `%G'
input conversions are interchangeable. They all match an optionally
signed floating point number, in the same syntax as for the
strtod function (see section Parsing of Floats).
For the floating-point input conversions, the default argument type is
float *. (This is different from the corresponding output
conversions, where the default type is double; remember that
float arguments to printf are converted to double
by the default argument promotions, but float * arguments are
not promoted to double *.) You can specify other sizes of float
using these type modifiers:
double *.
long double *.
For all the above number parsing formats there is an additional optional
flag `''. When this flag is given the scanf function
expects the number represented in the input string to be formatted
according to the grouping rules of the currently selected locale
(see section Generic Numeric Formatting Parameters).
If the "C" or "POSIX" locale is selected there is no
difference. But for a locale which specifies values for the appropriate
fields in the locale the input must have the correct form in the input.
Otherwise the longest prefix with a correct form is processed.
This section describes the scanf input conversions for reading
string and character values: `%s', `%[', and `%c'.
You have two options for how to receive the input from these conversions:
char *.
Warning: To make a robust program, you must make sure that the
input (plus its terminating null) cannot possibly exceed the size of the
buffer you provide. In general, the only way to do this is to specify a
maximum field width one less than the buffer size. If you
provide the buffer, always specify a maximum field width to prevent
overflow.
scanf to allocate a big enough buffer, by specifying the
`a' flag character. This is a GNU extension. You should provide
an argument of type char ** for the buffer address to be stored
in. See section Dynamically Allocating String Conversions.
The `%c' conversion is the simplest: it matches a fixed number of characters, always. The maximum field with says how many characters to read; if you don't specify the maximum, the default is 1. This conversion doesn't append a null character to the end of the text it reads. It also does not skip over initial whitespace characters. It reads precisely the next n characters, and fails if it cannot get that many. Since there is always a maximum field width with `%c' (whether specified, or 1 by default), you can always prevent overflow by making the buffer long enough.
The `%s' conversion matches a string of non-whitespace characters. It skips and discards initial whitespace, but stops when it encounters more whitespace after having read something. It stores a null character at the end of the text that it reads.
For example, reading the input:
hello, world
with the conversion `%10c' produces " hello, wo", but
reading the same input with the conversion `%10s' produces
"hello,".
Warning: If you do not specify a field width for `%s', then the number of characters read is limited only by where the next whitespace character appears. This almost certainly means that invalid input can make your program crash--which is a bug.
To read in characters that belong to an arbitrary set of your choice, use the `%[' conversion. You specify the set between the `[' character and a following `]' character, using the same syntax used in regular expressions. As special cases:
The `%[' conversion does not skip over initial whitespace characters.
Here are some examples of `%[' conversions and what they mean:
One more reminder: the `%s' and `%[' conversions are dangerous if you don't specify a maximum width or use the `a' flag, because input too long would overflow whatever buffer you have provided for it. No matter how long your buffer is, a user could supply input that is longer. A well-written program reports invalid input with a comprehensible error message, not with a crash.
A GNU extension to formatted input lets you safely read a string with no
maximum size. Using this feature, you don't supply a buffer; instead,
scanf allocates a buffer big enough to hold the data and gives
you its address. To use this feature, write `a' as a flag
character, as in `%as' or `%a[0-9a-z]'.
The pointer argument you supply for where to store the input should have
type char **. The scanf function allocates a buffer and
stores its address in the word that the argument points to. You should
free the buffer with free when you no longer need it.
Here is an example of using the `a' flag with the `%[...]' conversion specification to read a "variable assignment" of the form `variable = value'.
{
char *variable, *value;
if (2 > scanf ("%a[a-zA-Z0-9] = %a[^\n]\n",
&variable, &value))
{
invalid_input_error ();
return 0;
}
...
}
This section describes the miscellaneous input conversions.
The `%p' conversion is used to read a pointer value. It recognizes
the same syntax as is used by the `%p' output conversion for
printf (see section Other Output Conversions); that is, a hexadecimal
number just as the `%x' conversion accepts. The corresponding
argument should be of type void **; that is, the address of a
place to store a pointer.
The resulting pointer value is not guaranteed to be valid if it was not originally written during the same program execution that reads it in.
The `%n' conversion produces the number of characters read so far
by this call. The corresponding argument should be of type int *.
This conversion works in the same way as the `%n' conversion for
printf; see section Other Output Conversions, for an example.
The `%n' conversion is the only mechanism for determining the
success of literal matches or conversions with suppressed assignments.
If the `%n' follows the locus of a matching failure, then no value
is stored for it since scanf returns before processing the
`%n'. If you store -1 in that argument slot before calling
scanf, the presence of -1 after scanf indicates an
error occurred before the `%n' was reached.
Finally, the `%%' conversion matches a literal `%' character in the input stream, without using an argument. This conversion does not permit any flags, field width, or type modifier to be specified.
Here are the descriptions of the functions for performing formatted input. Prototypes for these functions are in the header file `stdio.h'.
scanf function reads formatted input from the stream
stdin under the control of the template string template.
The optional arguments are pointers to the places which receive the
resulting values.
The return value is normally the number of successful assignments. If
an end-of-file condition is detected before any matches are performed
(including matches against whitespace and literal characters in the
template), then EOF is returned.
scanf, except that the input is read
from the stream stream instead of stdin.
scanf, except that the characters are taken from the
null-terminated string s instead of from a stream. Reaching the
end of the string is treated as an end-of-file condition.
The behavior of this function is undefined if copying takes place between objects that overlap--for example, if s is also given as an argument to receive a string read under control of the `%s' conversion.
The functions vscanf and friends are provided so that you can
define your own variadic scanf-like functions that make use of
the same internals as the built-in formatted output functions.
These functions are analogous to the vprintf series of output
functions. See section Variable Arguments Output Functions, for important
information on how to use them.
Portability Note: The functions listed in this section are GNU extensions.
scanf except that, instead of taking
a variable number of arguments directly, it takes an argument list
pointer ap of type va_list (see section Variadic Functions).
fscanf with the variable argument list
specified directly as for vscanf.
sscanf with the variable argument list
specified directly as for vscanf.
In GNU C, there is a special construct you can use to let the compiler
know that a function uses a scanf-style format string. Then it
can check the number and types of arguments in each call to the
function, and warn you when they do not match the format string.
See section `Declaring Attributes of Functions' in Using GNU CC, for details.
Many of the functions described in this chapter return the value of the
macro EOF to indicate unsuccessful completion of the operation.
Since EOF is used to report both end of file and random errors,
it's often better to use the feof function to check explicitly
for end of file and ferror to check for errors. These functions
check indicators that are part of the internal state of the stream
object, indicators set if the appropriate condition was detected by a
previous I/O operation on that stream.
These symbols are declared in the header file `stdio.h'.
EOF is -1. In other libraries, its
value may be some other negative number.
The file positioning functions (see section File Positioning) also clear the end-of-file indicator for the stream.
feof function returns nonzero if and only if the end-of-file
indicator for the stream stream is set.
ferror function returns nonzero if and only if the error
indicator for the stream stream is set, indicating that an error
has occurred on a previous operation on the stream.
In addition to setting the error indicator associated with the stream,
the functions that operate on streams also set errno in the same
way as the corresponding low-level functions that operate on file
descriptors. For example, all of the functions that perform output to a
stream--such as fputc, printf, and fflush---are
implemented in terms of write, and all of the errno error
conditions defined for write are meaningful for these functions.
For more information about the descriptor-level I/O functions, see
section Low-Level Input/Output.
The GNU system and other POSIX-compatible operating systems organize all files as uniform sequences of characters. However, some other systems make a distinction between files containing text and files containing binary data, and the input and output facilities of ISO C provide for this distinction. This section tells you how to write programs portable to such systems.
When you open a stream, you can specify either a text stream or a
binary stream. You indicate that you want a binary stream by
specifying the `b' modifier in the opentype argument to
fopen; see section Opening Streams. Without this
option, fopen opens the file as a text stream.
Text and binary streams differ in several ways:
'\n') characters, while a binary stream is
simply a long series of characters. A text stream might on some systems
fail to handle lines more than 254 characters long (including the
terminating newline character).
Since a binary stream is always more capable and more predictable than a text stream, you might wonder what purpose text streams serve. Why not simply always use binary streams? The answer is that on these operating systems, text and binary streams use different file formats, and the only way to read or write "an ordinary file of text" that can work with other text-oriented programs is through a text stream.
In the GNU library, and on all POSIX systems, there is no difference between text streams and binary streams. When you open a stream, you get the same kind of stream regardless of whether you ask for binary. This stream can handle any file content, and has none of the restrictions that text streams sometimes have.
The file position of a stream describes where in the file the stream is currently reading or writing. I/O on the stream advances the file position through the file. In the GNU system, the file position is represented as an integer, which counts the number of bytes from the beginning of the file. See section File Position.
During I/O to an ordinary disk file, you can change the file position whenever you wish, so as to read or write any portion of the file. Some other kinds of files may also permit this. Files which support changing the file position are sometimes referred to as random-access files.
You can use the functions in this section to examine or modify the file position indicator associated with a stream. The symbols listed below are declared in the header file `stdio.h'.
This function can fail if the stream doesn't support file positioning,
or if the file position can't be represented in a long int, and
possibly for other reasons as well. If a failure occurs, a value of
-1 is returned.
fseek function is used to change the file position of the
stream stream. The value of whence must be one of the
constants SEEK_SET, SEEK_CUR, or SEEK_END, to
indicate whether the offset is relative to the beginning of the
file, the current file position, or the end of the file, respectively.
This function returns a value of zero if the operation was successful,
and a nonzero value to indicate failure. A successful call also clears
the end-of-file indicator of stream and discards any characters
that were "pushed back" by the use of ungetc.
fseek either flushes any buffered output before setting the file
position or else remembers it so it will be written later in its proper
place in the file.
Portability Note: In non-POSIX systems, ftell and
fseek might work reliably only on binary streams. See section Text and Binary Streams.
The following symbolic constants are defined for use as the whence
argument to fseek. They are also used with the lseek
function (see section Input and Output Primitives) and to specify offsets for file locks
(see section Control Operations on Files).
fseek function, specifies that the offset
provided is relative to the beginning of the file.
fseek function, specifies that the offset
provided is relative to the current file position.
fseek function, specifies that the offset
provided is relative to the end of the file.
rewind function positions the stream stream at the
begining of the file. It is equivalent to calling fseek on the
stream with an offset argument of 0L and a
whence argument of SEEK_SET, except that the return
value is discarded and the error indicator for the stream is reset.
These three aliases for the `SEEK_...' constants exist for the sake of compatibility with older BSD systems. They are defined in two different header files: `fcntl.h' and `sys/file.h'.
L_SET
SEEK_SET.
L_INCR
SEEK_CUR.
L_XTND
SEEK_END.
On the GNU system, the file position is truly a character count. You
can specify any character count value as an argument to fseek and
get reliable results for any random access file. However, some ISO C
systems do not represent file positions in this way.
On some systems where text streams truly differ from binary streams, it is impossible to represent the file position of a text stream as a count of characters from the beginning of the file. For example, the file position on some systems must encode both a record offset within the file, and a character offset within the record.
As a consequence, if you want your programs to be portable to these systems, you must observe certain rules:
ftell on a text stream has no predictable
relationship to the number of characters you have read so far. The only
thing you can rely on is that you can use it subsequently as the
offset argument to fseek to move back to the same file
position.
fseek on a text stream, either the offset must
either be zero; or whence must be SEEK_SET and the
offset must be the result of an earlier call to ftell on
the same stream.
ungetc
that haven't been read or discarded. See section Unreading.
But even if you observe these rules, you may still have trouble for long
files, because ftell and fseek use a long int value
to represent the file position. This type may not have room to encode
all the file positions in a large file.
So if you do want to support systems with peculiar encodings for the
file positions, it is better to use the functions fgetpos and
fsetpos instead. These functions represent the file position
using the data type fpos_t, whose internal representation varies
from system to system.
These symbols are declared in the header file `stdio.h'.
fgetpos and
fsetpos.
In the GNU system, fpos_t is equivalent to off_t or
long int. In other systems, it might have a different internal
representation.
fpos_t object pointed to by
position. If successful, fgetpos returns zero; otherwise
it returns a nonzero value and stores an implementation-defined positive
value in errno.
fgetpos on the same stream. If successful, fsetpos
clears the end-of-file indicator on the stream, discards any characters
that were "pushed back" by the use of ungetc, and returns a value
of zero. Otherwise, fsetpos returns a nonzero value and stores
an implementation-defined positive value in errno.
Characters that are written to a stream are normally accumulated and transmitted asynchronously to the file in a block, instead of appearing as soon as they are output by the application program. Similarly, streams often retrieve input from the host environment in blocks rather than on a character-by-character basis. This is called buffering.
If you are writing programs that do interactive input and output using streams, you need to understand how buffering works when you design the user interface to your program. Otherwise, you might find that output (such as progress or prompt messages) doesn't appear when you intended it to, or other unexpected behavior.
This section deals only with controlling when characters are transmitted between the stream and the file or device, and not with how things like echoing, flow control, and the like are handled on specific classes of devices. For information on common control operations on terminal devices, see section Low-Level Terminal Interface.
You can bypass the stream buffering facilities altogether by using the low-level input and output functions that operate on file descriptors instead. See section Low-Level Input/Output.
There are three different kinds of buffering strategies:
Newly opened streams are normally fully buffered, with one exception: a stream connected to an interactive device such as a terminal is initially line buffered. See section Controlling Which Kind of Buffering, for information on how to select a different kind of buffering. Usually the automatic selection gives you the most convenient kind of buffering for the file or device you open.
The use of line buffering for interactive devices implies that output
messages ending in a newline will appear immediately--which is usually
what you want. Output that doesn't end in a newline might or might not
show up immediately, so if you want them to appear immediately, you
should flush buffered output explicitly with fflush, as described
in section Flushing Buffers.
Flushing output on a buffered stream means transmitting all accumulated characters to the file. There are many circumstances when buffered output on a stream is flushed automatically:
exit.
See section Normal Termination.
If you want to flush the buffered output at another time, call
fflush, which is declared in the header file `stdio.h'.
fflush causes buffered output on all open output streams
to be flushed.
This function returns EOF if a write error occurs, or zero
otherwise.
Compatibility Note: Some brain-damaged operating systems have been known to be so thoroughly fixated on line-oriented input and output that flushing a line buffered stream causes a newline to be written! Fortunately, this "feature" seems to be becoming less common. You do not need to worry about this in the GNU system.
After opening a stream (but before any other operations have been
performed on it), you can explicitly specify what kind of buffering you
want it to have using the setvbuf function.
The facilities listed in this section are declared in the header file `stdio.h'.
_IOFBF
(for full buffering), _IOLBF (for line buffering), or
_IONBF (for unbuffered input/output).
If you specify a null pointer as the buf argument, then setvbuf
allocates a buffer itself using malloc. This buffer will be freed
when you close the stream.
Otherwise, buf should be a character array that can hold at least
size characters. You should not free the space for this array as
long as the stream remains open and this array remains its buffer. You
should usually either allocate it statically, or malloc
(see section Unconstrained Allocation) the buffer. Using an automatic array
is not a good idea unless you close the file before exiting the block
that declares the array.
While the array remains a stream buffer, the stream I/O functions will use the buffer for their internal purposes. You shouldn't try to access the values in the array directly while the stream is using it for buffering.
The setvbuf function returns zero on success, or a nonzero value
if the value of mode is not valid or if the request could not
be honored.
setvbuf function to
specify that the stream should be fully buffered.
setvbuf function to
specify that the stream should be line buffered.
setvbuf function to
specify that the stream should be unbuffered.
setvbuf. This value is
guaranteed to be at least 256.
The value of BUFSIZ is chosen on each system so as to make stream
I/O efficient. So it is a good idea to use BUFSIZ as the size
for the buffer when you call setvbuf.
Actually, you can get an even better value to use for the buffer size
by means of the fstat system call: it is found in the
st_blksize field of the file attributes. See section What the File Attribute Values Mean.
Sometimes people also use BUFSIZ as the allocation size of
buffers used for related purposes, such as strings used to receive a
line of input with fgets (see section Character Input). There is no
particular reason to use BUFSIZ for this instead of any other
integer, except that it might lead to doing I/O in chunks of an
efficient size.
setvbuf with a mode argument of
_IONBF. Otherwise, it is equivalent to calling setvbuf
with buf, and a mode of _IOFBF and a size
argument of BUFSIZ.
The setbuf function is provided for compatibility with old code;
use setvbuf in all new programs.
This function is provided for compatibility with old BSD code. Use
setvbuf instead.
This function is provided for compatibility with old BSD code. Use
setvbuf instead.
The GNU library provides ways for you to define additional kinds of streams that do not necessarily correspond to an open file.
One such type of stream takes input from or writes output to a string.
These kinds of streams are used internally to implement the
sprintf and sscanf functions. You can also create such a
stream explicitly, using the functions described in section String Streams.
More generally, you can define streams that do input/output to arbitrary objects using functions supplied by your program. This protocol is discussed in section Programming Your Own Custom Streams.
Portability Note: The facilities described in this section are specific to GNU. Other systems or C implementations might or might not provide equivalent functionality.
The fmemopen and open_memstream functions allow you to do
I/O to a string or memory buffer. These facilities are declared in
`stdio.h'.
If you specify a null pointer as the buf argument, fmemopen
dynamically allocates (as with malloc; see section Unconstrained Allocation) an array size bytes long. This is really only useful
if you are going to write things to the buffer and then read them back
in again, because you have no way of actually getting a pointer to the
buffer (for this, try open_memstream, below). The buffer is
freed when the stream is open.
The argument opentype is the same as in fopen
(See section Opening Streams). If the opentype specifies
append mode, then the initial file position is set to the first null
character in the buffer. Otherwise the initial file position is at the
beginning of the buffer.
When a stream open for writing is flushed or closed, a null character (zero byte) is written at the end of the buffer if it fits. You should add an extra byte to the size argument to account for this. Attempts to write more than size bytes to the buffer result in an error.
For a stream open for reading, null characters (zero bytes) in the buffer do not count as "end of file". Read operations indicate end of file only when the file position advances past size bytes. So, if you want to read characters from a null-terminated string, you should supply the length of the string as the size argument.
Here is an example of using fmemopen to create a stream for
reading from a string:
#include <stdio.h>
static char buffer[] = "foobar";
int
main (void)
{
int ch;
FILE *stream;
stream = fmemopen (buffer, strlen (buffer), "r");
while ((ch = fgetc (stream)) != EOF)
printf ("Got %c\n", ch);
fclose (stream);
return 0;
}
This program produces the following output:
Got f Got o Got o Got b Got a Got r
malloc; see section Unconstrained Allocation) and grown as necessary.
When the stream is closed with fclose or flushed with
fflush, the locations ptr and sizeloc are updated to
contain the pointer to the buffer and its size. The values thus stored
remain valid only as long as no further output on the stream takes
place. If you do more output, you must flush the stream again to store
new values before you use them again.
A null character is written at the end of the buffer. This null character is not included in the size value stored at sizeloc.
You can move the stream's file position with fseek (see section File Positioning). Moving the file position past the end of the data
already written fills the intervening space with zeroes.
Here is an example of using open_memstream:
#include <stdio.h>
int
main (void)
{
char *bp;
size_t size;
FILE *stream;
stream = open_memstream (&bp, &size);
fprintf (stream, "hello");
fflush (stream);
printf ("buf = `%s', size = %d\n", bp, size);
fprintf (stream, ", world");
fclose (stream);
printf ("buf = `%s', size = %d\n", bp, size);
return 0;
}
This program produces the following output:
buf = `hello', size = 5 buf = `hello, world', size = 12
You can open an output stream that puts it data in an obstack. See section Obstacks.
Calling fflush on this stream updates the current size of the
object to match the amount of data that has been written. After a call
to fflush, you can examine the object temporarily.
You can move the file position of an obstack stream with fseek
(see section File Positioning). Moving the file position past the end of
the data written fills the intervening space with zeros.
To make the object permanent, update the obstack with fflush, and
then use obstack_finish to finalize the object and get its address.
The following write to the stream starts a new object in the obstack,
and later writes add to that object until you do another fflush
and obstack_finish.
But how do you find out how long the object is? You can get the length
in bytes by calling obstack_object_size (see section Status of an Obstack), or you can null-terminate the object like this:
obstack_1grow (obstack, 0);
Whichever one you do, you must do it before calling
obstack_finish. (You can do both if you wish.)
Here is a sample function that uses open_obstack_stream:
char *
make_message_string (const char *a, int b)
{
FILE *stream = open_obstack_stream (&message_obstack);
output_task (stream);
fprintf (stream, ": ");
fprintf (stream, a, b);
fprintf (stream, "\n");
fclose (stream);
obstack_1grow (&message_obstack, 0);
return obstack_finish (&message_obstack);
}
This section describes how you can make a stream that gets input from an arbitrary data source or writes output to an arbitrary data sink programmed by you. We call these custom streams.
Inside every custom stream is a special object called the cookie.
This is an object supplied by you which records where to fetch or store
the data read or written. It is up to you to define a data type to use
for the cookie. The stream functions in the library never refer
directly to its contents, and they don't even know what the type is;
they record its address with type void *.
To implement a custom stream, you must specify how to fetch or store the data in the specified place. You do this by defining hook functions to read, write, change "file position", and close the stream. All four of these functions will be passed the stream's cookie so they can tell where to fetch or store the data. The library functions don't know what's inside the cookie, but your functions will know.
When you create a custom stream, you must specify the cookie pointer,
and also the four hook functions stored in a structure of type
cookie_io_functions_t.
These facilities are declared in `stdio.h'.
cookie_read_function_t *read
EOF.
cookie_write_function_t *write
cookie_seek_function_t *seek
fseek on this stream can only seek to locations within the
buffer; any attempt to seek outside the buffer will return an
ESPIPE error.
cookie_close_function_t *close
fopen;
see section Opening Streams. (But note that the "truncate on
open" option is ignored.) The new stream is fully buffered.
The fopencookie function returns the newly created stream, or a null
pointer in case of an error.
Here are more details on how you should define the four hook functions that a custom stream needs.
You should define the function to read data from the cookie as:
ssize_t reader (void *cookie, void *buffer, size_t size)
This is very similar to the read function; see section Input and Output Primitives. Your function should transfer up to size bytes into
the buffer, and return the number of bytes read, or zero to
indicate end-of-file. You can return a value of -1 to indicate
an error.
You should define the function to write data to the cookie as:
ssize_t writer (void *cookie, const void *buffer, size_t size)
This is very similar to the write function; see section Input and Output Primitives. Your function should transfer up to size bytes from
the buffer, and return the number of bytes written. You can return a
value of -1 to indicate an error.
You should define the function to perform seek operations on the cookie as:
int seeker (void *cookie, fpos_t *position, int whence)
For this function, the position and whence arguments are
interpreted as for fgetpos; see section Portable File-Position Functions. In
the GNU library, fpos_t is equivalent to off_t or
long int, and simply represents the number of bytes from the
beginning of the file.
After doing the seek operation, your function should store the resulting
file position relative to the beginning of the file in position.
Your function should return a value of 0 on success and -1
to indicate an error.
You should define the function to do cleanup operations on the cookie appropriate for closing the stream as:
int cleaner (void *cookie)
Your function should return -1 to indicate an error, and 0
otherwise.
This chapter describes functions for performing low-level input/output operations on file descriptors. These functions include the primitives for the higher-level I/O functions described in section Input/Output on Streams, as well as functions for performing low-level control operations for which there are no equivalents on streams.
Stream-level I/O is more flexible and usually more convenient; therefore, programmers generally use the descriptor-level functions only when necessary. These are some of the usual reasons:
fileno to get the descriptor
corresponding to a stream.)
This section describes the primitives for opening and closing files
using file descriptors. The open and creat functions are
declared in the header file `fcntl.h', while close is
declared in `unistd.h'.
open function creates and returns a new file descriptor
for the file named by filename. Initially, the file position
indicator for the file is at the beginning of the file. The argument
mode is used only when a file is created, but it doesn't hurt
to supply the argument in any case.
The flags argument controls how the file is to be opened. This is a bit mask; you create the value by the bitwise OR of the appropriate parameters (using the `|' operator in C). See section File Status Flags, for the parameters available.
The normal return value from open is a non-negative integer file
descriptor. In the case of an error, a value of -1 is returned
instead. In addition to the usual file name errors (see section File Name Errors), the following errno error conditions are defined
for this function:
EACCES
EEXIST
O_CREAT and O_EXCL are set, and the named file already
exists.
EINTR
open operation was interrupted by a signal.
See section Primitives Interrupted by Signals.
EISDIR
EMFILE
RLIMIT_NOFILE resource limit; see section Limiting Resource Usage.
ENFILE
ENOENT
O_CREAT is not specified.
ENOSPC
ENXIO
O_NONBLOCK and O_WRONLY are both set in the flags
argument, the file named by filename is a FIFO (see section Pipes and FIFOs), and no process has the file open for reading.
EROFS
O_WRONLY,
O_RDWR, and O_TRUNC are set in the flags argument,
or O_CREAT is set and the file does not already exist.
The open function is the underlying primitive for the fopen
and freopen functions, that create streams.
creat (filename, mode)
is equivalent to:
open (filename, O_WRONLY | O_CREAT | O_TRUNC, mode)
close closes the file descriptor filedes.
Closing a file has the following consequences:
The normal return value from close is 0; a value of -1
is returned in case of failure. The following errno error
conditions are defined for this function:
EBADF
EINTR
close call was interrupted by a signal.
See section Primitives Interrupted by Signals.
Here is an example of how to handle EINTR properly:
TEMP_FAILURE_RETRY (close (desc));
ENOSPC
EIO
EDQUOT
write can sometimes
not be detected until close. See section Input and Output Primitives, for details
on their meaning.
To close a stream, call fclose (see section Closing Streams) instead
of trying to close its underlying file descriptor with close.
This flushes any buffered output and updates the stream object to
indicate that it is closed.
This section describes the functions for performing primitive input and
output operations on file descriptors: read, write, and
lseek. These functions are declared in the header file
`unistd.h'.
size_t,
but must be a signed type.
read function reads up to size bytes from the file
with descriptor filedes, storing the results in the buffer.
(This is not necessarily a character string and there is no terminating
null character added.)
The return value is the number of bytes actually read. This might be less than size; for example, if there aren't that many bytes left in the file or if there aren't that many bytes immediately available. The exact behavior depends on what kind of file it is. Note that reading less than size bytes is not an error.
A value of zero indicates end-of-file (except if the value of the
size argument is also zero). This is not considered an error.
If you keep calling read while at end-of-file, it will keep
returning zero and doing nothing else.
If read returns at least one character, there is no way you can
tell whether end-of-file was reached. But if you did reach the end, the
next read will return zero.
In case of an error, read returns -1. The following
errno error conditions are defined for this function:
EAGAIN
read waits for
some input. But if the O_NONBLOCK flag is set for the file
(see section File Status Flags), read returns immediately without
reading any data, and reports this error.
Compatibility Note: Most versions of BSD Unix use a different
error code for this: EWOULDBLOCK. In the GNU library,
EWOULDBLOCK is an alias for EAGAIN, so it doesn't matter
which name you use.
On some systems, reading a large amount of data from a character special
file can also fail with EAGAIN if the kernel cannot find enough
physical memory to lock down the user's pages. This is limited to
devices that transfer with direct memory access into the user's memory,
which means it does not include terminals, since they always use
separate buffers inside the kernel. This problem never happens in the
GNU system.
Any condition that could result in EAGAIN can instead result in a
successful read which returns fewer bytes than requested.
Calling read again immediately would result in EAGAIN.
EBADF
EINTR
read was interrupted by a signal while it was waiting for input.
See section Primitives Interrupted by Signals. A signal will not necessary cause
read to return EINTR; it may instead result in a
successful read which returns fewer bytes than requested.
EIO
EIO also occurs when a background process tries to read from the
controlling terminal, and the normal action of stopping the process by
sending it a SIGTTIN signal isn't working. This might happen if
signal is being blocked or ignored, or because the process group is
orphaned. See section Job Control, for more information about job control,
and section Signal Handling, for information about signals.
The read function is the underlying primitive for all of the
functions that read from streams, such as fgetc.
write function writes up to size bytes from
buffer to the file with descriptor filedes. The data in
buffer is not necessarily a character string and a null character is
output like any other character.
The return value is the number of bytes actually written. This may be
size, but can always be smaller. Your program should always call
write in a loop, iterating until all the data is written.
Once write returns, the data is enqueued to be written and can be
read back right away, but it is not necessarily written out to permanent
storage immediately. You can use fsync when you need to be sure
your data has been permanently stored before continuing. (It is more
efficient for the system to batch up consecutive writes and do them all
at once when convenient. Normally they will always be written to disk
within a minute or less.)
You can use the O_FSYNC open mode to make write always
store the data to disk before returning; see section I/O Operating Modes.
In the case of an error, write returns -1. The following
errno error conditions are defined for this function:
EAGAIN
write blocks until the write operation is complete.
But if the O_NONBLOCK flag is set for the file (see section Control Operations on Files), it returns immediately without writing any data, and
reports this error. An example of a situation that might cause the
process to block on output is writing to a terminal device that supports
flow control, where output has been suspended by receipt of a STOP
character.
Compatibility Note: Most versions of BSD Unix use a different
error code for this: EWOULDBLOCK. In the GNU library,
EWOULDBLOCK is an alias for EAGAIN, so it doesn't matter
which name you use.
On some systems, writing a large amount of data from a character special
file can also fail with EAGAIN if the kernel cannot find enough
physical memory to lock down the user's pages. This is limited to
devices that transfer with direct memory access into the user's memory,
which means it does not include terminals, since they always use
separate buffers inside the kernel. This problem does not arise in the
GNU system.
EBADF
EFBIG
EINTR
write operation was interrupted by a signal while it was
blocked waiting for completion. A signal will not necessary cause
write to return EINTR; it may instead result in a
successful write which writes fewer bytes than requested.
See section Primitives Interrupted by Signals.
EIO
ENOSPC
EPIPE
SIGPIPE
signal is also sent to the process; see section Signal Handling.
Unless you have arranged to prevent EINTR failures, you should
check errno after each failing call to write, and if the
error was EINTR, you should simply repeat the call.
See section Primitives Interrupted by Signals. The easy way to do this is with the
macro TEMP_FAILURE_RETRY, as follows:
nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count));
The write function is the underlying primitive for all of the
functions that write to streams, such as fputc.
Just as you can set the file position of a stream with fseek, you
can set the file position of a descriptor with lseek. This
specifies the position in the file for the next read or
write operation. See section File Positioning, for more information
on the file position and what it means.
To read the current file position value from a descriptor, use
lseek (desc, 0, SEEK_CUR).
lseek function is used to change the file position of the
file with descriptor filedes.
The whence argument specifies how the offset should be
interpreted in the same way as for the fseek function, and must be
one of the symbolic constants SEEK_SET, SEEK_CUR, or
SEEK_END.
SEEK_SET
SEEK_CUR
SEEK_END
lseek is normally the resulting file
position, measured in bytes from the beginning of the file.
You can use this feature together with SEEK_CUR to read the
current file position.
If you want to append to the file, setting the file position to the
current end of file with SEEK_END is not sufficient. Another
process may write more data after you seek but before you write,
extending the file so the position you write onto clobbers their data.
Instead, use the O_APPEND operating mode; see section I/O Operating Modes.
You can set the file position past the current end of the file. This
does not by itself make the file longer; lseek never changes the
file. But subsequent output at that position will extend the file.
Characters between the previous end of file and the new position are
filled with zeros. Extending the file in this way can create a
"hole": the blocks of zeros are not actually allocated on disk, so the
file takes up less space than it appears so; it is then called a
"sparse file".
If the file position cannot be changed, or the operation is in some way
invalid, lseek returns a value of -1. The following
errno error conditions are defined for this function:
EBADF
EINVAL
ESPIPE
ESPIPE if the object is not seekable.)
lseek function is the underlying primitive for the
fseek, ftell and rewind functions, which operate on
streams instead of file descriptors.
dup.
Descriptors that come from separate calls to open have independent
file positions; using lseek on one descriptor has no effect on the
other. For example,
{
int d1, d2;
char buf[4];
d1 = open ("foo", O_RDONLY);
d2 = open ("foo", O_RDONLY);
lseek (d1, 1024, SEEK_SET);
read (d2, buf, 4);
}
will read the first four characters of the file `foo'. (The
error-checking code necessary for a real program has been omitted here
for brevity.)
By contrast, descriptors made by duplication share a common file
position with the original descriptor that was duplicated. Anything
which alters the file position of one of the duplicates, including
reading or writing data, affects all of them alike. Thus, for example,
{
int d1, d2, d3;
char buf1[4], buf2[4];
d1 = open ("foo", O_RDONLY);
d2 = dup (d1);
d3 = dup (d2);
lseek (d3, 1024, SEEK_SET);
read (d1, buf1, 4);
read (d2, buf2, 4);
}
will read four characters starting with the 1024'th character of
`foo', and then four more characters starting with the 1028'th
character.
fpos_t or long int.
L_SET
SEEK_SET.
L_INCR
SEEK_CUR.
L_XTND
SEEK_END.
Given an open file descriptor, you can create a stream for it with the
fdopen function. You can get the underlying file descriptor for
an existing stream with the fileno function. These functions are
declared in the header file `stdio.h'.
fdopen function returns a new stream for the file descriptor
filedes.
The opentype argument is interpreted in the same way as for the
fopen function (see section Opening Streams), except that
the `b' option is not permitted; this is because GNU makes no
distinction between text and binary files. Also, "w" and
"w+" do not cause truncation of the file; these have affect only
when opening a file, and in this case the file has already been opened.
You must make sure that the opentype argument matches the actual
mode of the open file descriptor.
The return value is the new stream. If the stream cannot be created (for example, if the modes for the file indicated by the file descriptor do not permit the access specified by the opentype argument), a null pointer is returned instead.
In some other systems, fdopen may fail to detect that the modes
for file descriptor do not permit the access specified by
opentype. The GNU C library always checks for this.
For an example showing the use of the fdopen function,
see section Creating a Pipe.
fileno returns -1.
There are also symbolic constants defined in `unistd.h' for the
file descriptors belonging to the standard streams stdin,
stdout, and stderr; see section Standard Streams.
STDIN_FILENO
0, which is the file descriptor for
standard input.
STDOUT_FILENO
1, which is the file descriptor for
standard output.
STDERR_FILENO
2, which is the file descriptor for
standard error output.
You can have multiple file descriptors and streams (let's call both streams and descriptors "channels" for short) connected to the same file, but you must take care to avoid confusion between channels. There are two cases to consider: linked channels that share a single file position value, and independent channels that have their own file positions.
It's best to use just one channel in your program for actual data
transfer to any given file, except when all the access is for input.
For example, if you open a pipe (something you can only do at the file
descriptor level), either do all I/O with the descriptor, or construct a
stream from the descriptor with fdopen and then do all I/O with
the stream.
Channels that come from a single opening share the same file position;
we call them linked channels. Linked channels result when you
make a stream from a descriptor using fdopen, when you get a
descriptor from a stream with fileno, when you copy a descriptor
with dup or dup2, and when descriptors are inherited
during fork. For files that don't support random access, such as
terminals and pipes, all channels are effectively linked. On
random-access files, all append-type output streams are effectively
linked to each other.
If you have been using a stream for I/O, and you want to do I/O using another channel (either a stream or a descriptor) that is linked to it, you must first clean up the stream that you have been using. See section Cleaning Streams.
Terminating a process, or executing a new program in the process, destroys all the streams in the process. If descriptors linked to these streams persist in other processes, their file positions become undefined as a result. To prevent this, you must clean up the streams before destroying them.
When you open channels (streams or descriptors) separately on a seekable file, each channel has its own file position. These are called independent channels.
The system handles each channel independently. Most of the time, this is quite predictable and natural (especially for input): each channel can read or write sequentially at its own place in the file. However, if some of the channels are streams, you must take these precautions:
If you do output to one channel at the end of the file, this will certainly leave the other independent channels positioned somewhere before the new end. You cannot reliably set their file positions to the new end of file before writing, because the file can always be extended by another process between when you set the file position and when you write the data. Instead, use an append-type descriptor or stream; they always output at the current end of the file. In order to make the end-of-file position accurate, you must clean the output channel you were using, if it is a stream.
It's impossible for two channels to have separate file pointers for a file that doesn't support random access. Thus, channels for reading or writing such files are always linked, never independent. Append-type channels are also always linked. For these channels, follow the rules for linked channels; see section Linked Channels.
On the GNU system, you can clean up any stream with fclean:
On other systems, you can use fflush to clean a stream in most
cases.
You can skip the fclean or fflush if you know the stream
is already clean. A stream is clean whenever its buffer is empty. For
example, an unbuffered stream is always clean. An input stream that is
at end-of-file is clean. A line-buffered stream is clean when the last
character output was a newline.
There is one case in which cleaning a stream is impossible on most
systems. This is when the stream is doing input from a file that is not
random-access. Such streams typically read ahead, and when the file is
not random access, there is no way to give back the excess data already
read. When an input stream reads from a random-access file,
fflush does clean the stream, but leaves the file pointer at an
unpredictable place; you must set the file pointer before doing any
further I/O. On the GNU system, using fclean avoids both of
these problems.
Closing an output-only stream also does fflush, so this is a
valid way of cleaning an output stream. On the GNU system, closing an
input stream does fclean.
You need not clean a stream before using its descriptor for control operations such as setting terminal modes; these operations don't affect the file position and are not affected by it. You can use any descriptor for these operations, and all channels are affected simultaneously. However, text already "output" to a stream but still buffered by the stream will be subject to the new terminal modes when subsequently flushed. To make sure "past" output is covered by the terminal settings that were in effect at the time, flush the output streams for that terminal before setting the modes. See section Terminal Modes.
Sometimes a program needs to accept input on multiple input channels whenever input arrives. For example, some workstations may have devices such as a digitizing tablet, function button box, or dial box that are connected via normal asynchronous serial interfaces; good user interface style requires responding immediately to input on any device. Another example is a program that acts as a server to several other processes via pipes or sockets.
You cannot normally use read for this purpose, because this
blocks the program until input is available on one particular file
descriptor; input on other channels won't wake it up. You could set
nonblocking mode and poll each file descriptor in turn, but this is very
inefficient.
A better solution is to use the select function. This blocks the
program until input or output is ready on a specified set of file
descriptors, or until a timer expires, whichever comes first. This
facility is declared in the header file `sys/types.h'.
In the case of a server socket (see section Listening for Connections), we say that
"input" is available when there are pending connections that could be
accepted (see section Accepting Connections). accept for server
sockets blocks and interacts with select just as read does
for normal input.
The file descriptor sets for the select function are specified
as fd_set objects. Here is the description of the data type
and some macros for manipulating these objects.
fd_set data type represents file descriptor sets for the
select function. It is actually a bit array.
fd_set object can hold information about. On systems with a
fixed maximum number, FD_SETSIZE is at least that number. On
some systems, including GNU, there is no absolute limit on the number of
descriptors open, but this macro still has a constant value which
controls the number of bits in an fd_set; if you get a file
descriptor with a value as high as FD_SETSIZE, you cannot put
that descriptor into an fd_set.
Next, here is the description of the select function itself.
select function blocks the calling process until there is
activity on any of the specified sets of file descriptors, or until the
timeout period has expired.
The file descriptors specified by the read-fds argument are checked to see if they are ready for reading; the write-fds file descriptors are checked to see if they are ready for writing; and the except-fds file descriptors are checked for exceptional conditions. You can pass a null pointer for any of these arguments if you are not interested in checking for that kind of condition.
A file descriptor is considered ready for reading if it is at end of
file. A server socket is considered ready for reading if there is a
pending connection which can be accepted with accept;
see section Accepting Connections. A client socket is ready for writing when
its connection is fully established; see section Making a Connection.
"Exceptional conditions" does not mean errors--errors are reported immediately when an erroneous system call is executed, and do not constitute a state of the descriptor. Rather, they include conditions such as the presence of an urgent message on a socket. (See section Sockets, for information on urgent messages.)
The select function checks only the first nfds file
descriptors. The usual thing is to pass FD_SETSIZE as the value
of this argument.
The timeout specifies the maximum time to wait. If you pass a
null pointer for this argument, it means to block indefinitely until one
of the file descriptors is ready. Otherwise, you should provide the
time in struct timeval format; see section High-Resolution Calendar. Specify zero as the time (a struct timeval containing
all zeros) if you want to find out which descriptors are ready without
waiting if none are ready.
The normal return value from select is the total number of ready file
descriptors in all of the sets. Each of the argument sets is overwritten
with information about the descriptors that are ready for the corresponding
operation. Thus, to see if a particular descriptor desc has input,
use FD_ISSET (desc, read-fds) after select returns.
If select returns because the timeout period expires, it returns
a value of zero.
Any signal will cause select to return immediately. So if your
program uses signals, you can't rely on select to keep waiting
for the full time specified. If you want to be sure of waiting for a
particular amount of time, you must check for EINTR and repeat
the select with a newly calculated timeout based on the current
time. See the example below. See also section Primitives Interrupted by Signals.
If an error occurs, select returns -1 and does not modify
the argument file descriptor sets. The following errno error
conditions are defined for this function:
EBADF
EINTR
EINVAL
Portability Note: The select function is a BSD Unix
feature.
Here is an example showing how you can use select to establish a
timeout period for reading from a file descriptor. The input_timeout
function blocks the calling process until input is available on the
file descriptor, or until the timeout period expires.
#include <stdio.h>
#include <unistd.h>
#include <sys/types.h>
#include <sys/time.h>
int
input_timeout (int filedes, unsigned int seconds)
{
fd_set set;
struct timeval timeout;
/* Initialize the file descriptor set. */
FD_ZERO (&set);
FD_SET (filedes, &set);
/* Initialize the timeout data structure. */
timeout.tv_sec = seconds;
timeout.tv_usec = 0;
/* select returns 0 if timeout, 1 if input available, -1 if error. */
return TEMP_FAILURE_RETRY (select (FD_SETSIZE,
&set, NULL, NULL,
&timeout));
}
int
main (void)
{
fprintf (stderr, "select returned %d.\n",
input_timeout (STDIN_FILENO, 5));
return 0;
}
There is another example showing the use of select to multiplex
input from multiple sockets in section Byte Stream Connection Server Example.
This section describes how you can perform various other operations on
file descriptors, such as inquiring about or setting flags describing
the status of the file descriptor, manipulating record locks, and the
like. All of these operations are performed by the function fcntl.
The second argument to the fcntl function is a command that
specifies which operation to perform. The function and macros that name
various flags that are used with it are declared in the header file
`fcntl.h'. Many of these flags are also used by the open
function; see section Opening and Closing Files.
fcntl function performs the operation specified by
command on the file descriptor filedes. Some commands
require additional arguments to be supplied. These additional arguments
and the return value and error conditions are given in the detailed
descriptions of the individual commands.
Briefly, here is a list of what the various commands are.
F_DUPFD
F_GETFD
F_SETFD
F_GETFL
F_SETFL
F_GETLK
F_SETLK
F_SETLKW
F_SETLK, but wait for completion. See section File Locks.
F_GETOWN
SIGIO signals.
See section Interrupt-Driven Input.
F_SETOWN
SIGIO signals.
See section Interrupt-Driven Input.
You can duplicate a file descriptor, or allocate another file descriptor that refers to the same open file as the original. Duplicate descriptors share one file position and one set of file status flags (see section File Status Flags), but each has its own set of file descriptor flags (see section File Descriptor Flags).
The major use of duplicating a file descriptor is to implement redirection of input or output: that is, to change the file or pipe that a particular file descriptor corresponds to.
You can perform this operation using the fcntl function with the
F_DUPFD command, but there are also convenient functions
dup and dup2 for duplicating descriptors.
The fcntl function and flags are declared in `fcntl.h',
while prototypes for dup and dup2 are in the header file
`unistd.h'.
fcntl (old, F_DUPFD, 0).
If old is an invalid descriptor, then dup2 does nothing; it
does not close new. Otherwise, the new duplicate of old
replaces any previous meaning of descriptor new, as if new
were closed first.
If old and new are different numbers, and old is a
valid descriptor number, then dup2 is equivalent to:
close (new); fcntl (old, F_DUPFD, new)
However, dup2 does this atomically; there is no instant in the
middle of calling dup2 at which new is closed and not yet a
duplicate of old.
fcntl, to
copy the file descriptor given as the first argument.
The form of the call in this case is:
fcntl (old, F_DUPFD, next-filedes)
The next-filedes argument is of type int and specifies that
the file descriptor returned should be the next available one greater
than or equal to this value.
The return value from fcntl with this command is normally the value
of the new file descriptor. A return value of -1 indicates an
error. The following errno error conditions are defined for
this command:
EBADF
EINVAL
EMFILE
RLIMIT_NOFILE limit.
ENFILE is not a possible error code for dup2 because
dup2 does not create a new opening of a file; duplicate
descriptors do not count toward the limit which ENFILE
indicates. EMFILE is possible because it refers to the limit on
distinct descriptor numbers in use in one process.
Here is an example showing how to use dup2 to do redirection.
Typically, redirection of the standard streams (like stdin) is
done by a shell or shell-like program before calling one of the
exec functions (see section Executing a File) to execute a new
program in a child process. When the new program is executed, it
creates and initializes the standard streams to point to the
corresponding file descriptors, before its main function is
invoked.
So, to redirect standard input to a file, the shell could do something like:
pid = fork ();
if (pid == 0)
{
char *filename;
char *program;
int file;
...
file = TEMP_FAILURE_RETRY (open (filename, O_RDONLY));
dup2 (file, STDIN_FILENO);
TEMP_FAILURE_RETRY (close (file));
execv (program, NULL);
}
There is also a more detailed example showing how to implement redirection in the context of a pipeline of processes in section Launching Jobs.
File descriptor flags are miscellaneous attributes of a file descriptor. These flags are associated with particular file descriptors, so that if you have created duplicate file descriptors from a single opening of a file, each descriptor has its own set of flags.
Currently there is just one file descriptor flag: FD_CLOEXEC,
which causes the descriptor to be closed if you use any of the
exec... functions (see section Executing a File).
The symbols in this section are defined in the header file `fcntl.h'.
fcntl, to
specify that it should return the file descriptor flags associated
with the filedes argument.
The normal return value from fcntl with this command is a
nonnegative number which can be interpreted as the bitwise OR of the
individual flags (except that currently there is only one flag to use).
In case of an error, fcntl returns -1. The following
errno error conditions are defined for this command:
EBADF
fcntl, to
specify that it should set the file descriptor flags associated with the
filedes argument. This requires a third int argument to
specify the new flags, so the form of the call is:
fcntl (filedes, F_SETFD, new-flags)
The normal return value from fcntl with this command is an
unspecified value other than -1, which indicates an error.
The flags and error conditions are the same as for the F_GETFD
command.
The following macro is defined for use as a file descriptor flag with
the fcntl function. The value is an integer constant usable
as a bit mask value.
exec function is invoked; see section Executing a File. When
a file descriptor is allocated (as with open or dup),
this bit is initially cleared on the new file descriptor, meaning that
descriptor will survive into the new program after exec.
If you want to modify the file descriptor flags, you should get the
current flags with F_GETFD and modify the value. Don't assume
that the flags listed here are the only ones that are implemented; your
program may be run years from now and more flags may exist then. For
example, here is a function to set or clear the flag FD_CLOEXEC
without altering any other flags:
/* Set theFD_CLOEXECflag of desc if value is nonzero, or clear the flag if value is 0. Return 0 on success, or -1 on error witherrnoset. */ int set_cloexec_flag (int desc, int value) { int oldflags = fcntl (desc, F_GETFD, 0); /* If reading the flags failed, return error indication now. if (oldflags < 0) return oldflags; /* Set just the flag we want to set. */ if (value != 0) oldflags |= FD_CLOEXEC; else oldflags &= ~FD_CLOEXEC; /* Store modified flag word in the descriptor. */ return fcntl (desc, F_SETFD, oldflags); }
File status flags are used to specify attributes of the opening of a
file. Unlike the file descriptor flags discussed in section File Descriptor Flags, the file status flags are shared by duplicated file descriptors
resulting from a single opening of the file. The file status flags are
specified with the flags argument to open;
see section Opening and Closing Files.
File status flags fall into three categories, which are described in the following sections.
open and are
returned by fcntl, but cannot be changed.
open will do.
These flags are not preserved after the open call.
read and
write are done. They are set by open, and can be fetched or
changed with fcntl.
The symbols in this section are defined in the header file `fcntl.h'.
The file access modes allow a file descriptor to be used for reading, writing, or both. (In the GNU system, they can also allow none of these, and allow execution of the file as a program.) The access modes are chosen when the file is opened, and never change.
In the GNU system (and not in other systems), O_RDONLY and
O_WRONLY are independent bits that can be bitwise-ORed together,
and it is valid for either bit to be set or clear. This means that
O_RDWR is the same as O_RDONLY|O_WRONLY. A file access
mode of zero is permissible; it allows no operations that do input or
output to the file, but does allow other operations such as
fchmod. On the GNU system, since "read-only" or "write-only"
is a misnomer, `fcntl.h' defines additional names for the file
access modes. These names are preferred when writing GNU-specific code.
But most programs will want to be portable to other POSIX.1 systems and
should use the POSIX.1 names above instead.
O_RDWR; only defined on GNU.
O_WRONLY; only defined on GNU.
To determine the file access mode with fcntl, you must extract
the access mode bits from the retrieved file status flags. In the GNU
system, you can just test the O_READ and O_WRITE bits in
the flags word. But in other POSIX.1 systems, reading and writing
access modes are not stored as distinct bit flags. The portable way to
extract the file access mode bits is with O_ACCMODE.
O_RDONLY, O_WRONLY, or O_RDWR.
(In the GNU system it could also be zero, and it never includes the
O_EXEC bit.)
The open-time flags specify options affecting how open will behave.
These options are not preserved once the file is open. The exception to
this is O_NONBLOCK, which is also an I/O operating mode and so it
is saved. See section Opening and Closing Files, for how to call
open.
There are two sorts of options specified by open-time flags.
open looks up the
file name to locate the file, and whether the file can be created.
open will
perform on the file once it is open.
Here are the file name translation flags.
O_CREAT and O_EXCL are set, then open fails
if the specified file already exists. This is guaranteed to never
clobber an existing file.
open from blocking for a "long time" to open the
file. This is only meaningful for some kinds of files, usually devices
such as serial ports; when it is not meaningful, it is harmless and
ignored. Often opening a port to a modem blocks until the modem reports
carrier detection; if O_NONBLOCK is specified, open will
return immediately without a carrier.
Note that the O_NONBLOCK flag is overloaded as both an I/O operating
mode and a file name translation flag. This means that specifying
O_NONBLOCK in open also sets nonblocking I/O mode;
see section I/O Operating Modes. To open the file without blocking but do normal
I/O that blocks, you must call open with O_NONBLOCK set and
then call fcntl to turn the bit off.
In the GNU system and 4.4 BSD, opening a file never makes it the
controlling terminal and O_NOCTTY is zero. However, other
systems may use a nonzero value for O_NOCTTY and set the
controlling terminal when you open a file that is a terminal device; so
to be portable, use O_NOCTTY when it is important to avoid this.
The following three file name translation flags exist only in the GNU system.
fstat on the new file descriptor will
return the information returned by lstat on the link's name.)
The open-time action flags tell open to do additional operations
which are not really related to opening the file. The reason to do them
as part of open instead of in separate calls is that open
can do them atomically.
O_TRUNC. In
BSD and GNU you must have permission to write the file to truncate it,
but you need not open for write access.
This is the only open-time action flag specified by POSIX.1. There is
no good reason for truncation to be done by open, instead of by
calling ftruncate afterwards. The O_TRUNC flag existed in
Unix before ftruncate was invented, and is retained for backward
compatibility.
flock.
See section File Locks.
If O_CREAT is specified, the locking is done atomically when
creating the file. You are guaranteed that no other process will get
the lock on the new file first.
flock.
See section File Locks. This is atomic like O_SHLOCK.
The operating modes affect how input and output operations using a file
descriptor work. These flags are set by open and can be fetched
and changed with fcntl.
write operations write the data at the end of the file, extending
it, regardless of the current file position. This is the only reliable
way to append to a file. In append mode, you are guaranteed that the
data you write will always go to the current end of the file, regardless
of other processes writing to the file. Conversely, if you simply set
the file position to the end of file and write, then another process can
extend the file after you set the file position but before you write,
resulting in your data appearing someplace before the real end of file.
read requests on the file can return immediately with a failure
status if there is no input immediately available, instead of blocking.
Likewise, write requests can also return immediately with a
failure status if the output can't be written immediately.
Note that the O_NONBLOCK flag is overloaded as both an I/O
operating mode and a file name translation flag; see section Open-time Flags.
O_NONBLOCK, provided for
compatibility with BSD. It is not defined by the POSIX.1 standard.
The remaining operating modes are BSD and GNU extensions. They exist only on some systems. On other systems, these macros are not defined.
SIGIO
signals will be generated when input is available. See section Interrupt-Driven Input.
Asynchronous input mode is a BSD feature.
write call will make sure the data is reliably stored on disk before
returning.
Synchronous writing is a BSD feature.
O_FSYNC. They have the same value.
read will not update the access time of the
file. See section File Times. This is used by programs that do backups, so
that backing a file up does not count as reading it.
Only the owner of the file or the superuser may use this bit.
This is a GNU extension.
The fcntl function can fetch or change file status flags.
fcntl, to
read the file status flags for the open file with descriptor
filedes.
The normal return value from fcntl with this command is a
nonnegative number which can be interpreted as the bitwise OR of the
individual flags. Since the file access modes are not single-bit values,
you can mask off other bits in the returned flags with O_ACCMODE
to compare them.
In case of an error, fcntl returns -1. The following
errno error conditions are defined for this command:
EBADF
fcntl, to set
the file status flags for the open file corresponding to the
filedes argument. This command requires a third int
argument to specify the new flags, so the call looks like this:
fcntl (filedes, F_SETFL, new-flags)
You can't change the access mode for the file in this way; that is, whether the file descriptor was opened for reading or writing.
The normal return value from fcntl with this command is an
unspecified value other than -1, which indicates an error. The
error conditions are the same as for the F_GETFL command.
If you want to modify the file status flags, you should get the current
flags with F_GETFL and modify the value. Don't assume that the
flags listed here are the only ones that are implemented; your program
may be run years from now and more flags may exist then. For example,
here is a function to set or clear the flag O_NONBLOCK without
altering any other flags:
/* Set theO_NONBLOCKflag of desc if value is nonzero, or clear the flag if value is 0. Return 0 on success, or -1 on error witherrnoset. */ int set_nonblock_flag (int desc, int value) { int oldflags = fcntl (desc, F_GETFL, 0); /* If reading the flags failed, return error indication now. */ if (oldflags == -1) return -1; /* Set just the flag we want to set. */ if (value != 0) oldflags |= O_NONBLOCK; else oldflags &= ~O_NONBLOCK; /* Store modified flag word in the descriptor. */ return fcntl (desc, F_SETFL, oldflags); }
The remaining fcntl commands are used to support record
locking, which permits multiple cooperating programs to prevent each
other from simultaneously accessing parts of a file in error-prone
ways.
An exclusive or write lock gives a process exclusive access for writing to the specified part of the file. While a write lock is in place, no other process can lock that part of the file.
A shared or read lock prohibits any other process from requesting a write lock on the specified part of the file. However, other processes can request read locks.
The read and write functions do not actually check to see
whether there are any locks in place. If you want to implement a
locking protocol for a file shared by multiple processes, your application
must do explicit fcntl calls to request and clear locks at the
appropriate points.
Locks are associated with processes. A process can only have one kind
of lock set for each byte of a given file. When any file descriptor for
that file is closed by the process, all of the locks that process holds
on that file are released, even if the locks were made using other
descriptors that remain open. Likewise, locks are released when a
process exits, and are not inherited by child processes created using
fork (see section Creating a Process).
When making a lock, use a struct flock to specify what kind of
lock and where. This data type and the associated macros for the
fcntl function are declared in the header file `fcntl.h'.
fcntl function to describe a file
lock. It has these members:
short int l_type
F_RDLCK, F_WRLCK, or
F_UNLCK.
short int l_whence
fseek or
lseek, and specifies what the offset is relative to. Its value
can be one of SEEK_SET, SEEK_CUR, or SEEK_END.
off_t l_start
l_whence member.
off_t l_len
0 is treated specially; it means the region extends to the end of
the file.
pid_t l_pid
fcntl with
the F_GETLK command, but is ignored when making a lock.
fcntl, to
specify that it should get information about a lock. This command
requires a third argument of type struct flock * to be passed
to fcntl, so that the form of the call is:
fcntl (filedes, F_GETLK, lockp)
If there is a lock already in place that would block the lock described
by the lockp argument, information about that lock overwrites
*lockp. Existing locks are not reported if they are
compatible with making a new lock as specified. Thus, you should
specify a lock type of F_WRLCK if you want to find out about both
read and write locks, or F_RDLCK if you want to find out about
write locks only.
There might be more than one lock affecting the region specified by the
lockp argument, but fcntl only returns information about
one of them. The l_whence member of the lockp structure is
set to SEEK_SET and the l_start and l_len fields
set to identify the locked region.
If no lock applies, the only change to the lockp structure is to
update the l_type to a value of F_UNLCK.
The normal return value from fcntl with this command is an
unspecified value other than -1, which is reserved to indicate an
error. The following errno error conditions are defined for
this command:
EBADF
EINVAL
fcntl, to
specify that it should set or clear a lock. This command requires a
third argument of type struct flock * to be passed to
fcntl, so that the form of the call is:
fcntl (filedes, F_SETLK, lockp)
If the process already has a lock on any part of the region, the old lock
on that part is replaced with the new lock. You can remove a lock
by specifying a lock type of F_UNLCK.
If the lock cannot be set, fcntl returns immediately with a value
of -1. This function does not block waiting for other processes
to release locks. If fcntl succeeds, it return a value other
than -1.
The following errno error conditions are defined for this
function:
EAGAIN
EACCES
EAGAIN in this case, and other systems
use EACCES; your program should treat them alike, after
F_SETLK. (The GNU system always uses EAGAIN.)
EBADF
EINVAL
ENOLCK
fcntl, to
specify that it should set or clear a lock. It is just like the
F_SETLK command, but causes the process to block (or wait)
until the request can be specified.
This command requires a third argument of type struct flock *, as
for the F_SETLK command.
The fcntl return values and errors are the same as for the
F_SETLK command, but these additional errno error conditions
are defined for this command:
EINTR
EDEADLK
The following macros are defined for use as values for the l_type
member of the flock structure. The values are integer constants.
F_RDLCK
F_WRLCK
F_UNLCK
As an example of a situation where file locking is useful, consider a program that can be run simultaneously by several different users, that logs status information to a common file. One example of such a program might be a game that uses a file to keep track of high scores. Another example might be a program that records usage or accounting information for billing purposes.
Having multiple copies of the program simultaneously writing to the file could cause the contents of the file to become mixed up. But you can prevent this kind of problem by setting a write lock on the file before actually writing to the file.
If the program also needs to read the file and wants to make sure that the contents of the file are in a consistent state, then it can also use a read lock. While the read lock is set, no other process can lock that part of the file for writing.
Remember that file locks are only a voluntary protocol for controlling access to a file. There is still potential for access to the file by programs that don't use the lock protocol.
If you set the O_ASYNC status flag on a file descriptor
(see section File Status Flags), a SIGIO signal is sent whenever
input or output becomes possible on that file descriptor. The process
or process group to receive the signal can be selected by using the
F_SETOWN command to the fcntl function. If the file
descriptor is a socket, this also selects the recipient of SIGURG
signals that are delivered when out-of-band data arrives on that socket;
see section Out-of-Band Data. (SIGURG is sent in any situation
where select would report the socket as having an "exceptional
condition". See section Waiting for Input or Output.)
If the file descriptor corresponds to a terminal device, then SIGIO
signals are sent to the foreground process group of the terminal.
See section Job Control.
The symbols in this section are defined in the header file `fcntl.h'.
fcntl, to
specify that it should get information about the process or process
group to which SIGIO signals are sent. (For a terminal, this is
actually the foreground process group ID, which you can get using
tcgetpgrp; see section Functions for Controlling Terminal Access.)
The return value is interpreted as a process ID; if negative, its absolute value is the process group ID.
The following errno error condition is defined for this command:
EBADF
fcntl, to
specify that it should set the process or process group to which
SIGIO signals are sent. This command requires a third argument
of type pid_t to be passed to fcntl, so that the form of
the call is:
fcntl (filedes, F_SETOWN, pid)
The pid argument should be a process ID. You can also pass a negative number whose absolute value is a process group ID.
The return value from fcntl with this command is -1
in case of error and some other value if successful. The following
errno error conditions are defined for this command:
EBADF
ESRCH
This chapter describes the GNU C library's functions for manipulating files. Unlike the input and output functions described in section Input/Output on Streams and section Low-Level Input/Output, these functions are concerned with operating on the files themselves, rather than on their contents.
Among the facilities described in this chapter are functions for examining or modifying directories, functions for renaming and deleting files, and functions for examining and setting file attributes such as access permissions and modification times.
Each process has associated with it a directory, called its current working directory or simply working directory, that is used in the resolution of relative file names (see section File Name Resolution).
When you log in and begin a new session, your working directory is
initially set to the home directory associated with your login account
in the system user database. You can find any user's home directory
using the getpwuid or getpwnam functions; see section User Database.
Users can change the working directory using shell commands like
cd. The functions described in this section are the primitives
used by those commands and by other programs for examining and changing
the working directory.
Prototypes for these functions are declared in the header file `unistd.h'.
getcwd function returns an absolute file name representing
the current working directory, storing it in the character array
buffer that you provide. The size argument is how you tell
the system the allocation size of buffer.
The GNU library version of this function also permits you to specify a
null pointer for the buffer argument. Then getcwd
allocates a buffer automatically, as with malloc
(see section Unconstrained Allocation). If the size is greater than
zero, then the buffer is that large; otherwise, the buffer is as large
as necessary to hold the result.
The return value is buffer on success and a null pointer on failure.
The following errno error conditions are defined for this function:
EINVAL
ERANGE
EACCES
Here is an example showing how you could implement the behavior of GNU's
getcwd (NULL, 0) using only the standard behavior of
getcwd:
char *
gnu_getcwd ()
{
int size = 100;
char *buffer = (char *) xmalloc (size);
while (1)
{
char *value = getcwd (buffer, size);
if (value != 0)
return buffer;
size *= 2;
free (buffer);
buffer = (char *) xmalloc (size);
}
}
See section Examples of malloc, for information about xmalloc, which is
not a library function but is a customary name used in most GNU
software.
getcwd, but has no way to specify the size of
the buffer. The GNU library provides getwd only
for backwards compatibility with BSD.
The buffer argument should be a pointer to an array at least
PATH_MAX bytes long (see section Limits on File System Capacity). In the GNU
system there is no limit to the size of a file name, so this is not
necessarily enough space to contain the directory name. That is why
this function is deprecated.
The normal, successful return value from chdir is 0. A
value of -1 is returned to indicate an error. The errno
error conditions defined for this function are the usual file name
syntax errors (see section File Name Errors), plus ENOTDIR if the
file filename is not a directory.
The facilities described in this section let you read the contents of a directory file. This is useful if you want your program to list all the files in a directory, perhaps as part of a menu.
The opendir function opens a directory stream whose
elements are directory entries. You use the readdir function on
the directory stream to retrieve these entries, represented as
struct dirent objects. The name of the file for each entry is
stored in the d_name member of this structure. There are obvious
parallels here to the stream facilities for ordinary files, described in
section Input/Output on Streams.
This section describes what you find in a single directory entry, as you might obtain it from a directory stream. All the symbols are declared in the header file `dirent.h'.
char d_name[]
ino_t d_fileno
d_ino. In the GNU system and most POSIX
systems, for most files this the same as the st_ino member that
stat will return for the file. See section File Attributes.
unsigned char d_namlen
unsigned char because that is the integer
type of the appropriate size
unsigned char d_type
DT_UNKNOWN
DT_REG
DT_DIR
DT_FIFO
DT_SOCK
DT_CHR
DT_BLK
st_mode member of
struct statbuf. These two macros convert between d_type
values and st_mode values:
d_type value corresponding to mode.
st_mode value corresponding to dirtype.
This structure may contain additional members in the future.
When a file has multiple names, each name has its own directory entry.
The only way you can tell that the directory entries belong to a
single file is that they have the same value for the d_fileno
field.
File attributes such as size, modification times, and the like are part of the file itself, not any particular directory entry. See section File Attributes.
This section describes how to open a directory stream. All the symbols are declared in the header file `dirent.h'.
DIR data type represents a directory stream.
You shouldn't ever allocate objects of the struct dirent or
DIR data types, since the directory access functions do that for
you. Instead, you refer to these objects using the pointers returned by
the following functions.
opendir function opens and returns a directory stream for
reading the directory whose file name is dirname. The stream has
type DIR *.
If unsuccessful, opendir returns a null pointer. In addition to
the usual file name errors (see section File Name Errors), the
following errno error conditions are defined for this function: