   This file documents the GNU C library.

   This is Edition 0.03, last updated 19 May 1993, of
`The GNU C Library Reference Manual', for Version 1.06 Beta.

   Copyright (C) 1993 Free Software Foundation, Inc.

   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 translations of the section
entitled "GNU Library General Public License" must be approved for
accuracy by the Foundation.

Setuid Program Example
======================

   Here's an example showing how to set up a program that changes its
effective user ID.

   This is part of a game program called `caber-toss' that manipulates
a file `scores' that should be writable only by the game program
itself.  The program assumes that its executable file will be installed
with the set-user-ID bit set and owned by the same user as the `scores'
file.  Typically, a system administrator will set up an account like
`games' for this purpose.

   The executable file is given mode `4755', so that doing an `ls -l'
on it produces output like:

     -rwsr-xr-x   1 games    184422 Jul 30 15:17 caber-toss

The set-user-ID bit shows up in the file modes as the `s'.

   The scores file is given mode `644', and doing an `ls -l' on it
shows:

     -rw-r--r--  1 games           0 Jul 31 15:33 scores

   Here are the parts of the program that show how to set up the changed
user ID.  This program is conditionalized so that it makes use of the
saved IDs feature if it is supported, and otherwise uses `setreuid' to
swap the effective and real user IDs.

     #include <stdio.h>
     #include <sys/types.h>
     #include <unistd.h>
     #include <stdlib.h>

     /* Save the effective and real UIDs. */

     static uid_t euid, ruid;

     /* Restore the effective UID to its original value. */

     void
     do_setuid (void)
     {
       int status;

     #ifdef _POSIX_SAVED_IDS
       status = setuid (euid);
     #else
       status = setreuid (ruid, euid);
     #endif
       if (status < 0) {
         fprintf (stderr, "Couldn't set uid.\n");
         exit (status);
         }
     }

     /* Set the effective UID to the real UID. */

     void
     undo_setuid (void)
     {
       int status;

     #ifdef _POSIX_SAVED_IDS
       status = setuid (ruid);
     #else
       status = setreuid (euid, ruid);
     #endif
       if (status < 0) {
         fprintf (stderr, "Couldn't set uid.\n");
         exit (status);
         }
     }

     /* Main program. */

     int
     main (void)
     {
       /* Save the real and effective user IDs.  */
       ruid = getuid ();
       euid = geteuid ();
       undo_setuid ();

       /* Do the game and record the score.  */
       ...
     }

   Notice how the first thing the `main' function does is to set the
effective user ID back to the real user ID.  This is so that any other
file accesses that are performed while the user is playing the game use
the real user ID for determining permissions.  Only when the program
needs to open the scores file does it switch back to the original
effective user ID, like this:

     /* Record the score. */

     int
     record_score (int score)
     {
       FILE *stream;
       char *myname;

       /* Open the scores file. */
       do_setuid ();
       stream = fopen (SCORES_FILE, "a");
       undo_setuid ();

       /* Write the score to the file. */
       if (stream)
         {
           myname = cuserid (NULL);
           if (score < 0)
             fprintf (stream, "%10s: Couldn't lift the caber.\n", myname);
           else
             fprintf (stream, "%10s: %d feet.\n", myname, score);
           fclose (stream);
           return 0;
         }
       else
         return -1;
     }

Tips for Writing Setuid Programs
================================

   It is easy for setuid programs to give the user access that isn't
intended--in fact, if you want to avoid this, you need to be careful.
Here are some guidelines for preventing unintended access and
minimizing its consequences when it does occur:

   * Don't have `setuid' programs with privileged user IDs such as
     `root' unless it is absolutely necessary.  If the resource is
     specific to your particular program, it's better to define a new,
     nonprivileged user ID or group ID just to manage that resource.

   * Be cautious about using the `system' and `exec' functions in
     combination with changing the effective user ID.  Don't let users
     of your program execute arbitrary programs under a changed user ID.
     Executing a shell is especially bad news.  Less obviously, the
     `execlp' and `execvp' functions are a potential risk (since the
     program they execute depends on the user's `PATH' environment
     variable).

     If you must `exec' another program under a changed ID, specify an
     absolute file name (see File Name Resolution.) for the
     executable, and make sure that the protections on that executable
     and *all* containing directories are such that ordinary users
     cannot replace it with some other program.

   * Only use the user ID controlling the resource in the part of the
     program that actually uses that resource.  When you're finished
     with it, restore the effective user ID back to the actual user's
     user ID. See Enable/Disable Setuid.

   * If the `setuid' part of your program needs to access other files
     besides the controlled resource, it should verify that the real
     user would ordinarily have permission to access those files.  You
     can use the `access' function (see Access Permission.) to
     check this; it uses the real user and group IDs, rather than the
     effective IDs.

Identifying Who Logged In
=========================

   You can use the functions listed in this section to determine the
login name of the user who is running a process, and the name of the
user who logged in the current session.  See also the function `getuid'
and friends (see Reading Persona.).

   The `getlogin' function is declared in `unistd.h', while `cuserid'
and `L_cuserid' are declared in `stdio.h'.

 -- Function: char * getlogin (void)
     The `getlogin' function returns a pointer to a string containing
     the name of the user logged in on the controlling terminal of the
     process, or a null pointer if this information cannot be
     determined.  The string is statically allocated and might be
     overwritten on subsequent calls to this function or to `cuserid'.

 -- Function: char * cuserid (char *STRING)
     The `cuserid' function returns a pointer to a string containing a
     user name associated with the effective ID of the process.  If
     STRING is not a null pointer, it should be an array that can hold
     at least `L_cuserid' characters; the string is returned in this
     array.  Otherwise, a pointer to a string in a static area is
     returned. This string is statically allocated and might be
     overwritten on subsequent calls to this function or to `getlogin'.

 -- Macro: int L_cuserid
     An integer constant that indicates how long an array you might
     need to store a user name.

   These functions let your program identify positively the user who is
running or the user who logged in this session.  (These can differ when
setuid programs are involved; see Process Persona.)  The user cannot
do anything to fool these functions.

   For most purposes, it is more useful to use the environment variable
`LOGNAME' to find out who the user is.  This is more flexible precisely
because the user can set `LOGNAME' arbitrarily. See Standard Environment.

User Database
=============

   This section describes all about now to search and scan the database
of registered users.  The database itself is kept in the file
`/etc/passwd' on most systems, but on some systems a special network
server gives access to it.

The Data Structure that Describes a User
----------------------------------------

   The functions and data structures for accessing the system user
database are declared in the header file `pwd.h'.

 -- Data Type: struct passwd
     The `passwd' data structure is used to hold information about
     entries in the system user data base.  It has at least the
     following members:

    `char *pw_name'
          The user's login name.

    `char *pw_passwd.'
          The encrypted password string.

    `uid_t pw_uid'
          The user ID number.

    `gid_t pw_gid'
          The user's default group ID number.

    `char *pw_gecos'
          A string typically containing the user's real name, and
          possibly other information such as a phone number.

    `char *pw_dir'
          The user's home directory, or initial working directory.
          This might be a null pointer, in which case the
          interpretation is system-dependent.

    `char *pw_shell'
          The user's default shell, or the initial program run when the
          user logs in. This might be a null pointer, indicating that
          the system default should be used.

Looking Up One User
-------------------

   You can search the system user database for information about a
specific user using `getpwuid' or `getpwnam'.  These functions are
declared in `pwd.h'.

 -- Function: struct passwd * getpwuid (uid_t UID)
     This function returns a pointer to a statically-allocated structure
     containing information about the user whose user ID is UID.  This
     structure may be overwritten on subsequent calls to `getpwuid'.

     A null pointer value indicates there is no user in the data base
     with user ID UID.

 -- Function: struct passwd * getpwnam (const char *NAME)
     This function returns a pointer to a statically-allocated structure
     containing information about the user whose user name is NAME.
     This structure may be overwritten on subsequent calls to
     `getpwnam'.

     A null pointer value indicates there is no user named NAME.

Scanning the List of All Users
------------------------------

   This section explains how a program can read the list of all users in
the system, one user at a time.  The functions described here are
declared in `pwd.h'.

   The recommended way to scan the users is to open the user file and
then call `fgetpwent' for each successive user:

 -- Function: struct passwd * fgetpwent (FILE *STREAM)
     This function reads the next user entry from STREAM and returns a
     pointer to the entry.  The structure is statically allocated and is
     rewritten on subsequent calls to `getpwent'.  You must copy the
     contents of the structure if you wish to save the information.

     This stream must correspond to a file in the same format as the
     standard password database file.  This function comes from System
     V.

   Another way to scan all the entries in the group database is with
`setpwent', `getpwent', and `endpwent'.  But this method is less robust
than `fgetpwent', so we provide it only for compatibility with SVID.
In particular, these functions are not reentrant and are not suitable
for use in programs with multiple threads of control.

 -- Function: void setpwent (void)
     This function initializes a stream which `getpwent' uses to read
     the user database.

 -- Function: struct passwd * getpwent (void)
     The `getpwent' function reads the next entry from the stream
     initialized by `setpwent'.  It returns a pointer to the entry.  The
     structure is statically allocated and is rewritten on subsequent
     calls to `getpwent'.  You must copy the contents of the structure
     if you wish to save the information.

 -- Function: void endpwent (void)
     This function closes the internal stream used by `getpwent'.

Writing a User Entry
--------------------

 -- Function: int putpwent (const struct passwd *P, FILE *STREAM)
     This function writes the user entry `*P' to the stream STREAM, in
     the format used for the standard user database file.  The return
     value is zero on success and nonzero on failure.

     This function exists for compatibility with SVID.  We recommend
     that you avoid using it, because it makes sense only on the
     assumption that the `struct passwd' structure has no members
     except the standard ones; on a system which merges the traditional
     Unix data base with other extended information about users, adding
     an entry using this function would inevitably leave out much of
     the important information.

     The function `putpwent' is declared in `pwd.h'.

Group Database
==============

   This section describes all about how to search and scan the database
of registered groups.  The database itself is kept in the file
`/etc/group' on most systems, but on some systems a special network
service provides access to it.

The Data Structure for a Group
------------------------------

   The functions and data structures for accessing the system group
database are declared in the header file `grp.h'.

 -- Data Type: struct group
     The `group' structure is used to hold information about an entry in
     the system group database.  It has at least the following members:

    `char *gr_name'
          The name of the group.

    `gid_t gr_gid'
          The group ID of the group.

    `char **gr_mem'
          A vector of pointers to the names of users in the group.
          Each user name is a null-terminated string, and the vector
          itself is terminated by a null pointer.

Looking Up One Group
--------------------

   You can search the group database for information about a specific
group using `getgrgid' or `getgrnam'.  These functions are declared in
`grp.h'.

 -- Function: struct group * getgrgid (gid_t GID)
     This function returns a pointer to a statically-allocated structure
     containing information about the group whose group ID is GID. This
     structure may be overwritten by subsequent calls to `getgrgid'.

     A null pointer indicates there is no group with ID GID.

 -- Function: struct group * getgrnam (const char *NAME)
     This function returns a pointer to a statically-allocated structure
     containing information about the group whose group name is NAME.
     This structure may be overwritten by subsequent calls to
     `getgrnam'.

     A null pointer indicates there is no group named NAME.

Scanning the List of All Groups
-------------------------------

   This section explains how a program can read the list of all groups
in the system, one group at a time.  The functions described here are
declared in `grp.h'.

   The recommended way to scan the groups is to open the group file and
then call `fgetgrent' for each successive group:

 -- Function: struct group * fgetgrent (FILE *STREAM)
     The `fgetgrent' function reads the next entry from STREAM. It
     returns a pointer to the entry.  The structure is statically
     allocated and is rewritten on subsequent calls to `getgrent'.  You
     must copy the contents of the structure if you wish to save the
     information.

     The stream must correspond to a file in the same format as the
     standard group database file.

   Another way to scan all the entries in the group database is with
`setgrent', `getgrent', and `endgrent'.  But this method is less robust
than `fgetgrent', so we provide it only for compatibility with SVID.
In particular, these functions are not reentrant and are not suitable
for use in programs with multiple threads of control.

 -- Function: void setgrent (void)
     This function initializes a stream for reading from the group data
     base. You use this stream by calling `getgrent'.

 -- Function: struct group * getgrent (void)
     The `getgrent' function reads the next entry from the stream
     initialized by `setgrent'.  It returns a pointer to the entry.  The
     structure is statically allocated and is rewritten on subsequent
     calls to `getgrent'.  You must copy the contents of the structure
     if you wish to save the information.

 -- Function: void endgrent (void)
     This function closes the internal stream used by `getgrent'.

User and Group Database Example
===============================

   Here is an example program showing the use of the system database
inquiry functions.  The program prints some information about the user
running the program.

     #include <grp.h>
     #include <pwd.h>
     #include <sys/types.h>
     #include <unistd.h>
     #include <stdlib.h>

     int
     main (void)
     {
       uid_t me;
       struct passwd *my_passwd;
       struct group *my_group;
       char **members;

       /* Get information about the user ID.  */
       me = getuid ();
       my_passwd = getpwuid (me);
       if (!my_passwd)
         {
           printf ("Couldn't find out about user %d.\n", (int) me);
           exit (EXIT_FAILURE);
         }

       /* Print the information.  */
       printf ("I am %s.\n", my_passwd->pw_gecos);
       printf ("My login name is %s.\n", my_passwd->pw_name);
       printf ("My uid is %d.\n", (int) (my_passwd->pw_uid));
       printf ("My home directory is %s.\n", my_passwd->pw_dir);
       printf ("My default shell is %s.\n", my_passwd->pw_shell);

       /* Get information about the default group ID.  */
       my_group = getgrgid (my_passwd->pw_gid);
       if (!my_group)
         {
           printf ("Couldn't find out about group %d.\n", (int) my_passwd->pw_gid);
           exit (EXIT_FAILURE);
         }

       /* Print the information.  */
       printf ("My default group is %s (%d).\n",
     	  my_group->gr_name, (int) (my_passwd->pw_gid));
       printf ("The members of this group are:\n");
       members = my_group->gr_mem;
       while (*members)
         {
           printf ("  %s\n", *(members));
           members++;
         }

       return EXIT_SUCCESS;
     }

   Here is some output from this program:

     I am Throckmorton Snurd.
     My login name is snurd.
     My uid is 31093.
     My home directory is /home/fsg/snurd.
     My default shell is /bin/sh.
     My default group is guest (12).
     The members of this group are:
       friedman
       tami

System Information
******************

   This chapter describes functions that return information about the
particular machine that is in use--the type of hardware, the type of
software, and the individual machine's name.

Host Identification
===================

   This section explains how to identify the particular machine that
your program is running on.  The identification of a machine consists
of its Internet host name and Internet address; see Internet Namespace.

   Prototypes for these functions appear in `unistd.h'.  The shell
commands `hostname' and `hostid' work by calling them.

 -- Function: int gethostname (char *NAME, size_t SIZE)
     This function returns the name of the host machine in the array
     NAME.  The SIZE argument specifies the size of this array, in
     bytes.

     The return value is `0' on success and `-1' on failure.  In the
     GNU C library, `gethostname' fails if SIZE is not large enough;
     then you can try again with a larger array.  The following `errno'
     error condition is defined for this function:

    `ENAMETOOLONG'
          The SIZE argument is less than the size of the host name plus
          one.

     On some systems, there is a symbol for the maximum possible host
     name length: `MAXHOSTNAMELEN'.  It is defined in `sys/param.h'.
     But you can't count on this to exist, so it is cleaner to handle
     failure and try again.

     `gethostname' stores the beginning of the host name in NAME even
     if the host name won't entirely fit.  For some purposes, a
     truncated host name is good enough.  If it is, you can ignore the
     error code.

 -- Function: int sethostname (const char *NAME, size_t LENGTH)
     The `sethostname' function sets the name of the host machine to
     NAME, a string with length LENGTH.  Only privileged processes are
     allowed to do this.  Usually it happens just once, at system boot
     time.

     The return value is `0' on success and `-1' on failure. The
     following `errno' error condition is defined for this function:

    `EPERM'
          This process cannot set the host name because it is not
          privileged.

 -- Function: long int gethostid (void)
     This function returns the Internet address of the machine the
     program is running on.

 -- Function: int sethostid (long int ID)
     The `sethostid' function sets the address of the host machine to
     ID.  Only privileged processes are allowed to do this.  Usually it
     happens just once, at system boot time.

     The return value is `0' on success and `-1' on failure. The
     following `errno' error condition is defined for this function:

    `EPERM'
          This process cannot set the host name because it is not
          privileged.

Hardware/Software Type Identification
=====================================

   You can use the `uname' function to find out some information about
the type of computer your program is running on.  This function and the
associated data type are declared in the header file `sys/utsname.h'.

 -- Data Type: struct utsname
     The `utsname' structure is used to hold information returned by
     the `uname' function.  It has the following members:

    `char sysname[]'
          This is the name of the operating system in use.

    `char nodename[]'
          This is the network name of this particular computer.  In the
          GNU library, the value is the same as that returned by
          `gethostname'; see Host Identification.

    `char release[]'
          This is the current release level of the operating system
          implementation.

    `char version[]'
          This is the current version level within the release of the
          operating system.

    `char machine[]'
          This is a description of the type of hardware that is in use.

          The GNU C Library fills in this field based on the
          configuration name that was specified when building and
          installing the library.  GNU uses a three-part name to
          describe a system configuration; the three parts are CPU,
          MANUFACTURER and SYSTEM-TYPE, and they are separated with
          dashes.  Any possible combination of three names is
          potentially meaningful, but most such combinations are
          meaningless in practice and even the meaningful ones are not
          necessarily supported by any particular GNU program.

          Since the value in `machine' is supposed to describe just the
          hardware, it consists of the first two parts of the
          configuration name: `CPU-MANUFACTURER'.

          Here is a list of all the possible alternatives:

               `"i386-ANYTHING"', `"m68k-hp"', `"sparc-sun"',
               `"m68k-sun"', `"m68k-sony"', `"mips-dec"'

 -- Function: int uname (struct utsname *INFO)
     The `uname' function fills in the structure pointed to by INFO
     with information about the operating system and host machine. A
     non-negative value indicates that the data was successfully stored.

     `-1' as the value indicates an error.  The only error possible is
     `EFAULT', which we normally don't mention as it is always a
     possibility.

System Configuration Parameters
*******************************

   The functions and macros listed in this chapter give information
about configuration parameters of the operating system--for example,
capacity limits, presence of optional POSIX features, and the default
path for executable files (see String Parameters.).

General Capacity Limits
=======================

   The POSIX.1 and POSIX.2 standards specify a number of parameters that
describe capacity limitations of the system.  These limits can be fixed
constants for a given operating system, or they can vary from machine to
machine.  For example, some limit values may be configurable by the
system administrator, either at run time or by rebuilding the kernel,
and this should not require recompiling application programs.

   Each of the following limit parameters has a macro that is defined in
`limits.h' only if the system has a fixed, uniform limit for the
parameter in question.  If the system allows different file systems or
files to have different limits, then the macro is undefined; use
`sysconf' to find out the limit that applies at a particular time on a
particular machine.  See Sysconf.

   Each of these parameters also has another macro, with a name starting
with `_POSIX', which gives the lowest value that the limit is allowed
to have on *any* POSIX system.  See Minimums.

 -- Macro: int ARG_MAX
     If defined, the unvarying maximum combined length of the ARGV and
     ENVIRON arguments that can be passed to the `exec' functions.

 -- Macro: int CHILD_MAX
     If defined, the unvarying maximum number of processes that can
     exist with the same real user ID at any one time.

 -- Macro: int OPEN_MAX
     If defined, the unvarying maximum number of files that a single
     process can have open simultaneously.

 -- Macro: int STREAM_MAX
     If defined, the unvarying maximum number of streams that a single
     process can have open simultaneously.  See Opening Streams.

 -- Macro: int TZNAME_MAX
     If defined, the unvarying maximum length of a time zone name.
     See Time Zone Functions.

   These limit macros are always defined in `limits.h'.

 -- Macro: int NGROUPS_MAX
     The maximum number of supplementary group IDs that one process can
     have.

     The value of this macro is actually a lower bound for the maximum.
      That is, you can count on being able to have that many
     supplementary group IDs, but a particular machine might let you
     have even more.  You can use `sysconf' to see whether a particular
     machine will let you have more (see Sysconf.).

 -- Macro: int SSIZE_MAX
     The largest value that can fit in an object of type `ssize_t'.
     Effectively, this is the limit on the number of bytes that can be
     read or written in a single operation.

     This macro is defined in all POSIX systems because this limit is
     never configurable.

 -- Macro: int RE_DUP_MAX
     The largest number of repetitions you are guaranteed is allowed in
     the construct `\{MIN,MAX\}' in a regular expression.

     The value of this macro is actually a lower bound for the maximum.
      That is, you can count on being able to have that many
     supplementary group IDs, but a particular machine might let you
     have even more.  You can use `sysconf' to see whether a particular
     machine will let you have more (see Sysconf.).  And even the
     value that `sysconf' tells you is just a lower bound--larger
     values might work.

     This macro is defined in all POSIX.2 systems, because POSIX.2 says
     it should always be defined even if there is no specific imposed
     limit.

Overall System Options
======================

   POSIX defines certain system-specific options that not all POSIX
systems support.  Since these options are provided in the kernel, not
in the library, simply using the GNU C library does not guarantee any
of these features is supported; it depends on the system you are using.

   You can test for the availability of a given option using the macros
in this section, together with the function `sysconf'.  The macros are
defined only if you include `unistd.h'.

   For the following macros, if the macro is defined in `unistd.h',
then the option is supported.  Otherwise, the option may or may not be
supported; use `sysconf' to find out.  See Sysconf.

 -- Macro: int _POSIX_JOB_CONTROL
     If this symbol is defined, it indicates that the system supports
     job control.  Otherwise, the implementation behaves as if all
     processes within a session belong to a single process group.
     See Job Control.

 -- Macro: int _POSIX_SAVED_IDS
     If this symbol is defined, it indicates that the system remembers
     the effective user and group IDs of a process before it executes an
     executable file with the set-user-ID or set-group-ID bits set, and
     that explicitly changing the effective user or group IDs back to
     these values is permitted.  If this option is not defined, then if
     a nonprivileged process changes its effective user or group ID to
     the real user or group ID of the process, it can't change it back
     again.  See Enable/Disable Setuid.

   For the following macros, if the macro is defined in `unistd.h',
then its value indicates whether the option is supported.  A value of
`-1' means no, and any other value means yes.  If the macro is not
defined, then the option may or may not be supported; use `sysconf' to
find out.  See Sysconf.

 -- Macro: int _POSIX2_C_DEV
     If this symbol is defined, it indicates that the system has the
     POSIX.2 C compiler command, `c89'.  The GNU C library always
     defines this as `1', on the assumption that you would not have
     installed it if you didn't have a C compiler.

 -- Macro: int _POSIX2_FORT_DEV
     If this symbol is defined, it indicates that the system has the
     POSIX.2 Fortran compiler command, `fort77'.  The GNU C library
     never defines this, because we don't know what the system has.

 -- Macro: int _POSIX2_FORT_RUN
     If this symbol is defined, it indicates that the system has the
     POSIX.2 `asa' command to interpret Fortran carriage control.  The
     GNU C library never defines this, because we don't know what the
     system has.

 -- Macro: int _POSIX2_LOCALEDEF
     If this symbol is defined, it indicates that the system has the
     POSIX.2 `localedef' command.  The GNU C library never defines
     this, because we don't know what the system has.

 -- Macro: int _POSIX2_SW_DEV
     If this symbol is defined, it indicates that the system has the
     POSIX.2 commands `ar', `make', and `strip'.  The GNU C library
     always defines this as `1', on the assumption that you had to have
     `ar' and `make' to install the library, and it's unlikely that
     `strip' would be absent when those are present.

Which Version of POSIX is Supported
===================================

 -- Macro: long int _POSIX_VERSION
     This constant represents the version of the POSIX.1 standard to
     which the implementation conforms.  For an implementation
     conforming to the 1990 POSIX.1 standard, the value is the integer
     `199009L'.

     `_POSIX_VERSION' is always defined (in `unistd.h') in any POSIX
     system.

     *Usage Note:* Don't try to test whether the system supports POSIX
     by including `unistd.h' and then checking whether `_POSIX_VERSION'
     is defined.  On a non-POSIX system, this will probably fail
     because there is no `unistd.h'.  We do not know of *any* way you
     can reliably test at compilation time whether your target system
     supports POSIX or whether `unistd.h' exists.

     The GNU C compiler predefines the symbol `__POSIX__' if the target
     system is a POSIX system.  Provided you do not use any other
     compilers on POSIX systems, testing `defined (__POSIX__)' will
     reliably detect such systems.

 -- Macro: long int _POSIX2_C_VERSION
     This constant represents the version of the POSIX.2 standard which
     the library and system kernel support.  We don't know what value
     this will be for the first version of the POSIX.2 standard,
     because the value is based on the year and month in which the
     standard is officially adopted.

     The value of this symbol says nothing about the utilities
     installed on the system.

     *Usage Note:* You can use this macro to tell whether a POSIX.1
     system library supports POSIX.2 as well.  Any POSIX.1 system
     contains `unistd.h', so include that file and then test `defined
     (_POSIX2_C_VERSION)'.

Using `sysconf'
===============

   When your system has configurable system limits, you can use the
`sysconf' function to find out the value that applies to any particular
machine.  The function and the associated PARAMETER constants are
declared in the header file `unistd.h'.

Definition of `sysconf'
-----------------------

 -- Function: long int sysconf (int PARAMETER)
     This function is used to inquire about runtime system parameters.
     The PARAMETER argument should be one of the `_SC_' symbols listed
     below.

     The normal return value from `sysconf' is the value you requested.
     A value of `-1' is returned both if the implementation does not
     impose a limit, and in case of an error.

     The following `errno' error conditions are defined for this
     function:

    `EINVAL'
          The value of the PARAMETER is invalid.

Constants for `sysconf' Parameters
----------------------------------

   Here are the symbolic constants for use as the PARAMETER argument to
`sysconf'.  The values are all integer constants (more specifically,
enumeration type values).

`_SC_ARG_MAX'
     Inquire about the parameter corresponding to `ARG_MAX'.

`_SC_CHILD_MAX'
     Inquire about the parameter corresponding to `CHILD_MAX'.

`_SC_OPEN_MAX'
     Inquire about the parameter corresponding to `OPEN_MAX'.

`_SC_STREAM_MAX'
     Inquire about the parameter corresponding to `STREAM_MAX'.

`_SC_TZNAME_MAX'
     Inquire about the parameter corresponding to `TZNAME_MAX'.

`_SC_NGROUPS_MAX'
     Inquire about the parameter corresponding to `NGROUPS_MAX'.

`_SC_JOB_CONTROL'
     Inquire about the parameter corresponding to `_POSIX_JOB_CONTROL'.

`_SC_SAVED_IDS'
     Inquire about the parameter corresponding to `_POSIX_SAVED_IDS'.

`_SC_VERSION'
     Inquire about the parameter corresponding to `_POSIX_VERSION'.

`_SC_CLK_TCK'
     Inquire about the parameter corresponding to `CLOCKS_PER_SEC';
     see Basic CPU Time..

`_SC_2_C_DEV'
     Inquire about whether the system has the POSIX.2 C compiler
     command, `c89'.

`_SC_2_FORT_DEV'
     Inquire about whether the system has the POSIX.2 Fortran compiler
     command, `fort77'.

`_SC_2_FORT_RUN'
     Inquire about whether the system has the POSIX.2 `asa' command to
     interpret Fortran carriage control.

`_SC_2_LOCALEDEF'
     Inquire about whether the system has the POSIX.2 `localedef'
     command.

`_SC_2_SW_DEV'
     Inquire about whether the system has the POSIX.2 commands `ar',
     `make', and `strip'.

`_SC_BC_BASE_MAX'
     Inquire about the maximum value of `obase' in the `bc' utility.

`_SC_BC_DIM_MAX'
     Inquire about the maximum size of an array in the `bc' utility.

`_SC_BC_SCALE_MAX'
     Inquire about the maximum value of `scale' in the `bc' utility.

`_SC_BC_STRING_MAX'
     Inquire about the maximum size of a string constant in the `bc'
     utility.

`_SC_COLL_WEIGHTS_MAX'
     Inquire about the maximum number of weights that can necessarily
     be used in defining the collating sequence for a locale.

`_SC_EXPR_NEST_MAX'
     Inquire about the maximum number of expressions nested within
     parentheses when using the `expr' utility.

`_SC_LINE_MAX'
     Inquire about the maximum size of a text line that the POSIX.2 text
     utilities can handle.

`_SC_VERSION'
     Inquire about the version number of POSIX.1 that the library and
     kernel support.

`_SC_2_VERSION'
     Inquire about the version number of POSIX.2 that the system
     utilities support.

Examples of `sysconf'
---------------------

   We recommend that you first test for a macro definition for the
parameter you are interested in, and call `sysconf' only if the macro
is not defined.  For example, here is how to test whether job control
is supported:

     int
     have_job_control (void)
     {
     #ifdef _POSIX_JOB_CONTROL
       return 1;
     #else
       int value = sysconf (_SC_JOB_CONTROL);
       if (value < 0)
         /* If the system is that badly wedged,
            there's no use trying to go on.  */
         fatal (strerror (errno));
       return value;
     #endif
     }

   Here is how to get the value of a numeric limit:

     int
     get_child_max ()
     {
     #ifdef CHILD_MAX
       return CHILD_MAX;
     #else
       int value = sysconf (_SC_CHILD_MAX);
       if (value < 0)
         fatal (strerror (errno));
       return value;
     #endif
     }

Minimum Values for General Capacity Limits
==========================================

   Here are the names for the POSIX minimum upper bounds for the system
limit parameters.  The significance of these values is that you can
safely push to these limits without checking whether the particular
system you are using can go that far.

`_POSIX_ARG_MAX'
     The value of this macro is the most restrictive limit permitted by
     POSIX for the maximum combined length of the ARGV and ENVIRON
     arguments that can be passed to the `exec' functions. Its value is
     `4096'.

`_POSIX_CHILD_MAX'
     The value of this macro is the most restrictive limit permitted by
     POSIX for the maximum number of simultaneous processes per real
     user ID.  Its value is `6'.

`_POSIX_NGROUPS_MAX'
     The value of this macro is the most restrictive limit permitted by
     POSIX for the maximum number of supplementary group IDs per
     process.  Its value is `0'.

`_POSIX_OPEN_MAX'
     The value of this macro is the most restrictive limit permitted by
     POSIX for the maximum number of files that a single process can
     have open simultaneously.  Its value is `16'.

`_POSIX_SSIZE_MAX'
     The value of this macro is the most restrictive limit permitted by
     POSIX for the maximum value that can be stored in an object of type
     `ssize_t'.  Its value is `32767'.

`_POSIX_STREAM_MAX'
     The value of this macro is the most restrictive limit permitted by
     POSIX for the maximum number of streams that a single process can
     have open simultaneously.  Its value is `8'.

`_POSIX_TZNAME_MAX'
     The value of this macro is the most restrictive limit permitted by
     POSIX for the maximum length of a time zone name.  Its value is
     `3'.

`_POSIX2_RE_DUP_MAX'
     The value of this macro is the most restrictive limit permitted by
     POSIX for the numbers used in the `\{MIN,MAX\}' construct in a
     regular expression.  Its value is `255'.

Limits on File System Capacity
==============================

   The POSIX.1 standard specifies a number of parameters that describe
the limitations of the file system.  It's possible for the system to
have a fixed, uniform limit for a parameter, but this isn't the usual
case.  On most systems, it's possible for different file systems (and,
for some parameters, even different files) to have different maximum
limits.  For example, this is very likely if you use NFS to mount some
of the file systems from other machines.

   Each of the following macros is defined in `limits.h' only if the
system has a fixed, uniform limit for the parameter in question.  If the
system allows different file systems or files to have different limits,
then the macro is undefined; use `pathconf' or `fpathconf' to find out
the limit that applies to a particular file.  See Pathconf.

   Each parameter also has another macro, with a name starting with
`_POSIX', which gives the lowest value that the limit is allowed to
have on *any* POSIX system.  See File Minimums.

 -- Macro: int LINK_MAX
     The uniform system limit (if any) for the number of names for a
     given file.  See Hard Links.

 -- Macro: int MAX_CANON
     The uniform system limit (if any) for the amount of text in a line
     of input when input editing is enabled.  See Canonical or Not.

 -- Macro: int MAX_INPUT
     The uniform system limit (if any) for the total number of
     characters typed ahead as input.  See I/O Queues.

 -- Macro: int NAME_MAX
     The uniform system limit (if any) for the length of a file name
     component.

 -- Macro: int PATH_MAX
     The uniform system limit (if any) for the length of an entire file
     name (that is, the argument given to system calls such as `open').

 -- Macro: int PIPE_BUF
     The uniform system limit (if any) for the number of bytes that can
     be written atomically to a pipe.  If multiple processes are
     writing to the same pipe simultaneously, output from different
     processes might be interleaved in chunks of this size.  See
     Pipes and FIFOs.

   These are alternative macro names for some of the same information.

 -- Macro: int MAXNAMLEN
     This is the BSD name for `NAME_MAX'.  It is defined in `dirent.h'.

 -- Macro: int FILENAME_MAX
     The value of this macro is an integer constant expression that
     represents the maximum length of a file name string.  It is
     defined in `stdio.h'.

     Unlike `PATH_MAX', this macro is defined even if there is no actual
     limit imposed.  In such a case, its value is typically a very large
     number.  *This is always the case on the GNU system.*

     *Usage Note:* Don't use `FILENAME_MAX' as the size of an array in
     which to store a file name!  You can't possibly make an array that
     big!  Use dynamic allocation (see Memory Allocation.) instead.

Optional Features in File Support
=================================

   POSIX defines certain system-specific options in the system calls for
operating on files.  Some systems support these options and others do
not.  Since these options are provided in the kernel, not in the
library, simply using the GNU C library does not guarantee any of these
features is supported; it depends on the system you are using.  They can
also vary between file systems on a single machine.

   This section describes the macros you can test to determine whether a
particular option is supported on your machine.  If a given macro is
defined in `unistd.h', then its value says whether the corresponding
feature is supported.  (A value of `-1' indicates no; any other value
indicates yes.)  If the macro is undefined, it means particular files
may or may not support the feature.

   Since all the machines that support the GNU C library also support
NFS, one can never make a general statement about whether all file
systems support the `_POSIX_CHOWN_RESTRICTED' and `_POSIX_NO_TRUNC'
features.  So these names are never defined as macros in the GNU C
library.

 -- Macro: int _POSIX_CHOWN_RESTRICTED
     If this option is in effect, the `chown' function is restricted so
     that the only changes permitted to nonprivileged processes is to
     change the group owner of a file to either be the effective group
     ID of the process, or one of its supplementary group IDs.  See
     File Owner.

 -- Macro: int _POSIX_NO_TRUNC
     If this option is in effect, file name components longer than
     `NAME_MAX' generate an `ENAMETOOLONG' error.  Otherwise, file name
     components that are too long are silently truncated.

 -- Macro: unsigned char _POSIX_VDISABLE
     This option is only meaningful for files that are terminal devices.
     If it is enabled, then handling for special control characters can
     be disabled individually.  See Special Characters.

   If one of these macros is undefined, that means that the option
might be in effect for some files and not for others.  To inquire about
a particular file, call `pathconf' or `fpathconf'. See Pathconf.

Minimum Values for File System Limits
=====================================

   Here are the names for the POSIX minimum upper bounds for some of the
above parameters.  The significance of these values is that you can
safely push to these limits without checking whether the particular
system you are using can go that far.

`_POSIX_LINK_MAX'
     The most restrictive limit permitted by POSIX for the maximum
     value of a file's link count.  The value of this constant is `8';
     thus, you can always make up to eight names for a file without
     running into a system limit.

`_POSIX_MAX_CANON'
     The most restrictive limit permitted by POSIX for the maximum
     number of bytes in a canonical input line from a terminal device.
     The value of this constant is `255'.

`_POSIX_MAX_INPUT'
     The most restrictive limit permitted by POSIX for the maximum
     number of bytes in a terminal device input queue (or typeahead
     buffer). See Input Modes.  The value of this constant is `255'.

`_POSIX_NAME_MAX'
     The most restrictive limit permitted by POSIX for the maximum
     number of bytes in a file name component.  The value of this
     constant is `14'.

`_POSIX_PATH_MAX'
     The most restrictive limit permitted by POSIX for the maximum
     number of bytes in a file name.  The value of this constant is
     `255'.

`_POSIX_PIPE_BUF'
     The most restrictive limit permitted by POSIX for the maximum
     number of bytes that can be written atomically to a pipe.  The
     value of this constant is `512'.