The GNU C Library


Table of Contents


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

Introduction

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.

Getting Started

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.

Standards and Portability

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.

ISO C

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.

POSIX (The Portable Operating System Interface)

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

Berkeley Unix

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

SVID (The System V Interface Description)

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

Using the Library

This section describes some of the practical issues involved in using the GNU C library.

Header Files

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.

Macro Definitions of Functions

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.

Reserved Names

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:

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.

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.

Feature Test Macros

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.

Macro: _POSIX_SOURCE
If you define this macro, then the functionality from the POSIX.1 standard (IEEE Standard 1003.1) is available, as well as all of the ISO C facilities.

Macro: _POSIX_C_SOURCE
If you define this macro with a value of 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.

Macro: _BSD_SOURCE
If you define this macro, functionality derived from 4.3 BSD Unix is included as well as the ISO C, POSIX.1, and POSIX.2 material.

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.

Macro: _SVID_SOURCE
If you define this macro, functionality derived from SVID is included as well as the ISO C, POSIX.1, POSIX.2, and X/Open material.

Macro: _XOPEN_SOURCE
If you define this macro, functionality described in the X/Open Portability Guide is included. This is a superset of the POSIX.1 and POSIX.2 functionality and in fact _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.

Macro: _GNU_SOURCE
If you define this macro, everything is included: ISO C, POSIX.1, POSIX.2, BSD, SVID, X/Open, and GNU extensions. In the cases where POSIX.1 conflicts with BSD, the POSIX definitions take precedence.

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.

Macro: _REENTRANT
Macro: _THREAD_SAFE
If you define one of these macros, reentrant versions of several functions get declared. Some of the functions are specified in POSIX.1c but many others are only available on a few other systems or are unique to GNU libc. The problem is that the standardization of the thread safe C library interface still is behind.

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.

Roadmap to the Manual

Here is an overview of the contents of the remaining chapters of this manual.

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.

Error Reporting

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.

Checking for Errors

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

Variable: volatile int errno
The variable 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.

Error Codes

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.

Macro: int EPERM
Operation not permitted; only the owner of the file (or other resource) or processes with special privileges can perform the operation.

Macro: int ENOENT
No such file or directory. This is a "file doesn't exist" error for ordinary files that are referenced in contexts where they are expected to already exist.

Macro: int ESRCH
No process matches the specified process ID.

Macro: int EINTR
Interrupted function call; an asynchronous signal occurred and prevented completion of the call. When this happens, you should try the call again.

You can choose to have functions resume after a signal that is handled, rather than failing with EINTR; see section Primitives Interrupted by Signals.

Macro: int EIO
Input/output error; usually used for physical read or write errors.

Macro: int ENXIO
No such device or address. The system tried to use the device represented by a file you specified, and it couldn't find the device. This can mean that the device file was installed incorrectly, or that the physical device is missing or not correctly attached to the computer.

Macro: int E2BIG
Argument list too long; used when the arguments passed to a new program being executed with one of the exec functions (see section Executing a File) occupy too much memory space. This condition never arises in the GNU system.

Macro: int ENOEXEC
Invalid executable file format. This condition is detected by the exec functions; see section Executing a File.

Macro: int EBADF
Bad file descriptor; for example, I/O on a descriptor that has been closed or reading from a descriptor open only for writing (or vice versa).

Macro: int ECHILD
There are no child processes. This error happens on operations that are supposed to manipulate child processes, when there aren't any processes to manipulate.

Macro: int EDEADLK
Deadlock avoided; allocating a system resource would have resulted in a deadlock situation. The system does not guarantee that it will notice all such situations. This error means you got lucky and the system noticed; it might just hang. See section File Locks, for an example.

Macro: int ENOMEM
No memory available. The system cannot allocate more virtual memory because its capacity is full.

Macro: int EACCES
Permission denied; the file permissions do not allow the attempted operation.

Macro: int EFAULT
Bad address; an invalid pointer was detected. In the GNU system, this error never happens; you get a signal instead.

Macro: int ENOTBLK
A file that isn't a block special file was given in a situation that requires one. For example, trying to mount an ordinary file as a file system in Unix gives this error.

Macro: int EBUSY
Resource busy; a system resource that can't be shared is already in use. For example, if you try to delete a file that is the root of a currently mounted filesystem, you get this error.

Macro: int EEXIST
File exists; an existing file was specified in a context where it only makes sense to specify a new file.

Macro: int EXDEV
An attempt to make an improper link across file systems was detected. This happens not only when you use link (see section Hard Links) but also when you rename a file with rename (see section Renaming Files).

Macro: int ENODEV
The wrong type of device was given to a function that expects a particular sort of device.

Macro: int ENOTDIR
A file that isn't a directory was specified when a directory is required.

Macro: int EISDIR
File is a directory; you cannot open a directory for writing, or create or remove hard links to it.

Macro: int EINVAL
Invalid argument. This is used to indicate various kinds of problems with passing the wrong argument to a library function.

Macro: int EMFILE
The current process has too many files open and can't open any more. Duplicate descriptors do count toward this limit.

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.

Macro: int ENFILE
There are too many distinct file openings in the entire system. Note that any number of linked channels count as just one file opening; see section Linked Channels. This error never occurs in the GNU system.

Macro: int ENOTTY
Inappropriate I/O control operation, such as trying to set terminal modes on an ordinary file.

Macro: int ETXTBSY
An attempt to execute a file that is currently open for writing, or write to a file that is currently being executed. Often using a debugger to run a program is considered having it open for writing and will cause this error. (The name stands for "text file busy".) This is not an error in the GNU system; the text is copied as necessary.

Macro: int EFBIG
File too big; the size of a file would be larger than allowed by the system.

Macro: int ENOSPC
No space left on device; write operation on a file failed because the disk is full.

Macro: int ESPIPE
Invalid seek operation (such as on a pipe).

Macro: int EROFS
An attempt was made to modify something on a read-only file system.

Macro: int EMLINK
Too many links; the link count of a single file would become too large. rename can cause this error if the file being renamed already has as many links as it can take (see section Renaming Files).

Macro: int EPIPE
Broken pipe; there is no process reading from the other end of a pipe. Every library function that returns this error code also generates a 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.

Macro: int EDOM
Domain error; used by mathematical functions when an argument value does not fall into the domain over which the function is defined.

Macro: int ERANGE
Range error; used by mathematical functions when the result value is not representable because of overflow or underflow.

Macro: int EAGAIN
Resource temporarily unavailable; the call might work if you try again later. The macro 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:

Macro: int EWOULDBLOCK
In the GNU C library, this is another name for 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.

Macro: int EINPROGRESS
An operation that cannot complete immediately was initiated on an object that has non-blocking mode selected. Some functions that must always block (such as 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.

Macro: int EALREADY
An operation is already in progress on an object that has non-blocking mode selected.

Macro: int ENOTSOCK
A file that isn't a socket was specified when a socket is required.

Macro: int EMSGSIZE
The size of a message sent on a socket was larger than the supported maximum size.

Macro: int EPROTOTYPE
The socket type does not support the requested communications protocol.

Macro: int ENOPROTOOPT
You specified a socket option that doesn't make sense for the particular protocol being used by the socket. See section Socket Options.

Macro: int EPROTONOSUPPORT
The socket domain does not support the requested communications protocol (perhaps because the requested protocol is completely invalid.) See section Creating a Socket.

Macro: int ESOCKTNOSUPPORT
The socket type is not supported.

Macro: int EOPNOTSUPP
The operation you requested is not supported. Some socket functions don't make sense for all types of sockets, and others may not be implemented for all communications protocols. In the GNU system, this error can happen for many calls when the object does not support the particular operation; it is a generic indication that the server knows nothing to do for that call.

Macro: int EPFNOSUPPORT
The socket communications protocol family you requested is not supported.

Macro: int EAFNOSUPPORT
The address family specified for a socket is not supported; it is inconsistent with the protocol being used on the socket. See section Sockets.

Macro: int EADDRINUSE
The requested socket address is already in use. See section Socket Addresses.

Macro: int EADDRNOTAVAIL
The requested socket address is not available; for example, you tried to give a socket a name that doesn't match the local host name. See section Socket Addresses.

Macro: int ENETDOWN
A socket operation failed because the network was down.

Macro: int ENETUNREACH
A socket operation failed because the subnet containing the remote host was unreachable.

Macro: int ENETRESET
A network connection was reset because the remote host crashed.

Macro: int ECONNABORTED
A network connection was aborted locally.

Macro: int ECONNRESET
A network connection was closed for reasons outside the control of the local host, such as by the remote machine rebooting or an unrecoverable protocol violation.

Macro: int ENOBUFS
The kernel's buffers for I/O operations are all in use. In GNU, this error is always synonymous with ENOMEM; you may get one or the other from network operations.

Macro: int EISCONN
You tried to connect a socket that is already connected. See section Making a Connection.

Macro: int ENOTCONN
The socket is not connected to anything. You get this error when you try to transmit data over a socket, without first specifying a destination for the data. For a connectionless socket (for datagram protocols, such as UDP), you get EDESTADDRREQ instead.

Macro: int EDESTADDRREQ
No default destination address was set for the socket. You get this error when you try to transmit data over a connectionless socket, without first specifying a destination for the data with connect.

Macro: int ESHUTDOWN
The socket has already been shut down.

Macro: int ETOOMANYREFS
???

Macro: int ETIMEDOUT
A socket operation with a specified timeout received no response during the timeout period.

Macro: int ECONNREFUSED
A remote host refused to allow the network connection (typically because it is not running the requested service).

Macro: int ELOOP
Too many levels of symbolic links were encountered in looking up a file name. This often indicates a cycle of symbolic links.

Macro: int ENAMETOOLONG
Filename too long (longer than PATH_MAX; see section Limits on File System Capacity) or host name too long (in gethostname or sethostname; see section Host Identification).

Macro: int EHOSTDOWN
The remote host for a requested network connection is down.

Macro: int EHOSTUNREACH
The remote host for a requested network connection is not reachable.

Macro: int ENOTEMPTY
Directory not empty, where an empty directory was expected. Typically, this error occurs when you are trying to delete a directory.

Macro: int EPROCLIM
This means that the per-user limit on new process would be exceeded by an attempted fork. See section Limiting Resource Usage, for details on the RLIMIT_NPROC limit.

Macro: int EUSERS
The file quota system is confused because there are too many users.

Macro: int EDQUOT
The user's disk quota was exceeded.

Macro: int ESTALE
Stale NFS file handle. This indicates an internal confusion in the NFS system which is due to file system rearrangements on the server host. Repairing this condition usually requires unmounting and remounting the NFS file system on the local host.

Macro: int EREMOTE
An attempt was made to NFS-mount a remote file system with a file name that already specifies an NFS-mounted file. (This is an error on some operating systems, but we expect it to work properly on the GNU system, making this error code impossible.)

Macro: int EBADRPC
???

Macro: int ERPCMISMATCH
???

Macro: int EPROGUNAVAIL
???

Macro: int EPROGMISMATCH
???

Macro: int EPROCUNAVAIL
???

Macro: int ENOLCK
No locks available. This is used by the file locking facilities; see section File Locks. This error is never generated by the GNU system, but it can result from an operation to an NFS server running another operating system.

Macro: int EFTYPE
Inappropriate file type or format. The file was the wrong type for the operation, or a data file had the wrong format.

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.

Macro: int EAUTH
???

Macro: int ENEEDAUTH
???

Macro: int ENOSYS
Function not implemented. Some functions have commands or options defined that might not be supported in all implementations, and this is the kind of error you get if you request them and they are not supported.

Macro: int EILSEQ
While decoding a multibyte character the function came along an invalid or an incomplete sequence of bytes or the given wide character is invalid.

Macro: int EBACKGROUND
In the GNU system, servers supporting the 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.

Macro: int EDIED
In the GNU system, opening a file returns this error when the file is translated by a program and the translator program dies while starting up, before it has connected to the file.

Macro: int ED
The experienced user will know what is wrong.

Macro: int EGREGIOUS
You did what?

Macro: int EIEIO
Go home and have a glass of warm, dairy-fresh milk.

Macro: int EGRATUITOUS
This error code has no purpose.

Macro: int EBADMSG

Macro: int EIDRM

Macro: int EMULTIHOP

Macro: int ENODATA

Macro: int ENOLINK

Macro: int ENOMSG

Macro: int ENOSR

Macro: int ENOSTR

Macro: int EOVERFLOW

Macro: int EPROTO

Macro: int ETIME

The following error codes are defined by the Linux/i386 kernel. They are not yet documented.

Macro: int ERESTART

Macro: int ECHRNG

Macro: int EL2NSYNC

Macro: int EL3HLT

Macro: int EL3RST

Macro: int ELNRNG

Macro: int EUNATCH

Macro: int ENOCSI

Macro: int EL2HLT

Macro: int EBADE

Macro: int EBADR

Macro: int EXFULL

Macro: int ENOANO

Macro: int EBADRQC

Macro: int EBADSLT

Macro: int EDEADLOCK

Macro: int EBFONT

Macro: int ENONET

Macro: int ENOPKG

Macro: int EADV

Macro: int ESRMNT

Macro: int ECOMM

Macro: int EDOTDOT

Macro: int ENOTUNIQ

Macro: int EBADFD

Macro: int EREMCHG

Macro: int ELIBACC

Macro: int ELIBBAD

Macro: int ELIBSCN

Macro: int ELIBMAX

Macro: int ELIBEXEC

Macro: int ESTRPIPE

Macro: int EUCLEAN

Macro: int ENOTNAM

Macro: int ENAVAIL

Macro: int EISNAM

Macro: int EREMOTEIO

Macro: int ENOMEDIUM

Macro: int EMEDIUMTYPE

Error Messages

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.

Function: char * strerror (int errnum)
The 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'.

Function: char * strerror_r (int errnum, char *buf, size_t n)
The 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'.

Function: void perror (const char *message)
This function prints an error message to the stream 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:

Variable: char * program_invocation_name
This variable's value is the name that was used to invoke the program running in the current process. It is the same as argv[0]. Note that this is not necessarily a useful file name; often it contains no directory names. See section Program Arguments.

Variable: char * program_invocation_short_name
This variable's value is the name that was used to invoke the program running in the current process, with directory names removed. (That is to say, it is the same as 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;
}

Memory Allocation

The GNU system provides several methods for allocating memory space under explicit program control. They vary in generality and in efficiency.

Dynamic Memory Allocation Concepts

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.

Dynamic Allocation and C

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;
}

Unconstrained Allocation

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

Basic Storage Allocation

To allocate a block of memory, call malloc. The prototype for this function is in `stdlib.h'.

Function: void * malloc (size_t size)
This function returns a pointer to a newly allocated block size bytes long, or a null pointer if the block could not be allocated.

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.

Examples of 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).

Freeing Memory Allocated with 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'.

Function: void free (void *ptr)
The free function deallocates the block of storage pointed at by ptr.

Function: void cfree (void *ptr)
This function does the same thing as 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.

Changing the Size of a Block

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

Function: void * realloc (void *ptr, size_t newsize)
The 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.

Allocating Cleared Space

The function calloc allocates memory and clears it to zero. It is declared in `stdlib.h'.

Function: void * calloc (size_t count, size_t eltsize)
This function allocates a block long enough to contain a vector of count elements, each of size eltsize. Its contents are cleared to zero before 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.

Efficiency Considerations for 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.

Allocating Aligned Memory Blocks

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.

Function: void * memalign (size_t boundary, size_t size)
The 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.

Function: void * valloc (size_t size)
Using 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);
}

Malloc Tunable Parameters

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

Function: int mallopt (int param, int value)
When calling 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
This is the minimum size (in bytes) of the top-most, releaseable chunk that will cause sbrk to be called with a negative argument in order to return memory to the system.
M_TOP_PAD
This parameter determines the amount of extra memory to obtain from the system when a call to 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
All chunks larger than this value are allocated outside the normal heap, using the 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
The maximum number of chunks to allocate with mmap. Setting this to zero disables all use of mmap.

Heap Consistency Checking

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

Function: int mcheck (void (*abortfn) (enum mcheck_status status))
Calling 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.

Function: enum mcheck_status mprobe (void *pointer)
The 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.

Data Type: enum mcheck_status
This enumerated type describes what kind of inconsistency was detected in an allocated block, if any. Here are the possible values:

MCHECK_DISABLED
mcheck was not called before the first allocation. No consistency checking can be done.
MCHECK_OK
No inconsistency detected.
MCHECK_HEAD
The data immediately before the block was modified. This commonly happens when an array index or pointer is decremented too far.
MCHECK_TAIL
The data immediately after the block was modified. This commonly happens when an array index or pointer is incremented too far.
MCHECK_FREE
The block was already freed.

Storage Allocation Hooks

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

Variable: __malloc_hook
The value of this variable is a pointer to function that malloc uses whenever it is called. You should define this function to look like malloc; that is, like:

void *function (size_t size)

Variable: __realloc_hook
The value of this variable is a pointer to function that 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)

Variable: __free_hook
The value of this variable is a pointer to function that 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.

Statistics for Storage Allocation with 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.

Data Type: struct mallinfo
This structure type is used to return information about the dynamic storage allocator. It contains the following members:

int arena
This is the total size of memory allocated with sbrk by malloc, in bytes.
int ordblks
This is the number of chunks not in use. (The storage allocator internally gets chunks of memory from the operating system, and then carves them up to satisfy individual malloc requests; see section Efficiency Considerations for malloc.)
int smblks
This field is unused.
int hblks
This is the total number of chunks allocated with mmap.
int hblkhd
This is the total size of memory allocated with mmap, in bytes.
int usmblks
This field is unused.
int fsmblks
This field is unused.
int uordblks
This is the total size of memory occupied by chunks handed out by malloc.
int fordblks
This is the total size of memory occupied by free (not in use) chunks.
int keepcost
This is the size of the top-most, releaseable chunk that normally borders the end of the heap (i.e. the "brk" of the process).

Function: struct mallinfo mallinfo (void)
This function returns information about the current dynamic memory usage in a structure of type struct mallinfo.

Summary of malloc-Related Functions

Here is a summary of the functions that work with malloc:

void *malloc (size_t size)
Allocate a block of size bytes. See section Basic Storage Allocation.
void free (void *addr)
Free a block previously allocated by malloc. See section Freeing Memory Allocated with malloc.
void *realloc (void *addr, size_t size)
Make a block previously allocated by 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)
Allocate a block of count * eltsize bytes using malloc, and set its contents to zero. See section Allocating Cleared Space.
void *valloc (size_t size)
Allocate a block of size bytes, starting on a page boundary. See section Allocating Aligned Memory Blocks.
void *memalign (size_t size, size_t boundary)
Allocate a block of size bytes, starting on an address that is a multiple of boundary. See section Allocating Aligned Memory Blocks.
int mallopt (int param, int value)
Adjust a tunable parameter. See section Malloc Tunable Parameters
int mcheck (void (*abortfn) (void))
Tell 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)
A pointer to a function that malloc uses whenever it is called.
void *(*__realloc_hook) (void *ptr, size_t size)
A pointer to a function that realloc uses whenever it is called.
void (*__free_hook) (void *ptr)
A pointer to a function that free uses whenever it is called.
struct mallinfo mallinfo (void)
Return information about the current dynamic memory usage. See section Statistics for Storage Allocation with malloc.

Obstacks

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.

Creating Obstacks

The utilities for manipulating obstacks are declared in the header file `obstack.h'.

Data Type: struct obstack
An obstack is represented by a data structure of type 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.

Preparing for Using Obstacks

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.

Function: int obstack_init (struct obstack *obstack-ptr)
Initialize obstack obstack-ptr for allocation of objects. This function calls the obstack's 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);

Allocation in an Obstack

The most direct way to allocate an object in an obstack is with obstack_alloc, which is invoked almost like malloc.

Function: void * obstack_alloc (struct obstack *obstack-ptr, int size)
This allocates an uninitialized block of size bytes in an obstack and returns its address. Here obstack-ptr specifies which obstack to allocate the block in; it is the address of the 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:

Function: void * obstack_copy (struct obstack *obstack-ptr, void *address, int size)
This allocates a block and initializes it by copying size bytes of data starting at address. It can return a null pointer under the same conditions as obstack_alloc.

Function: void * obstack_copy0 (struct obstack *obstack-ptr, void *address, int size)
Like 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).

Freeing Objects in an Obstack

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.

Function: void obstack_free (struct obstack *obstack-ptr, void *object)
If object is a null pointer, everything allocated in the obstack is freed. Otherwise, object must be the address of an object allocated in the obstack. Then object is freed, along with everything allocated in obstack since object.

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.

Obstack Functions and Macros

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.

Growing Objects

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.

Function: void obstack_blank (struct obstack *obstack-ptr, int size)
The most basic function for adding to a growing object is obstack_blank, which adds space without initializing it.

Function: void obstack_grow (struct obstack *obstack-ptr, void *data, int size)
To add a block of initialized space, use 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.

Function: void obstack_grow0 (struct obstack *obstack-ptr, void *data, int size)
This is the growing-object analogue of obstack_copy0. It adds size bytes copied from data, followed by an additional null character.

Function: void obstack_1grow (struct obstack *obstack-ptr, char c)
To add one character at a time, use the function obstack_1grow. It adds a single byte containing c to the growing object.

Function: void obstack_ptr_grow (struct obstack *obstack-ptr, void *data)
Adding the value of a pointer one can use the function obstack_ptr_grow. It adds sizeof (void *) bytes containing the value of data.

Function: void obstack_int_grow (struct obstack *obstack-ptr, int data)
A single value of type 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.

Function: void * obstack_finish (struct obstack *obstack-ptr)
When you are finished growing the object, use the function 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:

Function: int obstack_object_size (struct obstack *obstack-ptr)
This function returns the current size of the growing object, in bytes. Remember to call this function before finishing the object. After it is finished, 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.

Extra Fast Growing Objects

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:

Function: int obstack_room (struct obstack *obstack-ptr)
This returns the number of bytes that can be added safely to the current growing object (or to an object about to be started) in obstack obstack using the fast growth functions.

While you know there is room, you can use these fast growth functions for adding data to a growing object:

Function: void obstack_1grow_fast (struct obstack *obstack-ptr, char c)
The function obstack_1grow_fast adds one byte containing the character c to the growing object in obstack obstack-ptr.

Function: void obstack_ptr_grow_fast (struct obstack *obstack-ptr, void *data)
The function obstack_ptr_grow_fast adds sizeof (void *) bytes containing the value of data to the growing object in obstack obstack-ptr.

Function: void obstack_int_grow_fast (struct obstack *obstack-ptr, int data)
The function obstack_int_grow_fast adds sizeof (int) bytes containing the value of data to the growing object in obstack obstack-ptr.

Function: void obstack_blank_fast (struct obstack *obstack-ptr, int size)
The function 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++);
        }
    }
}

Status of an Obstack

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.

Function: void * obstack_base (struct obstack *obstack-ptr)
This function returns the tentative address of the beginning of the currently growing object in obstack-ptr. If you finish the object immediately, it will have that address. If you make it larger first, it may outgrow the current chunk--then its address will change!

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

Function: void * obstack_next_free (struct obstack *obstack-ptr)
This function returns the address of the first free byte in the current chunk of obstack obstack-ptr. This is the end of the currently growing object. If no object is growing, obstack_next_free returns the same value as obstack_base.

Function: int obstack_object_size (struct obstack *obstack-ptr)
This function returns the size in bytes of the currently growing object. This is equivalent to

obstack_next_free (obstack-ptr) - obstack_base (obstack-ptr)

Alignment of Data in Obstacks

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:

Macro: int obstack_alignment_mask (struct obstack *obstack-ptr)
The value is a bit mask; a bit that is 1 indicates that the corresponding bit in the address of an object should be 0. The mask value should be one less than a power of 2; the effect is that all object addresses are multiples of that power of 2. The default value of the mask is 3, so that addresses are multiples of 4. A mask value of 0 means an object can start on any multiple of 1 (that is, no alignment is required).

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.

Obstack Chunks

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.

Macro: int obstack_chunk_size (struct obstack *obstack-ptr)
This returns the chunk size of the given obstack.

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;

Summary of Obstack Functions

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)
Initialize use of an obstack. See section Creating Obstacks.
void *obstack_alloc (struct obstack *obstack-ptr, int size)
Allocate an object of size uninitialized bytes. See section Allocation in an Obstack.
void *obstack_copy (struct obstack *obstack-ptr, void *address, int size)
Allocate an object of size bytes, with contents copied from address. See section Allocation in an Obstack.
void *obstack_copy0 (struct obstack *obstack-ptr, void *address, int size)
Allocate an object of size+1 bytes, with size of them copied from address, followed by a null character at the end. See section Allocation in an Obstack.
void obstack_free (struct obstack *obstack-ptr, void *object)
Free object (and everything allocated in the specified obstack more recently than object). See section Freeing Objects in an Obstack.
void obstack_blank (struct obstack *obstack-ptr, int size)
Add size uninitialized bytes to a growing object. See section Growing Objects.
void obstack_grow (struct obstack *obstack-ptr, void *address, int size)
Add size bytes, copied from address, to a growing object. See section Growing Objects.
void obstack_grow0 (struct obstack *obstack-ptr, void *address, int size)
Add size bytes, copied from address, to a growing object, and then add another byte containing a null character. See section Growing Objects.
void obstack_1grow (struct obstack *obstack-ptr, char data-char)
Add one byte containing data-char to a growing object. See section Growing Objects.
void *obstack_finish (struct obstack *obstack-ptr)
Finalize the object that is growing and return its permanent address. See section Growing Objects.
int obstack_object_size (struct obstack *obstack-ptr)
Get the current size of the currently growing object. See section Growing Objects.
void obstack_blank_fast (struct obstack *obstack-ptr, int size)
Add size uninitialized bytes to a growing object without checking that there is enough room. See section Extra Fast Growing Objects.
void obstack_1grow_fast (struct obstack *obstack-ptr, char data-char)
Add one byte containing data-char to a growing object without checking that there is enough room. See section Extra Fast Growing Objects.
int obstack_room (struct obstack *obstack-ptr)
Get the amount of room now available for growing the current object. See section Extra Fast Growing Objects.
int obstack_alignment_mask (struct obstack *obstack-ptr)
The mask used for aligning the beginning of an object. This is an lvalue. See section Alignment of Data in Obstacks.
int obstack_chunk_size (struct obstack *obstack-ptr)
The size for allocating chunks. This is an lvalue. See section Obstack Chunks.
void *obstack_base (struct obstack *obstack-ptr)
Tentative starting address of the currently growing object. See section Status of an Obstack.
void *obstack_next_free (struct obstack *obstack-ptr)
Address just after the end of the currently growing object. See section Status of an Obstack.

Automatic Storage with Variable Size

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.

Function: void * alloca (size_t size);
The return value of 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.

Advantages of alloca

Here are the reasons why alloca may be preferable to malloc:

Disadvantages of alloca

These are the disadvantages of alloca in comparison with malloc:

GNU C Variable-Size Arrays

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:

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.

Relocating Allocator

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.

Concepts of Relocating Allocation

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.

Allocating and Freeing Relocatable Blocks

In the descriptions below, handleptr designates the address of the handle. All the functions are declared in `malloc.h'; all are GNU extensions.

Function: void * r_alloc (void **handleptr, size_t size)
This function allocates a relocatable block of size size. It stores the block's address in *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.

Function: void r_alloc_free (void **handleptr)
This function is the way to free a relocatable block. It frees the block that *handleptr points to, and stores a null pointer in *handleptr to show it doesn't point to an allocated block any more.

Function: void * r_re_alloc (void **handleptr, size_t size)
The function 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.

Character Handling

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

Classification of Characters

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

Function: int islower (int c)
Returns true if c is a lower-case letter.

Function: int isupper (int c)
Returns true if c is an upper-case letter.

Function: int isalpha (int c)
Returns true if c is an alphabetic character (a letter). If 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.

Function: int isdigit (int c)
Returns true if c is a decimal digit (`0' through `9').

Function: int isalnum (int c)
Returns true if c is an alphanumeric character (a letter or number); in other words, if either isalpha or isdigit is true of a character, then isalnum is also true.

Function: int isxdigit (int c)
Returns true if c is a hexadecimal digit. Hexadecimal digits include the normal decimal digits `0' through `9' and the letters `A' through `F' and `a' through `f'.

Function: int ispunct (int c)
Returns true if c is a punctuation character. This means any printing character that is not alphanumeric or a space character.

Function: int isspace (int c)
Returns true if c is a whitespace character. In the standard "C" locale, isspace returns true for only the standard whitespace characters:

' '
space
'\f'
formfeed
'\n'
newline
'\r'
carriage return
'\t'
horizontal tab
'\v'
vertical tab

Function: int isblank (int c)
Returns true if c is a blank character; that is, a space or a tab. This function is a GNU extension.

Function: int isgraph (int c)
Returns true if c is a graphic character; that is, a character that has a glyph associated with it. The whitespace characters are not considered graphic.

Function: int isprint (int c)
Returns true if c is a printing character. Printing characters include all the graphic characters, plus the space (` ') character.

Function: int iscntrl (int c)
Returns true if c is a control character (that is, a character that is not a printing character).

Function: int isascii (int c)
Returns true if c is a 7-bit unsigned char value that fits into the US/UK ASCII character set. This function is a BSD extension and is also an SVID extension.

Case Conversion

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

Function: int tolower (int c)
If c is an upper-case letter, tolower returns the corresponding lower-case letter. If c is not an upper-case letter, c is returned unchanged.

Function: int toupper (int c)
If c is a lower-case letter, tolower returns the corresponding upper-case letter. Otherwise c is returned unchanged.

Function: int toascii (int c)
This function converts c to a 7-bit 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.

Function: int _tolower (int c)
This is identical to tolower, and is provided for compatibility with the SVID. See section SVID (The System V Interface Description).

Function: int _toupper (int c)
This is identical to toupper, and is provided for compatibility with the SVID.

String and Array Utilities

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.

Representation of Strings

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.

String and Array Conventions

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.

String Length

You can get the length of a string using the strlen function. This function is declared in the header file `string.h'.

Function: size_t strlen (const char *s)
The 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

Copying and Concatenation

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

Function: void * memcpy (void *to, const void *from, size_t size)
The 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));

Function: void * memmove (void *to, const void *from, size_t size)
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.

Function: void * memccpy (void *to, const void *from, int c, size_t size)
This function copies no more than size bytes from from to to, stopping if a byte matching c is found. The return value is a pointer into to one byte past where c was copied, or a null pointer if no byte matching c appeared in the first size bytes of from.

Function: void * memset (void *block, int c, size_t size)
This function copies the value of c (converted to an unsigned char) into each of the first size bytes of the object beginning at block. It returns the value of block.

Function: char * strcpy (char *to, const char *from)
This copies characters from the string from (up to and including the terminating null character) into the string to. Like memcpy, this function has undefined results if the strings overlap. The return value is the value of to.

Function: char * strncpy (char *to, const char *from, size_t size)
This function is similar 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.

Function: char * strdup (const char *s)
This function copies the null-terminated string s into a newly allocated string. The string is allocated using 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.

Function: char * strndup (const char *s, size_t size)
This function is similar to 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.

Function: char * stpcpy (char *to, const char *from)
This function is like 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.

Function: char * stpncpy (char *to, const char *from, size_t size)
This function is similar to 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.

Function: char * strdupa (const char *s)
This function is similar to 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.

Function: char * strndupa (const char *s, size_t size)
This function is similar to 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.

Function: char * strcat (char *to, const char *from)
The 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.

Function: char * strncat (char *to, const char *from, size_t size)
This function is like 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

Function: void * bcopy (void *from, const void *to, size_t size)
This is a partially obsolete alternative for memmove, derived from BSD. Note that it is not quite equivalent to memmove, because the arguments are not in the same order.

Function: void * bzero (void *block, size_t size)
This is a partially obsolete alternative for memset, derived from BSD. Note that it is not as general as memset, because the only value it can store is zero.

String/Array Comparison

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

Function: int memcmp (const void *a1, const void *a2, size_t size)
The function 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.

Function: int strcmp (const char *s1, const char *s2)
The 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.

Function: int strcasecmp (const char *s1, const char *s2)
This function is like strcmp, except that differences in case are ignored.

strcasecmp is derived from BSD.

Function: int strncasecmp (const char *s1, const char *s2, size_t n)
This function is like strncmp, except that differences in case are ignored.

strncasecmp is a GNU extension.

Function: int strncmp (const char *s1, const char *s2, size_t size)
This function is the similar to 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. */

Function: int bcmp (const void *a1, const void *a2, size_t size)
This is an obsolete alias for memcmp, derived from BSD.

Collation Functions

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.

Function: int strcoll (const char *s1, const char *s2)
The 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 with qsort. */

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)
{
  /* Sort temp_array by comparing the strings. */
  qsort (array, sizeof (char *),
         nstrings, compare_elements);
}

Function: size_t strxfrm (char *to, const char *from, size_t size)
The function 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.

Search Functions

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

Function: void * memchr (const void *block, int c, size_t size)
This function finds the first occurrence of the byte c (converted to an 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.

Function: char * strchr (const char *string, int c)
The 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.

Function: char * index (const char *string, int c)
index is another name for strchr; they are exactly the same.

Function: char * strrchr (const char *string, int c)
The function 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"

Function: char * rindex (const char *string, int c)
rindex is another name for strrchr; they are exactly the same.

Function: char * strstr (const char *haystack, const char *needle)
This is like 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"

Function: void * memmem (const void *haystack, size_t haystack-len,
const void *needle, size_t needle-len)
This is like 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.

Function: size_t strspn (const char *string, const char *skipset)
The 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

Function: size_t strcspn (const char *string, const char *stopset)
The 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

Function: char * strpbrk (const char *string, const char *stopset)
The 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"

Finding Tokens in a String

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

Function: char * strtok (char *newstring, const char *delimiters)
A string can be split into tokens by making a series of calls to the function 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.

Function: char * strtok_r (char *newstring, const char *delimiters, char **save_ptr)
Just like 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.

Function: char * strsep (char **string_ptr, const char *delimiter)
A second reentrant approach is to avoid the additional first argument. The initialization of the moving pointer has to be done by the user. Successive calls of 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 */

Input/Output Overview

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:

Input/Output Concepts

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.

Streams and File Descriptors

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.

File Position

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.

File Names

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.

Directories

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.

File Name Resolution

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'
The file named `a', in the root directory.
`/a/b'
The file named `b', in the directory named `a' in the root directory.
`a'
The file named `a', in the current working directory.
`/a/./b'
This is the same as `/a/b'.
`./a'
The file named `a', in the current working directory.
`../a'
The file named `a', in the parent directory of the current working directory.

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.

File Name Errors

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
The process does not have search permission for a directory component of the file name.
ENAMETOOLONG
This error is used when either the the total length of a file name is greater than 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
This error is reported when a file referenced as a directory component in the file name doesn't exist, or when a component is a symbolic link whose target file does not exist. See section Symbolic Links.
ENOTDIR
A file that is referenced as a directory component in the file name exists, but it isn't a directory.
ELOOP
Too many symbolic links were resolved while trying to look up the file name. The system has an arbitrary limit on the number of symbolic links that may be resolved in looking up a single file name, as a primitive way to detect loops. See section Symbolic Links.

Portability of File Names

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.

Input/Output on Streams

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.

Streams

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

Data Type: FILE
This is the data type used to represent stream objects. A 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.

Standard Streams

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

Variable: FILE * stdin
The standard input stream, which is the normal source of input for the program.

Variable: FILE * stdout
The standard output stream, which is used for normal output from the program.

Variable: FILE * stderr
The standard error stream, which is used for error messages and diagnostics issued by the program.

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

Function: FILE * fopen (const char *filename, const char *opentype)
The 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:

`r'
Open an existing file for reading only.
`w'
Open the file for writing only. If the file already exists, it is truncated to zero length. Otherwise a new file is created.
`a'
Open a file for append access; that is, writing at the end of file only. If the file already exists, its initial contents are unchanged and output to the stream is appended to the end of the file. Otherwise, a new, empty file is created.
`r+'
Open an existing file for both reading and writing. The initial contents of the file are unchanged and the initial file position is at the beginning of the file.
`w+'
Open a file for both reading and writing. If the file already exists, it is truncated to zero length. Otherwise, a new file is created.
`a+'
Open or create file for both reading and appending. If the file exists, its initial contents are unchanged. Otherwise, a new file is created. The initial file position for reading is at the beginning of the file, but output is always appended to the end of the file.

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.

Macro: int FOPEN_MAX
The value of this macro is an integer constant expression that represents the minimum number of streams that the implementation guarantees can be open simultaneously. You might be able to open more than this many streams, but that is not guaranteed. The value of this constant is at least eight, which includes the three standard streams 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.

Function: FILE * freopen (const char *filename, const char *opentype, FILE *stream)
This function is like a combination of 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.

Closing Streams

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.

Function: int fclose (FILE *stream)
This function causes stream to be closed and the connection to the corresponding file to be broken. Any buffered output is written and any buffered input is discarded. The 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.

Function: int fcloseall (void)
This function causes all open streams of the process to be closed and the connection to corresponding files to be broken. All buffered data is written and any buffered inputis discarded. The 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.

Simple Output by Characters or Lines

This section describes functions for performing character- and line-oriented output.

These functions are declared in the header file `stdio.h'.

Function: int fputc (int c, FILE *stream)
The 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.

Function: int putc (int c, FILE *stream)
This is just like 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.

Function: int putchar (int c)
The putchar function is equivalent to putc with stdout as the value of the stream argument.

Function: int fputs (const char *s, FILE *stream)
The function 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.

Function: int puts (const char *s)
The 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.");

Function: int putw (int w, FILE *stream)
This function writes the word w (that is, an int) to stream. It is provided for compatibility with SVID, but we recommend you use fwrite instead (see section Block Input/Output).

Character Input

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.

Function: int fgetc (FILE *stream)
This function reads the next character as an 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.

Function: int getc (FILE *stream)
This is just like 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.

Function: int getchar (void)
The 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);
    }
}

Function: int getw (FILE *stream)
This function reads a word (that is, an 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.

Line-Oriented Input

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

Function: ssize_t getline (char **lineptr, size_t *n, FILE *stream)
This function reads an entire line from stream, storing the text (including the newline and a terminating null character) in a buffer and storing the buffer address in *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.

Function: ssize_t getdelim (char **lineptr, size_t *n, int delimiter, FILE *stream)
This function is like 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);
}

Function: char * fgets (char *s, int count, FILE *stream)
The 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.

Deprecated function: char * gets (char *s)
The function 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.

Unreading

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.

What Unreading Means

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

Using ungetc To Do Unreading

The function to unread a character is called ungetc, because it reverses the action of getc.

Function: int ungetc (int c, FILE *stream)
The 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);
}

Block Input/Output

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

Function: size_t fread (void *data, size_t size, size_t count, FILE *stream)
This function reads up to count objects of size size into the array data, from the stream stream. It returns the number of objects actually read, which might be less than count if a read error occurs or the end of the file is reached. This function returns a value of zero (and doesn't read anything) if either size or count is zero.

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.

Function: size_t fwrite (const void *data, size_t size, size_t count, FILE *stream)
This function writes up to count objects of size size from the array data, to the stream stream. The return value is normally count, if the call succeeds. Any other value indicates some sort of error, such as running out of space.

Formatted Output

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.

Formatted Output Basics

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.

Output Conversion Syntax

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:

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.

Table of Output Conversions

Here is a table summarizing what all the different conversions do:

`%d', `%i'
Print an integer as a signed decimal number. See section Integer Conversions, for details. `%d' and `%i' are synonymous for output, but are different when used with scanf for input (see section Table of Input Conversions).
`%o'
Print an integer as an unsigned octal number. See section Integer Conversions, for details.
`%u'
Print an integer as an unsigned decimal number. See section Integer Conversions, for details.
`%x', `%X'
Print an integer as an unsigned hexadecimal number. `%x' uses lower-case letters and `%X' uses upper-case. See section Integer Conversions, for details.
`%f'
Print a floating-point number in normal (fixed-point) notation. See section Floating-Point Conversions, for details.
`%e', `%E'
Print a floating-point number in exponential notation. `%e' uses lower-case letters and `%E' uses upper-case. See section Floating-Point Conversions, for details.
`%g', `%G'
Print a floating-point number in either normal or exponential notation, whichever is more appropriate for its magnitude. `%g' uses lower-case letters and `%G' uses upper-case. See section Floating-Point Conversions, for details.
`%c'
Print a single character. See section Other Output Conversions.
`%s'
Print a string. See section Other Output Conversions.
`%p'
Print the value of a pointer. See section Other Output Conversions.
`%n'
Get the number of characters printed so far. See section Other Output Conversions. Note that this conversion specification never produces any output.
`%m'
Print the string corresponding to the value of errno. (This is a GNU extension.) See section Other Output Conversions.
`%%'
Print a literal `%' character. 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.

Integer Conversions

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:

`-'
Left-justify the result in the field (instead of the normal right-justification).
`+'
For the signed `%d' and `%i' conversions, print a plus sign if the value is positive.
` '
For the signed `%d' and `%i' conversions, if the result doesn't start with a plus or minus sign, prefix it with a space character instead. Since the `+' flag ensures that the result includes a sign, this flag is ignored if you supply both of them.
`#'
For the `%o' conversion, this forces the leading digit to be `0', as if by increasing the precision. For `%x' or `%X', this prefixes a leading `0x' or `0X' (respectively) to the result. This doesn't do anything useful for the `%d', `%i', or `%u' conversions. Using this flag produces output which can be parsed by the strtoul function (see section Parsing of Integers) and scanf with the `%i' conversion (see section Numeric Input Conversions).
`''
Separate the digits into groups as specified by the locale specified for the LC_NUMERIC category; see section Generic Numeric Formatting Parameters. This flag is a GNU extension.
`0'
Pad the field with zeros instead of spaces. The zeros are placed after any indication of sign or base. This flag is ignored if the `-' flag is also specified, or if a precision is specified.

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:

`h'
Specifies that the argument is a 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.
`l'
Specifies that the argument is a long int or unsigned long int, as appropriate. Two `l' characters is like the `L' modifier, below.
`L'
`ll'
`q'
Specifies that the argument is a 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.
`Z'
Specifies that the argument is a 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|

Floating-Point Conversions

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:

`-'
Left-justify the result in the field. Normally the result is right-justified.
`+'
Always include a plus or minus sign in the result.
` '
If the result doesn't start with a plus or minus sign, prefix it with a space instead. Since the `+' flag ensures that the result includes a sign, this flag is ignored if you supply both of them.
`#'
Specifies that the result should always include a decimal point, even if no digits follow it. For the `%g' and `%G' conversions, this also forces trailing zeros after the decimal point to be left in place where they would otherwise be removed.
`''
Separate the digits of the integer part of the result into groups as specified by the locale specified for the LC_NUMERIC category; see section Generic Numeric Formatting Parameters. This flag is a GNU extension.
`0'
Pad the field with zeros instead of spaces; the zeros are placed after any sign. This flag is ignored if the `-' flag is also specified.

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:

`L'
An uppercase `L' specifies that the argument is a 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.

Other Output Conversions

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.

Formatted Output Functions

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

Function: int printf (const char *template, ...)
The 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.

Function: int fprintf (FILE *stream, const char *template, ...)
This function is just like printf, except that the output is written to the stream stream instead of stdout.

Function: int sprintf (char *s, const char *template, ...)
This is like 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.

Function: int snprintf (char *s, size_t size, const char *template, ...)
The 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.

Dynamically Allocating Formatted Output

The functions in this section do formatted output and place the results in dynamically allocated memory.

Function: int asprintf (char **ptr, const char *template, ...)
This function is similar to 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;
}

Function: int obstack_printf (struct obstack *obstack, const char *template, ...)
This function is similar to 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).

Variable Arguments Output Functions

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

Function: int vprintf (const char *template, va_list ap)
This function is similar to printf except that, instead of taking a variable number of arguments directly, it takes an argument list pointer ap.

Function: int vfprintf (FILE *stream, const char *template, va_list ap)
This is the equivalent of fprintf with the variable argument list specified directly as for vprintf.

Function: int vsprintf (char *s, const char *template, va_list ap)
This is the equivalent of sprintf with the variable argument list specified directly as for vprintf.

Function: int vsnprintf (char *s, size_t size, const char *template, va_list ap)
This is the equivalent of snprintf with the variable argument list specified directly as for vprintf.

Function: int vasprintf (char **ptr, const char *template, va_list ap)
The vasprintf function is the equivalent of asprintf with the variable argument list specified directly as for vprintf.

Function: int obstack_vprintf (struct obstack *obstack, const char *template, va_list ap)
The 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.

Parsing a Template String

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

Function: size_t parse_printf_format (const char *template, size_t n, int *argtypes)
This function returns information about the number and types of arguments expected by the 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.

Macro: int PA_FLAG_MASK
This macro is a bitmask for the type modifier flag bits. You can write the expression (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
This specifies that the base type is int.
PA_CHAR
This specifies that the base type is int, cast to char.
PA_STRING
This specifies that the base type is char *, a null-terminated string.
PA_POINTER
This specifies that the base type is void *, an arbitrary pointer.
PA_FLOAT
This specifies that the base type is float.
PA_DOUBLE
This specifies that the base type is double.
PA_LAST
You can define additional base types for your own programs as offsets from 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
If this bit is set, it indicates that the encoded type is a pointer to the base type, rather than an immediate value. For example, `PA_INT|PA_FLAG_PTR' represents the type `int *'.
PA_FLAG_SHORT
If this bit is set, it indicates that the base type is modified with short. (This corresponds to the `h' type modifier.)
PA_FLAG_LONG
If this bit is set, it indicates that the base type is modified with long. (This corresponds to the `l' type modifier.)
PA_FLAG_LONG_LONG
If this bit is set, it indicates that the base type is modified with long long. (This corresponds to the `L' type modifier.)
PA_FLAG_LONG_DOUBLE
This is a synonym for PA_FLAG_LONG_LONG, used by convention with a base type of PA_DOUBLE to indicate a type of long double.

Example of Parsing a Template String

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;
}

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

Registering New Conversions

The function to register a new output conversion is register_printf_function, declared in `printf.h'.

Function: int register_printf_function (int spec, printf_function handler-function, printf_arginfo_function arginfo-function)
This function defines the conversion specifier character spec. Thus, if spec is '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.

Conversion Specifier Options

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

Type: struct printf_info
This structure is used to pass information about the options appearing in an instance of a conversion specifier in a printf template string to the handler and arginfo functions for that specifier. It contains the following members:

int prec
This is the precision specified. The value is -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
This is the minimum field width specified. The value is 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
This is the conversion specifier character specified. It's stored in the structure so that you can register the same handler function for multiple characters, but still have a way to tell them apart when the handler function is called.
unsigned int is_long_double
This is a boolean that is true if the `L', `ll', or `q' type modifier was specified. For integer conversions, this indicates long long int, as opposed to long double for floating point conversions.
unsigned int is_short
This is a boolean that is true if the `h' type modifier was specified.
unsigned int is_long
This is a boolean that is true if the `l' type modifier was specified.
unsigned int alt
This is a boolean that is true if the `#' flag was specified.
unsigned int space
This is a boolean that is true if the ` ' flag was specified.
unsigned int left
This is a boolean that is true if the `-' flag was specified.
unsigned int showsign
This is a boolean that is true if the `+' flag was specified.
unsigned int group
This is a boolean that is true if the `'' flag was specified.
unsigned int extra
This flag has a special meaning depending on the context. It could be used freely by the user-defined handlers but when called from the printf function this variable always contains the value 0.
wchar_t pad
This is the character to use for padding the output to the minimum field width. The value is '0' if the `0' flag was specified, and ' ' otherwise.

Defining the Output Handler

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.

Data Type: printf_function
This is the data type that a handler function should have.

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

Data Type: printf_arginfo_function
This type is used to describe functions that return information about the number and type of arguments used by a conversion specifier.

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

Formatted Input

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.

Formatted Input Basics

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.

Input Conversion Syntax

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:

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.

Table of Input Conversions

Here is a table that summarizes the various conversion specifications:

`%d'
Matches an optionally signed integer written in decimal. See section Numeric Input Conversions.
`%i'
Matches an optionally signed integer in any of the formats that the C language defines for specifying an integer constant. See section Numeric Input Conversions.
`%o'
Matches an unsigned integer written in octal radix. See section Numeric Input Conversions.
`%u'
Matches an unsigned integer written in decimal radix. See section Numeric Input Conversions.
`%x', `%X'
Matches an unsigned integer written in hexadecimal radix. See section Numeric Input Conversions.
`%e', `%f', `%g', `%E', `%G'
Matches an optionally signed floating-point number. See section Numeric Input Conversions.
`%s'
Matches a string containing only non-whitespace characters. See section String Input Conversions.
`%['
Matches a string of characters that belong to a specified set. See section String Input Conversions.
`%c'
Matches a string of one or more characters; the number of characters read is controlled by the maximum field width given for the conversion. See section String Input Conversions.
`%p'
Matches a pointer value in the same implementation-defined format used by the `%p' output conversion for printf. See section Other Input Conversions.
`%n'
This conversion doesn't read any characters; it records the number of characters read so far by this call. See section Other Input Conversions.
`%%'
This matches a literal `%' character in the input stream. No corresponding argument is used. 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.

Numeric Input Conversions

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:

`h'
Specifies that the argument is a short int * or unsigned short int *.
`l'
Specifies that the argument is a long int * or unsigned long int *. Two `l' characters is like the `L' modifier, below.
`ll'
`L'
`q'
Specifies that the argument is a 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:

`l'
Specifies that the argument is of type double *.
`L'
Specifies that the argument is of type 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.

String Input Conversions

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:

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:

`%25[1234567890]'
Matches a string of up to 25 digits.
`%25[][]'
Matches a string of up to 25 square brackets.
`%25[^ \f\n\r\t\v]'
Matches a string up to 25 characters long that doesn't contain any of the standard whitespace characters. This is slightly different from `%s', because if the input begins with a whitespace character, `%[' reports a matching failure while `%s' simply discards the initial whitespace.
`%25[a-z]'
Matches up to 25 lowercase characters.

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.

Dynamically Allocating String Conversions

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;
    }

  ...
}

Other Input Conversions

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.

Formatted Input Functions

Here are the descriptions of the functions for performing formatted input. Prototypes for these functions are in the header file `stdio.h'.

Function: int scanf (const char *template, ...)
The 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.

Function: int fscanf (FILE *stream, const char *template, ...)
This function is just like scanf, except that the input is read from the stream stream instead of stdin.

Function: int sscanf (const char *s, const char *template, ...)
This is like 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.

Variable Arguments Input Functions

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.

Function: int vscanf (const char *template, va_list ap)
This function is similar to 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).

Function: int vfscanf (FILE *stream, const char *template, va_list ap)
This is the equivalent of fscanf with the variable argument list specified directly as for vscanf.

Function: int vsscanf (const char *s, const char *template, va_list ap)
This is the equivalent of 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.

End-Of-File and Errors

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

Macro: int EOF
This macro is an integer value that is returned by a number of functions to indicate an end-of-file condition, or some other error situation. With the GNU library, EOF is -1. In other libraries, its value may be some other negative number.

Function: void clearerr (FILE *stream)
This function clears the end-of-file and error indicators for the stream stream.

The file positioning functions (see section File Positioning) also clear the end-of-file indicator for the stream.

Function: int feof (FILE *stream)
The feof function returns nonzero if and only if the end-of-file indicator for the stream stream is set.

Function: int ferror (FILE *stream)
The 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.

Text and Binary Streams

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:

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.

File Positioning

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

Function: long int ftell (FILE *stream)
This function returns the current file position of the stream stream.

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.

Function: int fseek (FILE *stream, long int offset, int whence)
The 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).

Macro: int SEEK_SET
This is an integer constant which, when used as the whence argument to the fseek function, specifies that the offset provided is relative to the beginning of the file.

Macro: int SEEK_CUR
This is an integer constant which, when used as the whence argument to the fseek function, specifies that the offset provided is relative to the current file position.

Macro: int SEEK_END
This is an integer constant which, when used as the whence argument to the fseek function, specifies that the offset provided is relative to the end of the file.

Function: void rewind (FILE *stream)
The 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
An alias for SEEK_SET.
L_INCR
An alias for SEEK_CUR.
L_XTND
An alias for SEEK_END.

Portable File-Position Functions

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:

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

Data Type: fpos_t
This is the type of an object that can encode information about the file position of a stream, for use by the functions 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.

Function: int fgetpos (FILE *stream, fpos_t *position)
This function stores the value of the file position indicator for the stream stream in the 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.

Function: int fsetpos (FILE *stream, const fpos_t position)
This function sets the file position indicator for the stream stream to the position position, which must have been set by a previous call to 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.

Stream Buffering

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.

Buffering Concepts

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

If you want to flush the buffered output at another time, call fflush, which is declared in the header file `stdio.h'.

Function: int fflush (FILE *stream)
This function causes any buffered output on stream to be delivered to the file. If stream is a null pointer, then 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.

Controlling Which Kind of Buffering

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

Function: int setvbuf (FILE *stream, char *buf, int mode, size_t size)
This function is used to specify that the stream stream should have the buffering mode mode, which can be either _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.

Macro: int _IOFBF
The value of this macro is an integer constant expression that can be used as the mode argument to the setvbuf function to specify that the stream should be fully buffered.

Macro: int _IOLBF
The value of this macro is an integer constant expression that can be used as the mode argument to the setvbuf function to specify that the stream should be line buffered.

Macro: int _IONBF
The value of this macro is an integer constant expression that can be used as the mode argument to the setvbuf function to specify that the stream should be unbuffered.

Macro: int BUFSIZ
The value of this macro is an integer constant expression that is good to use for the size argument to 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.

Function: void setbuf (FILE *stream, char *buf)
If buf is a null pointer, the effect of this function is equivalent to calling 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.

Function: void setbuffer (FILE *stream, char *buf, size_t size)
If buf is a null pointer, this function makes stream unbuffered. Otherwise, it makes stream fully buffered using buf as the buffer. The size argument specifies the length of buf.

This function is provided for compatibility with old BSD code. Use setvbuf instead.

Function: void setlinebuf (FILE *stream)
This function makes stream be line buffered, and allocates the buffer for you.

This function is provided for compatibility with old BSD code. Use setvbuf instead.

Other Kinds of Streams

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.

String Streams

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

Function: FILE * fmemopen (void *buf, size_t size, const char *opentype)
This function opens a stream that allows the access specified by the opentype argument, that reads from or writes to the buffer specified by the argument buf. This array must be at least size bytes long.

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

Function: FILE * open_memstream (char **ptr, size_t *sizeloc)
This function opens a stream for writing to a buffer. The buffer is allocated dynamically (as with 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

Obstack Streams

You can open an output stream that puts it data in an obstack. See section Obstacks.

Function: FILE * open_obstack_stream (struct obstack *obstack)
This function opens a stream for writing data into the obstack obstack. This starts an object in the obstack and makes it grow as data is written (see section Growing Objects).

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);
}

Programming Your Own Custom Streams

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.

Custom Streams and Cookies

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

Data Type: cookie_io_functions_t
This is a structure type that holds the functions that define the communications protocol between the stream and its cookie. It has the following members:

cookie_read_function_t *read
This is the function that reads data from the cookie. If the value is a null pointer instead of a function, then read operations on ths stream always return EOF.
cookie_write_function_t *write
This is the function that writes data to the cookie. If the value is a null pointer instead of a function, then data written to the stream is discarded.
cookie_seek_function_t *seek
This is the function that performs the equivalent of file positioning on the cookie. If the value is a null pointer instead of a function, calls to 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
This function performs any appropriate cleanup on the cookie when closing the stream. If the value is a null pointer instead of a function, nothing special is done to close the cookie when the stream is closed.

Function: FILE * fopencookie (void *cookie, const char *opentype, cookie_io_functions_t io-functions)
This function actually creates the stream for communicating with the cookie using the functions in the io-functions argument. The opentype argument is interpreted as for 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.

Custom Stream Hook Functions

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.

Data Type: cookie_read_function
This is the data type that the read function for a custom stream should have. If you declare the function as shown above, this is the type it will have.

Data Type: cookie_write_function
The data type of the write function for a custom stream.

Data Type: cookie_seek_function
The data type of the seek function for a custom stream.

Data Type: cookie_close_function
The data type of the close function for a custom stream.

Low-Level Input/Output

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:

Opening and Closing Files

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

Function: int open (const char *filename, int flags[, mode_t mode])
The 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
The file exists but is not readable/writable as requested by the flags argument, the file does not exist and the directory is unwritable so it cannot be created.
EEXIST
Both O_CREAT and O_EXCL are set, and the named file already exists.
EINTR
The open operation was interrupted by a signal. See section Primitives Interrupted by Signals.
EISDIR
The flags argument specified write access, and the file is a directory.
EMFILE
The process has too many files open. The maximum number of file descriptors is controlled by the RLIMIT_NOFILE resource limit; see section Limiting Resource Usage.
ENFILE
The entire system, or perhaps the file system which contains the directory, cannot support any additional open files at the moment. (This problem cannot happen on the GNU system.)
ENOENT
The named file does not exist, and O_CREAT is not specified.
ENOSPC
The directory or file system that would contain the new file cannot be extended, because there is no disk space left.
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
The file resides on a read-only file system and any of 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.

Obsolete function: int creat (const char *filename, mode_t mode)
This function is obsolete. The call:

creat (filename, mode)

is equivalent to:

open (filename, O_WRONLY | O_CREAT | O_TRUNC, mode)

Function: int close (int filedes)
The function 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
The filedes argument is not a valid file descriptor.
EINTR
The 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
When the file is accessed by NFS, these errors from 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.

Input and Output Primitives

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

Data Type: ssize_t
This data type is used to represent the sizes of blocks that can be read or written in a single operation. It is similar to size_t, but must be a signed type.

Function: ssize_t read (int filedes, void *buffer, size_t size)
The 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
Normally, when no input is immediately available, 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
The filedes argument is not a valid file descriptor, or is not open for reading.
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
For many devices, and for disk files, this error code indicates a hardware error. 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.

Function: ssize_t write (int filedes, const void *buffer, size_t size)
The 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
Normally, 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
The filedes argument is not a valid file descriptor, or is not open for writing.
EFBIG
The size of the file would become larger than the implementation can support.
EINTR
The 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
For many devices, and for disk files, this error code indicates a hardware error.
ENOSPC
The device containing the file is full.
EPIPE
This error is returned when you try to write to a pipe or FIFO that isn't open for reading by any process. When this happens, a 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.

Setting the File Position of a Descriptor

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

Function: off_t lseek (int filedes, off_t offset, int whence)
The 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
Specifies that whence is a count of characters from the beginning of the file.
SEEK_CUR
Specifies that whence is a count of characters from the current file position. This count may be positive or negative.
SEEK_END
Specifies that whence is a count of characters from the end of the file. A negative count specifies a position within the current extent of the file; a positive count specifies a position past the current end. If you set the position past the current end, and actually write data, you will extend the file with zeros up to that position.@end table The return value from 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
The filedes is not a valid file descriptor.
EINVAL
The whence argument value is not valid, or the resulting file offset is not valid. A file offset is invalid.
ESPIPE
The filedes corresponds to an object that cannot be positioned, such as a pipe, FIFO or terminal device. (POSIX.1 specifies this error only for pipes and FIFOs, but in the GNU system, you always get ESPIPE if the object is not seekable.)
The lseek function is the underlying primitive for the fseek, ftell and rewind functions, which operate on streams instead of file descriptors.
You can have multiple descriptors for the same file if you open the file more than once, or if you duplicate a descriptor with 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.
Data Type: off_t
This is an arithmetic data type used to represent file sizes. In the GNU system, this is equivalent to fpos_t or long int.
These 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
An alias for SEEK_SET.
L_INCR
An alias for SEEK_CUR.
L_XTND
An alias for SEEK_END.

Descriptors and Streams

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

Function: FILE * fdopen (int filedes, const char *opentype)
The 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.

Function: int fileno (FILE *stream)
This function returns the file descriptor associated with the stream stream. If an error is detected (for example, if the stream is not valid) or if stream does not do I/O to a file, 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
This macro has value 0, which is the file descriptor for standard input.
STDOUT_FILENO
This macro has value 1, which is the file descriptor for standard output.
STDERR_FILENO
This macro has value 2, which is the file descriptor for standard error output.

Dangers of Mixing Streams and Descriptors

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.

Linked Channels

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.

Independent Channels

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.

Cleaning Streams

On the GNU system, you can clean up any stream with fclean:

Function: int fclean (FILE *stream)
Clean up the stream stream so that its buffer is empty. If stream is doing output, force it out. If stream is doing input, give the data in the buffer back to the system, arranging to reread it.

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.

Waiting for Input or Output

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.

Data Type: fd_set
The fd_set data type represents file descriptor sets for the select function. It is actually a bit array.

Macro: int FD_SETSIZE
The value of this macro is the maximum number of file descriptors that a 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.

Macro: void FD_ZERO (fd_set *set)
This macro initializes the file descriptor set set to be the empty set.

Macro: void FD_SET (int filedes, fd_set *set)
This macro adds filedes to the file descriptor set set.

Macro: void FD_CLR (int filedes, fd_set *set)
This macro removes filedes from the file descriptor set set.

Macro: int FD_ISSET (int filedes, fd_set *set)
This macro returns a nonzero value (true) if filedes is a member of the the file descriptor set set, and zero (false) otherwise.

Next, here is the description of the select function itself.

Function: int select (int nfds, fd_set *read-fds, fd_set *write-fds, fd_set *except-fds, struct timeval *timeout)
The 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
One of the file descriptor sets specified an invalid file descriptor.
EINTR
The operation was interrupted by a signal. See section Primitives Interrupted by Signals.
EINVAL
The timeout argument is invalid; one of the components is negative or too large.

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.

Control Operations on Files

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.

Function: int fcntl (int filedes, int command, ...)
The 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
Duplicate the file descriptor (return another file descriptor pointing to the same open file). See section Duplicating Descriptors.
F_GETFD
Get flags associated with the file descriptor. See section File Descriptor Flags.
F_SETFD
Set flags associated with the file descriptor. See section File Descriptor Flags.
F_GETFL
Get flags associated with the open file. See section File Status Flags.
F_SETFL
Set flags associated with the open file. See section File Status Flags.
F_GETLK
Get a file lock. See section File Locks.
F_SETLK
Set or clear a file lock. See section File Locks.
F_SETLKW
Like F_SETLK, but wait for completion. See section File Locks.
F_GETOWN
Get process or process group ID to receive SIGIO signals. See section Interrupt-Driven Input.
F_SETOWN
Set process or process group ID to receive SIGIO signals. See section Interrupt-Driven Input.

Duplicating Descriptors

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

Function: int dup (int old)
This function copies descriptor old to the first available descriptor number (the first number not currently open). It is equivalent to fcntl (old, F_DUPFD, 0).

Function: int dup2 (int old, int new)
This function copies the descriptor old to descriptor number new.

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.

Macro: int F_DUPFD
This macro is used as the command argument to 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
The old argument is invalid.
EINVAL
The next-filedes argument is invalid.
EMFILE
There are no more file descriptors available--your program is already using the maximum. In BSD and GNU, the maximum is controlled by a resource limit that can be changed; see section Limiting Resource Usage, for more information about the 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

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

Macro: int F_GETFD
This macro is used as the command argument to 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
The filedes argument is invalid.

Macro: int F_SETFD
This macro is used as the command argument to 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.

Macro: int FD_CLOEXEC
This flag specifies that the file descriptor should be closed when an 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 the FD_CLOEXEC flag of desc if value is nonzero,
   or clear the flag if value is 0.
   Return 0 on success, or -1 on error with errno set. */

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

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.

The symbols in this section are defined in the header file `fcntl.h'.

File Access Modes

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.

Macro: int O_RDONLY
Open the file for read access.

Macro: int O_WRONLY
Open the file for write access.

Macro: int O_RDWR
Open the file for both reading and writing.

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.

Macro: int O_READ
Open the file for reading. Same as O_RDWR; only defined on GNU.

Macro: int O_WRITE
Open the file for reading. Same as O_WRONLY; only defined on GNU.

Macro: int O_EXEC
Open the file for executing. 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.

Macro: int O_ACCMODE
This macro stands for a mask that can be bitwise-ANDed with the file status flag value to produce a value representing the file access mode. The mode will be O_RDONLY, O_WRONLY, or O_RDWR. (In the GNU system it could also be zero, and it never includes the O_EXEC bit.)

Open-time Flags

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.

Here are the file name translation flags.

Macro: int O_CREAT
If set, the file will be created if it doesn't already exist.

Macro: int O_EXCL
If both 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.

Macro: int O_NONBLOCK
This prevents 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.

Macro: int O_NOCTTY
If the named file is a terminal device, don't make it the controlling terminal for the process. See section Job Control, for information about what it means to be the controlling terminal.

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.

Macro: int O_IGNORE_CTTY
Do not recognize the named file as the controlling terminal, even if it refers to the process's existing controlling terminal device. Operations on the new file descriptor will never induce job control signals. See section Job Control.

Macro: int O_NOLINK
If the named file is a symbolic link, open the link itself instead of the file it refers to. (fstat on the new file descriptor will return the information returned by lstat on the link's name.)

Macro: int O_NOTRANS
If the named file is specially translated, do not invoke the translator. Open the bare file the translator itself sees.

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.

Macro: int O_TRUNC
Truncate the file to zero length. This option is only useful for regular files, not special files such as directories or FIFOs. POSIX.1 requires that you open the file for writing to use 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.

Macro: int O_SHLOCK
Acquire a shared lock on the file, as with 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.

Macro: int O_EXLOCK
Acquire an exclusive lock on the file, as with flock. See section File Locks. This is atomic like O_SHLOCK.

I/O Operating Modes

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.

Macro: int O_APPEND
The bit that enables append mode for the file. If set, then all 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.

Macro: int O_NONBLOCK
The bit that enables nonblocking mode for the file. If this bit is set, 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.

Macro: int O_NDELAY
This is an obsolete name for 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.

Macro: int O_ASYNC
The bit that enables asynchronous input mode. If set, then SIGIO signals will be generated when input is available. See section Interrupt-Driven Input.

Asynchronous input mode is a BSD feature.

Macro: int O_FSYNC
The bit that enables synchronous writing for the file. If set, each write call will make sure the data is reliably stored on disk before returning.

Synchronous writing is a BSD feature.

Macro: int O_SYNC
This is another name for O_FSYNC. They have the same value.

Macro: int O_NOATIME
If this bit is set, 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.

Getting and Setting File Status Flags

The fcntl function can fetch or change file status flags.

Macro: int F_GETFL
This macro is used as the command argument to 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
The filedes argument is invalid.

Macro: int F_SETFL
This macro is used as the command argument to 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 the O_NONBLOCK flag of desc if value is nonzero,
   or clear the flag if value is 0.
   Return 0 on success, or -1 on error with errno set. */

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);
}

File Locks

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

Data Type: struct flock
This structure is used with the fcntl function to describe a file lock. It has these members:

short int l_type
Specifies the type of the lock; one of F_RDLCK, F_WRLCK, or F_UNLCK.
short int l_whence
This corresponds to the whence argument to 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
This specifies the offset of the start of the region to which the lock applies, and is given in bytes relative to the point specified by l_whence member.
off_t l_len
This specifies the length of the region to be locked. A value of 0 is treated specially; it means the region extends to the end of the file.
pid_t l_pid
This field is the process ID (see section Process Creation Concepts) of the process holding the lock. It is filled in by calling fcntl with the F_GETLK command, but is ignored when making a lock.

Macro: int F_GETLK
This macro is used as the command argument to 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
The filedes argument is invalid.
EINVAL
Either the lockp argument doesn't specify valid lock information, or the file associated with filedes doesn't support locks.

Macro: int F_SETLK
This macro is used as the command argument to 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
The lock cannot be set because it is blocked by an existing lock on the file. Some systems use 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
Either: the filedes argument is invalid; you requested a read lock but the filedes is not open for read access; or, you requested a write lock but the filedes is not open for write access.
EINVAL
Either the lockp argument doesn't specify valid lock information, or the file associated with filedes doesn't support locks.
ENOLCK
The system has run out of file lock resources; there are already too many file locks in place. Well-designed file systems never report this error, because they have no limitation on the number of locks. However, you must still take account of the possibility of this error, as it could result from network access to a file system on another machine.

Macro: int F_SETLKW
This macro is used as the command argument to 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
The function was interrupted by a signal while it was waiting. See section Primitives Interrupted by Signals.
EDEADLK
The specified region is being locked by another process. But that process is waiting to lock a region which the current process has locked, so waiting for the lock would result in deadlock. The system does not guarantee that it will detect all such conditions, but it lets you know if it notices one.

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
This macro is used to specify a read (or shared) lock.
F_WRLCK
This macro is used to specify a write (or exclusive) lock.
F_UNLCK
This macro is used to specify that the region is unlocked.

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.

Interrupt-Driven Input

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

Macro: int F_GETOWN
This macro is used as the command argument to 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
The filedes argument is invalid.

Macro: int F_SETOWN
This macro is used as the command argument to 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
The filedes argument is invalid.
ESRCH
There is no process or process group corresponding to pid.

File System Interface

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.

Working Directory

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

Function: char * getcwd (char *buffer, size_t size)
The 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
The size argument is zero and buffer is not a null pointer.
ERANGE
The size argument is less than the length of the working directory name. You need to allocate a bigger array and try again.
EACCES
Permission to read or search a component of the file name was denied.

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.

Function: char * getwd (char *buffer)
This is similar to 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.

Function: int chdir (const char *filename)
This function is used to set the process's working directory to filename.

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.

Accessing Directories

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.

Format of a Directory Entry

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

Data Type: struct dirent
This is a structure type used to return information about directory entries. It contains the following fields:

char d_name[]
This is the null-terminated file name component. This is the only field you can count on in all POSIX systems.
ino_t d_fileno
This is the file serial number. For BSD compatibility, you can also refer to this member as 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
This is the length of the file name, not including the terminating null character. Its type is unsigned char because that is the integer type of the appropriate size
unsigned char d_type
This is the type of the file, possibly unknown. The following constants are defined for its value:
DT_UNKNOWN
The type is unknown. On some systems this is the only value returned.
DT_REG
A regular file.
DT_DIR
A directory.
DT_FIFO
A named pipe, or FIFO. See section FIFO Special Files.
DT_SOCK
A local-domain socket.
DT_CHR
A character device.
DT_BLK
A block device.
This member is a BSD extension. Each value except DT_UNKNOWN corresponds to the file type bits in the st_mode member of struct statbuf. These two macros convert between d_type values and st_mode values:
Function: int IFTODT (mode_t mode)
This returns the d_type value corresponding to mode.
Function: mode_t DTTOIF (int dirtype)
This returns the 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.

Opening a Directory Stream

This section describes how to open a directory stream. All the symbols are declared in the header file `dirent.h'.

Data Type: DIR
The 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.

Function: DIR * opendir (const char *dirname)
The 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: