This is libc.info, produced by makeinfo version 4.2 from libc.texinfo.

INFO-DIR-SECTION GNU libraries
START-INFO-DIR-ENTRY
* Libc: (libc).                 C library.
END-INFO-DIR-ENTRY

   This file documents the GNU C library.

   This is Edition 0.10, last updated 2001-07-06, of `The GNU C Library
Reference Manual', for Version 2.3.x.

   Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002
Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Free Software Needs Free Documentation" and
"GNU Lesser General Public License", the Front-Cover texts being (a)
(see below), and with the Back-Cover Texts being (b) (see below).  A
copy of the license is included in the section entitled "GNU Free
Documentation License".

   (a) The FSF's Front-Cover Text is:

   A GNU Manual

   (b) The FSF's Back-Cover Text is:

   You have freedom to copy and modify this GNU Manual, like GNU
software.  Copies published by the Free Software Foundation raise
funds for GNU development.


File: libc.info,  Node: Examples of Sysconf,  Prev: Constants for Sysconf,  Up: Sysconf

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
     }


File: libc.info,  Node: Minimums,  Next: Limits for Files,  Prev: Sysconf,  Up: System Configuration

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_AIO_LISTIO_MAX'
     The most restrictive limit permitted by POSIX for the maximum
     number of I/O operations that can be specified in a list I/O call.
     The value of this constant is `2'; thus you can add up to two new
     entries of the list of outstanding operations.

`_POSIX_AIO_MAX'
     The most restrictive limit permitted by POSIX for the maximum
     number of outstanding asynchronous I/O operations.  The value of
     this constant is `1'.  So you cannot expect that you can issue
     more than one operation and immediately continue with the normal
     work, receiving the notifications asynchronously.

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


File: libc.info,  Node: Limits for Files,  Next: Options for Files,  Prev: Minimums,  Up: System Configuration

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.  *Note 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.  *Note File Minimums::.

 - Macro: int LINK_MAX
     The uniform system limit (if any) for the number of names for a
     given file.  *Note 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.  *Note Canonical or Not::.

 - Macro: int MAX_INPUT
     The uniform system limit (if any) for the total number of
     characters typed ahead as input.  *Note 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.  *Note
     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 (*note Memory Allocation::) instead.


File: libc.info,  Node: Options for Files,  Next: File Minimums,  Prev: Limits for Files,  Up: System Configuration

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 that 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.  *Note
     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.  *Note 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'.  *Note Pathconf::.


File: libc.info,  Node: File Minimums,  Next: Pathconf,  Prev: Options for Files,  Up: System Configuration

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.  In most cases GNU systems do not
have these strict limitations.  The actual limit should be requested if
necessary.

`_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).  *Note 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
     `256'.

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

`SYMLINK_MAX'
     Maximum number of bytes in a symbolic link.

`POSIX_REC_INCR_XFER_SIZE'
     Recommended increment for file transfer sizes between the
     `POSIX_REC_MIN_XFER_SIZE' and `POSIX_REC_MAX_XFER_SIZE' values.

`POSIX_REC_MAX_XFER_SIZE'
     Maximum recommended file transfer size.

`POSIX_REC_MIN_XFER_SIZE'
     Minimum recommended file transfer size.

`POSIX_REC_XFER_ALIGN'
     Recommended file transfer buffer alignment.


File: libc.info,  Node: Pathconf,  Next: Utility Limits,  Prev: File Minimums,  Up: System Configuration

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 (*note 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'.

`_PC_SYNC_IO'
     Inquire about the value of `_POSIX_SYNC_IO'.

`_PC_ASYNC_IO'
     Inquire about the value of `_POSIX_ASYNC_IO'.

`_PC_PRIO_IO'
     Inquire about the value of `_POSIX_PRIO_IO'.

`_PC_SOCK_MAXBUF'
     Inquire about the value of `_POSIX_PIPE_BUF'.

`_PC_FILESIZEBITS'
     Inquire about the availability of large files on the filesystem.

`_PC_REC_INCR_XFER_SIZE'
     Inquire about the value of `POSIX_REC_INCR_XFER_SIZE'.

`_PC_REC_MAX_XFER_SIZE'
     Inquire about the value of `POSIX_REC_MAX_XFER_SIZE'.

`_PC_REC_MIN_XFER_SIZE'
     Inquire about the value of `POSIX_REC_MIN_XFER_SIZE'.

`_PC_REC_XFER_ALIGN'
     Inquire about the value of `POSIX_REC_XFER_ALIGN'.


File: libc.info,  Node: Utility Limits,  Next: Utility Minimums,  Prev: Pathconf,  Up: System Configuration

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_DIM_MAX
     The largest number of elements in one array 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_STRING_MAX
     The largest number of characters in one string constant 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.


File: libc.info,  Node: Utility Minimums,  Next: String Parameters,  Prev: Utility Limits,  Up: System Configuration

Minimum Values for Utility Limits
=================================

`_POSIX2_BC_BASE_MAX'
     The most restrictive limit permitted by POSIX.2 for the maximum
     value of `obase' in the `bc' utility.  Its value is `99'.

`_POSIX2_BC_DIM_MAX'
     The most restrictive limit permitted by POSIX.2 for the maximum
     size of an array in the `bc' utility.  Its value is `2048'.

`_POSIX2_BC_SCALE_MAX'
     The most restrictive limit permitted by POSIX.2 for the maximum
     value of `scale' in the `bc' utility.  Its value is `99'.

`_POSIX2_BC_STRING_MAX'
     The most restrictive limit permitted by POSIX.2 for the maximum
     size of a string constant in the `bc' utility.  Its value is
     `1000'.

`_POSIX2_COLL_WEIGHTS_MAX'
     The most restrictive limit permitted by POSIX.2 for the maximum
     number of weights that can necessarily be used in defining the
     collating sequence for a locale.  Its value is `2'.

`_POSIX2_EXPR_NEST_MAX'
     The most restrictive limit permitted by POSIX.2 for the maximum
     number of expressions nested within parenthesis when using the
     `expr' utility.  Its value is `32'.

`_POSIX2_LINE_MAX'
     The most restrictive limit permitted by POSIX.2 for the maximum
     size of a text line that the text utilities can handle.  Its value
     is `2048'.

`_POSIX2_EQUIV_CLASS_MAX'
     The most restrictive limit permitted by POSIX.2 for the maximum
     number of weights that can be assigned to an entry of the
     `LC_COLLATE' category `order' keyword in a locale definition.  Its
     value is `2'.  The GNU C library does not presently support locale
     definitions.


File: libc.info,  Node: String Parameters,  Prev: Utility Minimums,  Up: System Configuration

String-Valued Parameters
========================

   POSIX.2 defines a way to get string-valued parameters from the
operating system with the function `confstr':

 - Function: size_t confstr (int PARAMETER, char *BUF, size_t LEN)
     This function reads the value of a string-valued system parameter,
     storing the string into LEN bytes of memory space starting at BUF.
     The PARAMETER argument should be one of the `_CS_' symbols listed
     below.

     The normal return value from `confstr' is the length of the string
     value that you asked for.  If you supply a null pointer for BUF,
     then `confstr' does not try to store the string; it just returns
     its length.  A value of `0' indicates an error.

     If the string you asked for is too long for the buffer (that is,
     longer than `LEN - 1'), then `confstr' stores just that much
     (leaving room for the terminating null character).  You can tell
     that this has happened because `confstr' returns a value greater
     than or equal to LEN.

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

    `EINVAL'
          The value of the PARAMETER is invalid.

   Currently there is just one parameter you can read with `confstr':

`_CS_PATH'
     This parameter's value is the recommended default path for
     searching for executable files.  This is the path that a user has
     by default just after logging in.

`_CS_LFS_CFLAGS'
     The returned string specifies which additional flags must be given
     to the C compiler if a source is compiled using the
     `_LARGEFILE_SOURCE' feature select macro; *note Feature Test
     Macros::.

`_CS_LFS_LDFLAGS'
     The returned string specifies which additional flags must be given
     to the linker if a source is compiled using the
     `_LARGEFILE_SOURCE' feature select macro; *note Feature Test
     Macros::.

`_CS_LFS_LIBS'
     The returned string specifies which additional libraries must be
     linked to the application if a source is compiled using the
     `_LARGEFILE_SOURCE' feature select macro; *note Feature Test
     Macros::.

`_CS_LFS_LINTFLAGS'
     The returned string specifies which additional flags must be given
     to the lint tool if a source is compiled using the
     `_LARGEFILE_SOURCE' feature select macro; *note Feature Test
     Macros::.

`_CS_LFS64_CFLAGS'
     The returned string specifies which additional flags must be given
     to the C compiler if a source is compiled using the
     `_LARGEFILE64_SOURCE' feature select macro; *note Feature Test
     Macros::.

`_CS_LFS64_LDFLAGS'
     The returned string specifies which additional flags must be given
     to the linker if a source is compiled using the
     `_LARGEFILE64_SOURCE' feature select macro; *note Feature Test
     Macros::.

`_CS_LFS64_LIBS'
     The returned string specifies which additional libraries must be
     linked to the application if a source is compiled using the
     `_LARGEFILE64_SOURCE' feature select macro; *note Feature Test
     Macros::.

`_CS_LFS64_LINTFLAGS'
     The returned string specifies which additional flags must be given
     to the lint tool if a source is compiled using the
     `_LARGEFILE64_SOURCE' feature select macro; *note Feature Test
     Macros::.

   The way to use `confstr' without any arbitrary limit on string size
is to call it twice: first call it to get the length, allocate the
buffer accordingly, and then call `confstr' again to fill the buffer,
like this:

     char *
     get_default_path (void)
     {
       size_t len = confstr (_CS_PATH, NULL, 0);
       char *buffer = (char *) xmalloc (len);
     
       if (confstr (_CS_PATH, buf, len + 1) == 0)
         {
           free (buffer);
           return NULL;
         }
     
       return buffer;
     }


File: libc.info,  Node: Cryptographic Functions,  Next: Debugging Support,  Prev: System Configuration,  Up: Top

DES Encryption and Password Handling
************************************

   On many systems, it is unnecessary to have any kind of user
authentication; for instance, a workstation which is not connected to a
network probably does not need any user authentication, because to use
the machine an intruder must have physical access.

   Sometimes, however, it is necessary to be sure that a user is
authorized to use some service a machine provides--for instance, to log
in as a particular user id (*note Users and Groups::).  One traditional
way of doing this is for each user to choose a secret "password"; then,
the system can ask someone claiming to be a user what the user's
password is, and if the person gives the correct password then the
system can grant the appropriate privileges.

   If all the passwords are just stored in a file somewhere, then this
file has to be very carefully protected.  To avoid this, passwords are
run through a "one-way function", a function which makes it difficult to
work out what its input was by looking at its output, before storing in
the file.

   The GNU C library provides a one-way function that is compatible with
the behavior of the `crypt' function introduced in FreeBSD 2.0.  It
supports two one-way algorithms: one based on the MD5 message-digest
algorithm that is compatible with modern BSD systems, and the other
based on the Data Encryption Standard (DES) that is compatible with
Unix systems.

   It also provides support for Secure RPC, and some library functions
that can be used to perform normal DES encryption.

* Menu:

* Legal Problems::              This software can get you locked up, or worse.
* getpass::                     Prompting the user for a password.
* crypt::                       A one-way function for passwords.
* DES Encryption::              Routines for DES encryption.


File: libc.info,  Node: Legal Problems,  Next: getpass,  Up: Cryptographic Functions

Legal Problems
==============

   Because of the continuously changing state of the law, it's not
possible to provide a definitive survey of the laws affecting
cryptography.  Instead, this section warns you of some of the known
trouble spots; this may help you when you try to find out what the laws
of your country are.

   Some countries require that you have a licence to use, possess, or
import cryptography.  These countries are believed to include
Byelorussia, Burma, India, Indonesia, Israel, Kazakhstan, Pakistan,
Russia, and Saudi Arabia.

   Some countries restrict the transmission of encrypted messages by
radio; some telecommunications carriers restrict the transmission of
encrypted messages over their network.

   Many countries have some form of export control for encryption
software.  The Wassenaar Arrangement is a multilateral agreement
between 33 countries (Argentina, Australia, Austria, Belgium, Bulgaria,
Canada, the Czech Republic, Denmark, Finland, France, Germany, Greece,
Hungary, Ireland, Italy, Japan, Luxembourg, the Netherlands, New
Zealand, Norway, Poland, Portugal, the Republic of Korea, Romania, the
Russian Federation, the Slovak Republic, Spain, Sweden, Switzerland,
Turkey, Ukraine, the United Kingdom and the United States) which
restricts some kinds of encryption exports.  Different countries apply
the arrangement in different ways; some do not allow the exception for
certain kinds of "public domain" software (which would include this
library), some only restrict the export of software in tangible form,
and others impose significant additional restrictions.

   The United States has additional rules.  This software would
generally be exportable under 15 CFR 740.13(e), which permits exports of
"encryption source code" which is "publicly available" and which is
"not subject to an express agreement for the payment of a licensing fee
or royalty for commercial production or sale of any product developed
with the source code" to most countries.

   The rules in this area are continuously changing.  If you know of any
information in this manual that is out-of-date, please report it using
the `glibcbug' script. *Note Reporting Bugs::.


File: libc.info,  Node: getpass,  Next: crypt,  Prev: Legal Problems,  Up: Cryptographic Functions

Reading Passwords
=================

   When reading in a password, it is desirable to avoid displaying it on
the screen, to help keep it secret.  The following function handles this
in a convenient way.

 - Function: char * getpass (const char *PROMPT)
     `getpass' outputs PROMPT, then reads a string in from the terminal
     without echoing it.  It tries to connect to the real terminal,
     `/dev/tty', if possible, to encourage users not to put plaintext
     passwords in files; otherwise, it uses `stdin' and `stderr'.
     `getpass' also disables the INTR, QUIT, and SUSP characters on the
     terminal using the `ISIG' terminal attribute (*note Local Modes::).
     The terminal is flushed before and after `getpass', so that
     characters of a mistyped password are not accidentally visible.

     In other C libraries, `getpass' may only return the first
     `PASS_MAX' bytes of a password.  The GNU C library has no limit, so
     `PASS_MAX' is undefined.

     The prototype for this function is in `unistd.h'.  `PASS_MAX'
     would be defined in `limits.h'.

   This precise set of operations may not suit all possible situations.
In this case, it is recommended that users write their own `getpass'
substitute.  For instance, a very simple substitute is as follows:

     #include <termios.h>
     #include <stdio.h>
     
     ssize_t
     my_getpass (char **lineptr, size_t *n, FILE *stream)
     {
       struct termios old, new;
       int nread;
     
       /* Turn echoing off and fail if we can't. */
       if (tcgetattr (fileno (stream), &old) != 0)
         return -1;
       new = old;
       new.c_lflag &= ~ECHO;
       if (tcsetattr (fileno (stream), TCSAFLUSH, &new) != 0)
         return -1;
     
       /* Read the password. */
       nread = getline (lineptr, n, stream);
     
       /* Restore terminal. */
       (void) tcsetattr (fileno (stream), TCSAFLUSH, &old);
     
       return nread;
     }

   The substitute takes the same parameters as `getline' (*note Line
Input::); the user must print any prompt desired.


File: libc.info,  Node: crypt,  Next: DES Encryption,  Prev: getpass,  Up: Cryptographic Functions

Encrypting Passwords
====================

 - Function: char * crypt (const char *KEY, const char *SALT)
     The `crypt' function takes a password, KEY, as a string, and a
     SALT character array which is described below, and returns a
     printable ASCII string which starts with another salt.  It is
     believed that, given the output of the function, the best way to
     find a KEY that will produce that output is to guess values of KEY
     until the original value of KEY is found.

     The SALT parameter does two things.  Firstly, it selects which
     algorithm is used, the MD5-based one or the DES-based one.
     Secondly, it makes life harder for someone trying to guess
     passwords against a file containing many passwords; without a
     SALT, an intruder can make a guess, run `crypt' on it once, and
     compare the result with all the passwords.  With a SALT, the
     intruder must run `crypt' once for each different salt.

     For the MD5-based algorithm, the SALT should consist of the string
     `$1$', followed by up to 8 characters, terminated by either
     another `$' or the end of the string.  The result of `crypt' will
     be the SALT, followed by a `$' if the salt didn't end with one,
     followed by 22 characters from the alphabet `./0-9A-Za-z', up to
     34 characters total.  Every character in the KEY is significant.

     For the DES-based algorithm, the SALT should consist of two
     characters from the alphabet `./0-9A-Za-z', and the result of
     `crypt' will be those two characters followed by 11 more from the
     same alphabet, 13 in total.  Only the first 8 characters in the
     KEY are significant.

     The MD5-based algorithm has no limit on the useful length of the
     password used, and is slightly more secure.  It is therefore
     preferred over the DES-based algorithm.

     When the user enters their password for the first time, the SALT
     should be set to a new string which is reasonably random.  To
     verify a password against the result of a previous call to
     `crypt', pass the result of the previous call as the SALT.

   The following short program is an example of how to use `crypt' the
first time a password is entered.  Note that the SALT generation is
just barely acceptable; in particular, it is not unique between
machines, and in many applications it would not be acceptable to let an
attacker know what time the user's password was last set.

     #include <stdio.h>
     #include <time.h>
     #include <unistd.h>
     #include <crypt.h>
     
     int
     main(void)
     {
       unsigned long seed[2];
       char salt[] = "$1$........";
       const char *const seedchars =
         "./0123456789ABCDEFGHIJKLMNOPQRST"
         "UVWXYZabcdefghijklmnopqrstuvwxyz";
       char *password;
       int i;
     
       /* Generate a (not very) random seed.
          You should do it better than this... */
       seed[0] = time(NULL);
       seed[1] = getpid() ^ (seed[0] >> 14 & 0x30000);
     
       /* Turn it into printable characters from `seedchars'. */
       for (i = 0; i < 8; i++)
         salt[3+i] = seedchars[(seed[i/5] >> (i%5)*6) & 0x3f];
     
       /* Read in the user's password and encrypt it. */
       password = crypt(getpass("Password:"), salt);
     
       /* Print the results. */
       puts(password);
       return 0;
     }

   The next program shows how to verify a password.  It prompts the user
for a password and prints "Access granted." if the user types `GNU libc
manual'.

     #include <stdio.h>
     #include <string.h>
     #include <unistd.h>
     #include <crypt.h>
     
     int
     main(void)
     {
       /* Hashed form of "GNU libc manual". */
       const char *const pass = "$1$/iSaq7rB$EoUw5jJPPvAPECNaaWzMK/";
     
       char *result;
       int ok;
     
       /* Read in the user's password and encrypt it,
          passing the expected password in as the salt. */
       result = crypt(getpass("Password:"), pass);
     
       /* Test the result. */
       ok = strcmp (result, pass) == 0;
     
       puts(ok ? "Access granted." : "Access denied.");
       return ok ? 0 : 1;
     }

 - Function: char * crypt_r (const char *KEY, const char *SALT, struct
          crypt_data * DATA)
     The `crypt_r' function does the same thing as `crypt', but takes
     an extra parameter which includes space for its result (among
     other things), so it can be reentrant.  `data->initialized' must be
     cleared to zero before the first time `crypt_r' is called.

     The `crypt_r' function is a GNU extension.

   The `crypt' and `crypt_r' functions are prototyped in the header
`crypt.h'.


File: libc.info,  Node: DES Encryption,  Prev: crypt,  Up: Cryptographic Functions

DES Encryption
==============

   The Data Encryption Standard is described in the US Government
Federal Information Processing Standards (FIPS) 46-3 published by the
National Institute of Standards and Technology.  The DES has been very
thoroughly analyzed since it was developed in the late 1970s, and no new
significant flaws have been found.

   However, the DES uses only a 56-bit key (plus 8 parity bits), and a
machine has been built in 1998 which can search through all possible
keys in about 6 days, which cost about US$200000; faster searches would
be possible with more money.  This makes simple DES insecure for most
purposes, and NIST no longer permits new US government systems to use
simple DES.

   For serious encryption functionality, it is recommended that one of
the many free encryption libraries be used instead of these routines.

   The DES is a reversible operation which takes a 64-bit block and a
64-bit key, and produces another 64-bit block.  Usually the bits are
numbered so that the most-significant bit, the first bit, of each block
is numbered 1.

   Under that numbering, every 8th bit of the key (the 8th, 16th, and so
on) is not used by the encryption algorithm itself.  But the key must
have odd parity; that is, out of bits 1 through 8, and 9 through 16, and
so on, there must be an odd number of `1' bits, and this completely
specifies the unused bits.

 - Function: void setkey (const char *KEY)
     The `setkey' function sets an internal data structure to be an
     expanded form of KEY.  KEY is specified as an array of 64 bits
     each stored in a `char', the first bit is `key[0]' and the 64th
     bit is `key[63]'.  The KEY should have the correct parity.

 - Function: void encrypt (char *BLOCK, int EDFLAG)
     The `encrypt' function encrypts BLOCK if EDFLAG is 0, otherwise it
     decrypts BLOCK, using a key previously set by `setkey'.  The
     result is placed in BLOCK.

     Like `setkey', BLOCK is specified as an array of 64 bits each
     stored in a `char', but there are no parity bits in BLOCK.

 - Function: void setkey_r (const char *KEY, struct crypt_data * DATA)
 - Function: void encrypt_r (char *BLOCK, int EDFLAG, struct crypt_data
          * DATA)
     These are reentrant versions of `setkey' and `encrypt'.  The only
     difference is the extra parameter, which stores the expanded
     version of KEY.  Before calling `setkey_r' the first time,
     `data->initialized' must be cleared to zero.

   The `setkey_r' and `encrypt_r' functions are GNU extensions.
`setkey', `encrypt', `setkey_r', and `encrypt_r' are defined in
`crypt.h'.

 - Function: int ecb_crypt (char *KEY, char *BLOCKS, unsigned LEN,
          unsigned MODE)
     The function `ecb_crypt' encrypts or decrypts one or more blocks
     using DES.  Each block is encrypted independently.

     The BLOCKS and the KEY are stored packed in 8-bit bytes, so that
     the first bit of the key is the most-significant bit of `key[0]'
     and the 63rd bit of the key is stored as the least-significant bit
     of `key[7]'.  The KEY should have the correct parity.

     LEN is the number of bytes in BLOCKS.  It should be a multiple of
     8 (so that there is a whole number of blocks to encrypt).  LEN is
     limited to a maximum of `DES_MAXDATA' bytes.

     The result of the encryption replaces the input in BLOCKS.

     The MODE parameter is the bitwise OR of two of the following:

    `DES_ENCRYPT'
          This constant, used in the MODE parameter, specifies that
          BLOCKS is to be encrypted.

    `DES_DECRYPT'
          This constant, used in the MODE parameter, specifies that
          BLOCKS is to be decrypted.

    `DES_HW'
          This constant, used in the MODE parameter, asks to use a
          hardware device.  If no hardware device is available,
          encryption happens anyway, but in software.

    `DES_SW'
          This constant, used in the MODE parameter, specifies that no
          hardware device is to be used.

     The result of the function will be one of these values:

    `DESERR_NONE'
          The encryption succeeded.

    `DESERR_NOHWDEVICE'
          The encryption succeeded, but there was no hardware device
          available.

    `DESERR_HWERROR'
          The encryption failed because of a hardware problem.

    `DESERR_BADPARAM'
          The encryption failed because of a bad parameter, for
          instance LEN is not a multiple of 8 or LEN is larger than
          `DES_MAXDATA'.

 - Function: int DES_FAILED (int ERR)
     This macro returns 1 if ERR is a `success' result code from
     `ecb_crypt' or `cbc_crypt', and 0 otherwise.

 - Function: int cbc_crypt (char *KEY, char *BLOCKS, unsigned LEN,
          unsigned MODE, char *IVEC)
     The function `cbc_crypt' encrypts or decrypts one or more blocks
     using DES in Cipher Block Chaining mode.

     For encryption in CBC mode, each block is exclusive-ored with IVEC
     before being encrypted, then IVEC is replaced with the result of
     the encryption, then the next block is processed.  Decryption is
     the reverse of this process.

     This has the advantage that blocks which are the same before being
     encrypted are very unlikely to be the same after being encrypted,
     making it much harder to detect patterns in the data.

     Usually, IVEC is set to 8 random bytes before encryption starts.
     Then the 8 random bytes are transmitted along with the encrypted
     data (without themselves being encrypted), and passed back in as
     IVEC for decryption.  Another possibility is to set IVEC to 8
     zeroes initially, and have the first the block encrypted consist
     of 8 random bytes.

     Otherwise, all the parameters are similar to those for `ecb_crypt'.

 - Function: void des_setparity (char *KEY)
     The function `des_setparity' changes the 64-bit KEY, stored packed
     in 8-bit bytes, to have odd parity by altering the low bits of
     each byte.

   The `ecb_crypt', `cbc_crypt', and `des_setparity' functions and
their accompanying macros are all defined in the header
`rpc/des_crypt.h'.


File: libc.info,  Node: Debugging Support,  Next: POSIX Threads,  Prev: Cryptographic Functions,  Up: Top

Debugging support
*****************

   Applications are usually debugged using dedicated debugger programs.
But sometimes this is not possible and, in any case, it is useful to
provide the developer with as much information as possible at the time
the problems are experienced.  For this reason a few functions are
provided which a program can use to help the developer more easily
locate the problem.

* Menu:

* Backtraces::                Obtaining and printing a back trace of the
                               current stack.


File: libc.info,  Node: Backtraces,  Up: Debugging Support

Backtraces
==========

   A "backtrace" is a list of the function calls that are currently
active in a thread.  The usual way to inspect a backtrace of a program
is to use an external debugger such as gdb.  However, sometimes it is
useful to obtain a backtrace programmatically from within a program,
e.g., for the purposes of logging or diagnostics.

   The header file `execinfo.h' declares three functions that obtain
and manipulate backtraces of the current thread.

 - Function: int backtrace (void **BUFFER, int SIZE)
     The `backtrace' function obtains a backtrace for the current
     thread, as a list of pointers, and places the information into
     BUFFER.  The argument SIZE should be the number of `void *'
     elements that will fit into BUFFER.  The return value is the
     actual number of entries of BUFFER that are obtained, and is at
     most SIZE.

     The pointers placed in BUFFER are actually return addresses
     obtained by inspecting the stack, one return address per stack
     frame.

     Note that certain compiler optimizations may interfere with
     obtaining a valid backtrace.  Function inlining causes the inlined
     function to not have a stack frame; tail call optimization
     replaces one stack frame with another; frame pointer elimination
     will stop `backtrace' from interpreting the stack contents
     correctly.

 - Function: char ** backtrace_symbols (void *const *BUFFER, int SIZE)
     The `backtrace_symbols' function translates the information
     obtained from the `backtrace' function into an array of strings.
     The argument BUFFER should be a pointer to an array of addresses
     obtained via the `backtrace' function, and SIZE is the number of
     entries in that array (the return value of `backtrace').

     The return value is a pointer to an array of strings, which has
     SIZE entries just like the array BUFFER.  Each string contains a
     printable representation of the corresponding element of BUFFER.
     It includes the function name (if this can be determined), an
     offset into the function, and the actual return address (in
     hexadecimal).

     Currently, the function name and offset only be obtained on
     systems that use the ELF binary format for programs and libraries.
     On other systems, only the hexadecimal return address will be
     present.  Also, you may need to pass additional flags to the
     linker to make the function names available to the program.  (For
     example, on systems using GNU ld, you must pass (`-rdynamic'.)

     The return value of `backtrace_symbols' is a pointer obtained via
     the `malloc' function, and it is the responsibility of the caller
     to `free' that pointer.  Note that only the return value need be
     freed, not the individual strings.

     The return value is `NULL' if sufficient memory for the strings
     cannot be obtained.

 - Function: void backtrace_symbols_fd (void *const *BUFFER, int SIZE,
          int FD)
     The `backtrace_symbols_fd' function performs the same translation
     as the function `backtrace_symbols' function.  Instead of returning
     the strings to the caller, it writes the strings to the file
     descriptor FD, one per line.  It does not use the `malloc'
     function, and can therefore be used in situations where that
     function might fail.

   The following program illustrates the use of these functions.  Note
that the array to contain the return addresses returned by `backtrace'
is allocated on the stack.  Therefore code like this can be used in
situations where the memory handling via `malloc' does not work anymore
(in which case the `backtrace_symbols' has to be replaced by a
`backtrace_symbols_fd' call as well).  The number of return addresses
is normally not very large.  Even complicated programs rather seldom
have a nesting level of more than, say, 50 and with 200 possible
entries probably all programs should be covered.

     #include <execinfo.h>
     #include <stdio.h>
     #include <stdlib.h>
     
     /* Obtain a backtrace and print it to `stdout'. */
     void
     print_trace (void)
     {
       void *array[10];
       size_t size;
       char **strings;
       size_t i;
     
       size = backtrace (array, 10);
       strings = backtrace_symbols (array, size);
     
       printf ("Obtained %zd stack frames.\n", size);
     
       for (i = 0; i < size; i++)
          printf ("%s\n", strings[i]);
     
       free (strings);
     }
     
     /* A dummy function to make the backtrace more interesting. */
     void
     dummy_function (void)
     {
       print_trace ();
     }
     
     int
     main (void)
     {
       dummy_function ();
       return 0;
     }


File: libc.info,  Node: POSIX Threads,  Next: Language Features,  Prev: Debugging Support,  Up: Top

POSIX Threads
*************

   This chapter describes the pthreads (POSIX threads) library.  This
library provides support functions for multithreaded programs: thread
primitives, synchronization objects, and so forth.  It also implements
POSIX 1003.1b semaphores (not to be confused with System V semaphores).

   The threads operations (`pthread_*') do not use ERRNO.  Instead they
return an error code directly.  The semaphore operations do use ERRNO.

* Menu:

* Basic Thread Operations::     Creating, terminating, and waiting for threads.
* Thread Attributes::           Tuning thread scheduling.
* Cancellation::                Stopping a thread before it's done.
* Cleanup Handlers::            Deallocating resources when a thread is
                                  canceled.
* Mutexes::                     One way to synchronize threads.
* Condition Variables::         Another way.
* POSIX Semaphores::            And a third way.
* Thread-Specific Data::        Variables with different values in
                                  different threads.
* Threads and Signal Handling:: Why you should avoid mixing the two, and
                                  how to do it if you must.
* Threads and Fork::            Interactions between threads and the
                                  `fork' function.
* Streams and Fork::            Interactions between stdio streams and
                                  `fork'.
* Miscellaneous Thread Functions:: A grab bag of utility routines.

