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 #include 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 #include #include #include 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 #include #include #include 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 #include #include /* 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.