   This file documents the GNU C library.

   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
Library Reference Manual', for Version 2.00 Beta.

   Copyright (C) 1993, '94, '95, '96 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 translation of the section
entitled "GNU Library General Public License" must be approved for
accuracy by the Foundation.

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

   You can use the `fgetgrent' function to read group entries from a
particular file.

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

 - Function: int fgetgrent_r (FILE *STREAM, struct group *RESULT_BUF,
          char *BUFFER, size_t BUFLEN, struct group **RESULT)
     This function is similar to `fgetgrent' in that it reads the next
     user entry from STREAM.  But the result is returned in the
     structure pointed to by RESULT_BUF.  The first BUFLEN bytes of the
     additional buffer pointed to by BUFFER are used to contain
     additional information, normally strings which are pointed to by
     the elements of the result structure.

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

     If the function returns zero RESULT points to the structure with
     the wanted data (normally this is in RESULT_BUF).  If errors
     occured the return value is non-zero and RESULT contains a null
     pointer.

   The way to scan all the entries in the group database is with
`setgrent', `getgrent', and `endgrent'.

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

 - 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: int getgrent_r (struct group *RESULT_BUF, char *BUFFER,
          size_t BUFLEN, struct group **RESULT)
     This function is similar to `getgrent' in that it returns the next
     entry from the stream initialized by `setgrent'.  But in contrast
     to the `getgrent' function this function is reentrant since the
     result is placed in the user supplied structure pointed to by
     RESULT_BUF.  Additional data, normally the strings pointed to by
     the elements of the result structure, are placed in the additional
     buffer or length BUFLEN starting at BUFFER.

     If the function returns zero RESULT points to the structure with
     the wanted data (normally this is in RESULT_BUF).  If errors
     occured the return value is non-zero and RESULT contains a null
     pointer.

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

Netgroup Database
=================

Netgroup Data
-------------

   Sometimes it is useful group users according to other criterias like
the ones used in the Group Database.  E.g., it is useful to
associate a certain group of users with a certain machine.  On the
other hand grouping of host names is not supported so far.

   In Sun Microsystems SunOS appeared a new kind of database, the
netgroup database.  It allows to group hosts, users, and domain freely,
giving them individual names.  More concrete: a netgroup is a list of
triples consisting of a host name, a user name, and a domain name,
where any of the entries can be a wildcard entry, matching all inputs.
A last possibility is that names of other netgroups can also be given
in the list specifying a netgroup.  So one can construct arbitrary
hierachies without loops.

   Sun's implementation allows netgroups only for the `nis' or
`nisplus' service Services in the NSS configuration..  The
implementation in the GNU C library has no such restriction.  An entry
in either of the input services must have the following form:

     GROUPNAME ( GROUPNAME | `('HOSTNAME`,'USERNAME`,'`domainname'`)' )+

   Any of the fields in the triple can be empty which means anything
matches.  While describing the functions we will see that the opposite
case is useful as well.  I.e., there may be entries which will not
match any input.  For entries like a name consisting of the single
character `-' shall be used.

Looking up one Netgroup
-----------------------

   The lookup functions for netgroups are a bit different to all other
system database handling functions.  Since a single netgroup can contain
many entries a two-step process is needed.  First a single netgroup is
selected and then one can iterate over all entries in this netgroup.
These functions are declared in `netdb.h'.

 - Function: int setnetgrent (const char *NETGROUP)
     A call to this function initializes the internal state of the
     library to allow following calls of the `getnetgrent' iterate over
     all entries in the netgroup with name NETGROUP.

     When the call is successful (i.e., when a netgroup with this name
     exist) the return value is `1'.  When the return value is `0' no
     netgroup of this name is known or some other error occured.

   It is important to remember that there is only one single state for
iterating the netgroups.  Even if the programmer uses the
`getnetgrent_r' function the result is not really reentrant since
always only one single netgroup at a time can be processed.  If the
program needs to process more than one netgroup simultaneously she must
protect this by using external locking.  This problem was introduced in
the original netgroups implementation in SunOS and since we must stay
compatible it is not possible to change this.

   Some other functions also use the netgroups state.  Currently these
are the `innetgr' function and parts of the implementation of the
`compat' service part of the NSS implementation.

 - Function: int getnetgrent (char **HOSTP, char **USERP, char
          **DOMAINP)
     This function returns the next unprocessed entry of the currently
     selected netgroup.  The string pointers, which addresses are
     passed in the arguments HOSTP, USERP, and DOMAINP, will contain
     after a successful call pointers to appropriate strings.  If the
     string in the next entry is empty the pointer has the value `NULL'.
     The returned string pointers are only valid unless no of the
     netgroup related functions are called.

     The return value is `1' if the next entry was successfully read.  A
     value of `0' means no further entry exist or internal errors
     occured.

 - Function: int getnetgrent_r (char **HOSTP, char **USERP, char
          **DOMAINP, char *BUFFER, int BUFLEN)
     This function is similar to `getnetgrent' with only one exception:
     the strings the three string pointers HOSTP, USERP, and DOMAINP
     point to, are placed in the buffer of BUFLEN bytes starting at
     BUFFER.  This means the returned values are valid even after other
     netgroup related functions are called.

     The return value is `1' if the next entry was successfully read and
     the buffer contains enough room to place the strings in it.  `0' is
     returned in case no more entries are found, the buffer is too
     small, or internal errors occured.

     This function is a GNU extension.  The original implementation in
     the SunOS libc does not provide this function.

 - Function: void endnetgrent (void)
     This function free all buffers which were allocated to process the
     last selected netgroup.  As a result all string pointers returned
     by calls to `getnetgrent' are invalid afterwards.

Testing for Netgroup Membership
-------------------------------

   It is often not necessary to scan the whole netgroup since often the
only interesting question is whether a given entry is part of the
selected netgroup.

 - Function: int innetgr (const char *NETGROUP, const char *HOST, const
          char *USER, const char *DOMAIN)
     This function tests whether the triple specified by the parameters
     HOSTP, USERP, and DOMAINP is part of the netgroup NETGROUP.  Using
     this function has the advantage that

       1. no other netgroup function can use the global netgroup state
          since internal locking is used and

       2. the function is implemented more efficiently than successive
          calls to the other `set'/`get'/`endnetgrent' functions.

     Any of the pointers HOSTP, USERP, and DOMAINP can be `NULL' which
     means any value is excepted in this position.  This is also true
     for the name `-' which should not match any other string otherwise.

     The return value is `1' if an entry matching the given triple is
     found in the netgroup.  The return value is `0' if the netgroup
     itself is not found, the netgroup does not contain the triple or
     internal errors occured.

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.
The host name should always be a fully qualified domain
name, like `crispy-wheats-n-chicken.ai.mit.edu', not a simple name like
just `crispy-wheats-n-chicken'.

   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 "host ID" of the machine the program is
     running on.  By convention, this is usually the primary Internet
     address of that machine, converted to a `long int'.  However, some
     systems it is a meaningless but unique number which is hard-coded
     for each machine.

 - Function: int sethostid (long int ID)
     The `sethostid' function sets the "host ID" 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.

    `ENOSYS'
          The operating system does not support setting the host ID.
          On some systems, the host ID is a meaningless but unique
          number hard-coded for each machine.

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.

          Some systems provide a mechanism to interrogate the kernel
          directly for this information.  On systems without such a
          mechanism, 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'.  For example, it
          might be one of these:

               `"sparc-sun"', `"i386-ANYTHING"', `"m68k-hp"',
               `"m68k-sony"', `"m68k-sun"', `"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.  In BSD and GNU,
     this is controlled by the `RLIMIT_NPROC' resource limit; see
     Limits on Resources..

 - Macro: int OPEN_MAX
     If defined, the unvarying maximum number of files that a single
     process can have open simultaneously.  In BSD and GNU, this is
     controlled by the `RLIMIT_NOFILE' resource limit; see Limits on Resources..

 - 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
     repetitions, 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_EQUIV_CLASS_MAX'
     Inquire about the maximum number of weights that can be assigned
     to an entry of the `LC_COLLATE' category `order' keyword in a
     locale definition.  The GNU C library does not presently support
     locale definitions.

`_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.

`_SC_PAGESIZE'
     Inquire about the virtual memory page size of the machine.
     `getpagesize' returns the same value.

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

Using `pathconf'
================

   When your machine allows different files to have different values
for a file system parameter, you can use the functions in this section
to find out the value that applies to any particular file.

   These functions and the associated constants for the PARAMETER
argument are declared in the header file `unistd.h'.

 - Function: long int pathconf (const char *FILENAME, int PARAMETER)
     This function is used to inquire about the limits that apply to
     the file named FILENAME.

     The PARAMETER argument should be one of the `_PC_' constants
     listed below.

     The normal return value from `pathconf' 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.  In the former case,
     `errno' is not set, while in the latter case, `errno' is set to
     indicate the cause of the problem.  So the only way to use this
     function robustly is to store `0' into `errno' just before calling
     it.

     Besides the usual file name errors (see File Name Errors.),
     the following error condition is defined for this function:

    `EINVAL'
          The value of PARAMETER is invalid, or the implementation
          doesn't support the PARAMETER for the specific file.

 - Function: long int fpathconf (int FILEDES, int PARAMETER)
     This is just like `pathconf' except that an open file descriptor
     is used to specify the file for which information is requested,
     instead of a file name.

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

    `EBADF'
          The FILEDES argument is not a valid file descriptor.

    `EINVAL'
          The value of PARAMETER is invalid, or the implementation
          doesn't support the PARAMETER for the specific file.

   Here are the symbolic constants that you can use as the PARAMETER
argument to `pathconf' and `fpathconf'.  The values are all integer
constants.

`_PC_LINK_MAX'
     Inquire about the value of `LINK_MAX'.

`_PC_MAX_CANON'
     Inquire about the value of `MAX_CANON'.

`_PC_MAX_INPUT'
     Inquire about the value of `MAX_INPUT'.

`_PC_NAME_MAX'
     Inquire about the value of `NAME_MAX'.

`_PC_PATH_MAX'
     Inquire about the value of `PATH_MAX'.

`_PC_PIPE_BUF'
     Inquire about the value of `PIPE_BUF'.

`_PC_CHOWN_RESTRICTED'
     Inquire about the value of `_POSIX_CHOWN_RESTRICTED'.

`_PC_NO_TRUNC'
     Inquire about the value of `_POSIX_NO_TRUNC'.

`_PC_VDISABLE'
     Inquire about the value of `_POSIX_VDISABLE'.

Utility Program Capacity Limits
===============================

   The POSIX.2 standard specifies certain system limits that you can
access through `sysconf' that apply to utility behavior rather than the
behavior of the library or the operating system.

   The GNU C library defines macros for these limits, and `sysconf'
returns values for them if you ask; but these values convey no
meaningful information.  They are simply the smallest values that
POSIX.2 permits.

 - Macro: int BC_BASE_MAX
     The largest value of `obase' that the `bc' utility is guaranteed
     to support.

 - Macro: int BC_SCALE_MAX
     The largest value of `scale' that the `bc' utility is guaranteed
     to support.

 - Macro: int BC_DIM_MAX
     The largest number of elements in one array that the `bc' utility
     is guaranteed to support.

 - Macro: int BC_STRING_MAX
     The largest number of characters in one string constant that the
     `bc' utility is guaranteed to support.

 - Macro: int BC_DIM_MAX
     The largest number of elements in one array that the `bc' utility
     is guaranteed to support.

 - Macro: int COLL_WEIGHTS_MAX
     The largest number of weights that can necessarily be used in
     defining the collating sequence for a locale.

 - Macro: int EXPR_NEST_MAX
     The maximum number of expressions that can be nested within
     parenthesis by the `expr' utility.

 - Macro: int LINE_MAX
     The largest text line that the text-oriented POSIX.2 utilities can
     support.  (If you are using the GNU versions of these utilities,
     then there is no actual limit except that imposed by the available
     virtual memory, but there is no way that the library can tell you
     this.)

 - Macro: int EQUIV_CLASS_MAX
     The maximum number of weights that can be assigned to an entry of
     the `LC_COLLATE' category `order' keyword in a locale definition.
     The GNU C library does not presently support locale definitions.