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: Editing Characters, Next: Signal Characters, Up: Special Characters Characters for Input Editing ............................ These special characters are active only in canonical input mode. *Note Canonical or Not::. - Macro: int VEOF This is the subscript for the EOF character in the special control character array. `TERMIOS.c_cc[VEOF]' holds the character itself. The EOF character is recognized only in canonical input mode. It acts as a line terminator in the same way as a newline character, but if the EOF character is typed at the beginning of a line it causes `read' to return a byte count of zero, indicating end-of-file. The EOF character itself is discarded. Usually, the EOF character is `C-d'. - Macro: int VEOL This is the subscript for the EOL character in the special control character array. `TERMIOS.c_cc[VEOL]' holds the character itself. The EOL character is recognized only in canonical input mode. It acts as a line terminator, just like a newline character. The EOL character is not discarded; it is read as the last character in the input line. You don't need to use the EOL character to make end a line. Just set the ICRNL flag. In fact, this is the default state of affairs. - Macro: int VEOL2 This is the subscript for the EOL2 character in the special control character array. `TERMIOS.c_cc[VEOL2]' holds the character itself. The EOL2 character works just like the EOL character (see above), but it can be a different character. Thus, you can specify two characters to terminate an input line, by setting EOL to one of them and EOL2 to the other. The EOL2 character is a BSD extension; it exists only on BSD systems and the GNU system. - Macro: int VERASE This is the subscript for the ERASE character in the special control character array. `TERMIOS.c_cc[VERASE]' holds the character itself. The ERASE character is recognized only in canonical input mode. When the user types the erase character, the previous character typed is discarded. (If the terminal generates multibyte character sequences, this may cause more than one byte of input to be discarded.) This cannot be used to erase past the beginning of the current line of text. The ERASE character itself is discarded. Usually, the ERASE character is . - Macro: int VWERASE This is the subscript for the WERASE character in the special control character array. `TERMIOS.c_cc[VWERASE]' holds the character itself. The WERASE character is recognized only in canonical mode. It erases an entire word of prior input, and any whitespace after it; whitespace characters before the word are not erased. The definition of a "word" depends on the setting of the `ALTWERASE' mode; *note Local Modes::. If the `ALTWERASE' mode is not set, a word is defined as a sequence of any characters except space or tab. If the `ALTWERASE' mode is set, a word is defined as a sequence of characters containing only letters, numbers, and underscores, optionally followed by one character that is not a letter, number, or underscore. The WERASE character is usually `C-w'. This is a BSD extension. - Macro: int VKILL This is the subscript for the KILL character in the special control character array. `TERMIOS.c_cc[VKILL]' holds the character itself. The KILL character is recognized only in canonical input mode. When the user types the kill character, the entire contents of the current line of input are discarded. The kill character itself is discarded too. The KILL character is usually `C-u'. - Macro: int VREPRINT This is the subscript for the REPRINT character in the special control character array. `TERMIOS.c_cc[VREPRINT]' holds the character itself. The REPRINT character is recognized only in canonical mode. It reprints the current input line. If some asynchronous output has come while you are typing, this lets you see the line you are typing clearly again. The REPRINT character is usually `C-r'. This is a BSD extension. File: libc.info, Node: Signal Characters, Next: Start/Stop Characters, Prev: Editing Characters, Up: Special Characters Characters that Cause Signals ............................. These special characters may be active in either canonical or noncanonical input mode, but only when the `ISIG' flag is set (*note Local Modes::). - Macro: int VINTR This is the subscript for the INTR character in the special control character array. `TERMIOS.c_cc[VINTR]' holds the character itself. The INTR (interrupt) character raises a `SIGINT' signal for all processes in the foreground job associated with the terminal. The INTR character itself is then discarded. *Note Signal Handling::, for more information about signals. Typically, the INTR character is `C-c'. - Macro: int VQUIT This is the subscript for the QUIT character in the special control character array. `TERMIOS.c_cc[VQUIT]' holds the character itself. The QUIT character raises a `SIGQUIT' signal for all processes in the foreground job associated with the terminal. The QUIT character itself is then discarded. *Note Signal Handling::, for more information about signals. Typically, the QUIT character is `C-\'. - Macro: int VSUSP This is the subscript for the SUSP character in the special control character array. `TERMIOS.c_cc[VSUSP]' holds the character itself. The SUSP (suspend) character is recognized only if the implementation supports job control (*note Job Control::). It causes a `SIGTSTP' signal to be sent to all processes in the foreground job associated with the terminal. The SUSP character itself is then discarded. *Note Signal Handling::, for more information about signals. Typically, the SUSP character is `C-z'. Few applications disable the normal interpretation of the SUSP character. If your program does this, it should provide some other mechanism for the user to stop the job. When the user invokes this mechanism, the program should send a `SIGTSTP' signal to the process group of the process, not just to the process itself. *Note Signaling Another Process::. - Macro: int VDSUSP This is the subscript for the DSUSP character in the special control character array. `TERMIOS.c_cc[VDSUSP]' holds the character itself. The DSUSP (suspend) character is recognized only if the implementation supports job control (*note Job Control::). It sends a `SIGTSTP' signal, like the SUSP character, but not right away--only when the program tries to read it as input. Not all systems with job control support DSUSP; only BSD-compatible systems (including the GNU system). *Note Signal Handling::, for more information about signals. Typically, the DSUSP character is `C-y'. File: libc.info, Node: Start/Stop Characters, Next: Other Special, Prev: Signal Characters, Up: Special Characters Special Characters for Flow Control ................................... These special characters may be active in either canonical or noncanonical input mode, but their use is controlled by the flags `IXON' and `IXOFF' (*note Input Modes::). - Macro: int VSTART This is the subscript for the START character in the special control character array. `TERMIOS.c_cc[VSTART]' holds the character itself. The START character is used to support the `IXON' and `IXOFF' input modes. If `IXON' is set, receiving a START character resumes suspended output; the START character itself is discarded. If `IXANY' is set, receiving any character at all resumes suspended output; the resuming character is not discarded unless it is the START character. `IXOFF' is set, the system may also transmit START characters to the terminal. The usual value for the START character is `C-q'. You may not be able to change this value--the hardware may insist on using `C-q' regardless of what you specify. - Macro: int VSTOP This is the subscript for the STOP character in the special control character array. `TERMIOS.c_cc[VSTOP]' holds the character itself. The STOP character is used to support the `IXON' and `IXOFF' input modes. If `IXON' is set, receiving a STOP character causes output to be suspended; the STOP character itself is discarded. If `IXOFF' is set, the system may also transmit STOP characters to the terminal, to prevent the input queue from overflowing. The usual value for the STOP character is `C-s'. You may not be able to change this value--the hardware may insist on using `C-s' regardless of what you specify. File: libc.info, Node: Other Special, Prev: Start/Stop Characters, Up: Special Characters Other Special Characters ........................ These special characters exist only in BSD systems and the GNU system. - Macro: int VLNEXT This is the subscript for the LNEXT character in the special control character array. `TERMIOS.c_cc[VLNEXT]' holds the character itself. The LNEXT character is recognized only when `IEXTEN' is set, but in both canonical and noncanonical mode. It disables any special significance of the next character the user types. Even if the character would normally perform some editing function or generate a signal, it is read as a plain character. This is the analogue of the `C-q' command in Emacs. "LNEXT" stands for "literal next." The LNEXT character is usually `C-v'. - Macro: int VDISCARD This is the subscript for the DISCARD character in the special control character array. `TERMIOS.c_cc[VDISCARD]' holds the character itself. The DISCARD character is recognized only when `IEXTEN' is set, but in both canonical and noncanonical mode. Its effect is to toggle the discard-output flag. When this flag is set, all program output is discarded. Setting the flag also discards all output currently in the output buffer. Typing any other character resets the flag. - Macro: int VSTATUS This is the subscript for the STATUS character in the special control character array. `TERMIOS.c_cc[VSTATUS]' holds the character itself. The STATUS character's effect is to print out a status message about how the current process is running. The STATUS character is recognized only in canonical mode, and only if `NOKERNINFO' is not set. File: libc.info, Node: Noncanonical Input, Prev: Special Characters, Up: Terminal Modes Noncanonical Input ------------------ In noncanonical input mode, the special editing characters such as ERASE and KILL are ignored. The system facilities for the user to edit input are disabled in noncanonical mode, so that all input characters (unless they are special for signal or flow-control purposes) are passed to the application program exactly as typed. It is up to the application program to give the user ways to edit the input, if appropriate. Noncanonical mode offers special parameters called MIN and TIME for controlling whether and how long to wait for input to be available. You can even use them to avoid ever waiting--to return immediately with whatever input is available, or with no input. The MIN and TIME are stored in elements of the `c_cc' array, which is a member of the `struct termios' structure. Each element of this array has a particular role, and each element has a symbolic constant that stands for the index of that element. `VMIN' and `VMAX' are the names for the indices in the array of the MIN and TIME slots. - Macro: int VMIN This is the subscript for the MIN slot in the `c_cc' array. Thus, `TERMIOS.c_cc[VMIN]' is the value itself. The MIN slot is only meaningful in noncanonical input mode; it specifies the minimum number of bytes that must be available in the input queue in order for `read' to return. - Macro: int VTIME This is the subscript for the TIME slot in the `c_cc' array. Thus, `TERMIOS.c_cc[VTIME]' is the value itself. The TIME slot is only meaningful in noncanonical input mode; it specifies how long to wait for input before returning, in units of 0.1 seconds. The MIN and TIME values interact to determine the criterion for when `read' should return; their precise meanings depend on which of them are nonzero. There are four possible cases: * Both TIME and MIN are nonzero. In this case, TIME specifies how long to wait after each input character to see if more input arrives. After the first character received, `read' keeps waiting until either MIN bytes have arrived in all, or TIME elapses with no further input. `read' always blocks until the first character arrives, even if TIME elapses first. `read' can return more than MIN characters if more than MIN happen to be in the queue. * Both MIN and TIME are zero. In this case, `read' always returns immediately with as many characters as are available in the queue, up to the number requested. If no input is immediately available, `read' returns a value of zero. * MIN is zero but TIME has a nonzero value. In this case, `read' waits for time TIME for input to become available; the availability of a single byte is enough to satisfy the read request and cause `read' to return. When it returns, it returns as many characters as are available, up to the number requested. If no input is available before the timer expires, `read' returns a value of zero. * TIME is zero but MIN has a nonzero value. In this case, `read' waits until at least MIN bytes are available in the queue. At that time, `read' returns as many characters as are available, up to the number requested. `read' can return more than MIN characters if more than MIN happen to be in the queue. What happens if MIN is 50 and you ask to read just 10 bytes? Normally, `read' waits until there are 50 bytes in the buffer (or, more generally, the wait condition described above is satisfied), and then reads 10 of them, leaving the other 40 buffered in the operating system for a subsequent call to `read'. *Portability note:* On some systems, the MIN and TIME slots are actually the same as the EOF and EOL slots. This causes no serious problem because the MIN and TIME slots are used only in noncanonical input and the EOF and EOL slots are used only in canonical input, but it isn't very clean. The GNU library allocates separate slots for these uses. - Function: void cfmakeraw (struct termios *TERMIOS-P) This function provides an easy way to set up `*TERMIOS-P' for what has traditionally been called "raw mode" in BSD. This uses noncanonical input, and turns off most processing to give an unmodified channel to the terminal. It does exactly this: TERMIOS-P->c_iflag &= ~(IGNBRK|BRKINT|PARMRK|ISTRIP |INLCR|IGNCR|ICRNL|IXON); TERMIOS-P->c_oflag &= ~OPOST; TERMIOS-P->c_lflag &= ~(ECHO|ECHONL|ICANON|ISIG|IEXTEN); TERMIOS-P->c_cflag &= ~(CSIZE|PARENB); TERMIOS-P->c_cflag |= CS8; File: libc.info, Node: BSD Terminal Modes, Next: Line Control, Prev: Terminal Modes, Up: Low-Level Terminal Interface BSD Terminal Modes ================== The usual way to get and set terminal modes is with the functions described in *Note Terminal Modes::. However, on some systems you can use the BSD-derived functions in this section to do some of the same thing. On many systems, these functions do not exist. Even with the GNU C library, the functions simply fail with `errno' = `ENOSYS' with many kernels, including Linux. The symbols used in this section are declared in `sgtty.h'. - Data Type: struct sgttyb This structure is an input or output parameter list for `gtty' and `stty'. `char sg_ispeed' Line speed for input `char sg_ospeed' Line speed for output `char sg_erase' Erase character `char sg_kill' Kill character `int sg_flags' Various flags - Function: int gtty (int FILEDES, struct sgttyb *ATTRIBUTES) This function gets the attributes of a terminal. `gtty' sets *ATTRIBUTES to describe the terminal attributes of the terminal which is open with file descriptor FILEDES. - Function: int stty (int FILEDES, struct sgttyb * attributes) This function sets the attributes of a terminal. `stty' sets the terminal attributes of the terminal which is open with file descriptor FILEDES to those described by *FILEDES. File: libc.info, Node: Line Control, Next: Noncanon Example, Prev: BSD Terminal Modes, Up: Low-Level Terminal Interface Line Control Functions ====================== These functions perform miscellaneous control actions on terminal devices. As regards terminal access, they are treated like doing output: if any of these functions is used by a background process on its controlling terminal, normally all processes in the process group are sent a `SIGTTOU' signal. The exception is if the calling process itself is ignoring or blocking `SIGTTOU' signals, in which case the operation is performed and no signal is sent. *Note Job Control::. - Function: int tcsendbreak (int FILEDES, int DURATION) This function generates a break condition by transmitting a stream of zero bits on the terminal associated with the file descriptor FILEDES. The duration of the break is controlled by the DURATION argument. If zero, the duration is between 0.25 and 0.5 seconds. The meaning of a nonzero value depends on the operating system. This function does nothing if the terminal is not an asynchronous serial data port. The return value is normally zero. In the event of an error, a value of -1 is returned. The following `errno' error conditions are defined for this function: `EBADF' The FILEDES is not a valid file descriptor. `ENOTTY' The FILEDES is not associated with a terminal device. - Function: int tcdrain (int FILEDES) The `tcdrain' function waits until all queued output to the terminal FILEDES has been transmitted. This function is a cancellation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time `tcdrain' is called. If the thread gets canceled these resources stay allocated until the program ends. To avoid this calls to `tcdrain' should be protected using cancellation handlers. The return value is normally zero. In the event of an error, a value of -1 is returned. The following `errno' error conditions are defined for this function: `EBADF' The FILEDES is not a valid file descriptor. `ENOTTY' The FILEDES is not associated with a terminal device. `EINTR' The operation was interrupted by delivery of a signal. *Note Interrupted Primitives::. - Function: int tcflush (int FILEDES, int QUEUE) The `tcflush' function is used to clear the input and/or output queues associated with the terminal file FILEDES. The QUEUE argument specifies which queue(s) to clear, and can be one of the following values: `TCIFLUSH' Clear any input data received, but not yet read. `TCOFLUSH' Clear any output data written, but not yet transmitted. `TCIOFLUSH' Clear both queued input and output. The return value is normally zero. In the event of an error, a value of -1 is returned. The following `errno' error conditions are defined for this function: `EBADF' The FILEDES is not a valid file descriptor. `ENOTTY' The FILEDES is not associated with a terminal device. `EINVAL' A bad value was supplied as the QUEUE argument. It is unfortunate that this function is named `tcflush', because the term "flush" is normally used for quite another operation--waiting until all output is transmitted--and using it for discarding input or output would be confusing. Unfortunately, the name `tcflush' comes from POSIX and we cannot change it. - Function: int tcflow (int FILEDES, int ACTION) The `tcflow' function is used to perform operations relating to XON/XOFF flow control on the terminal file specified by FILEDES. The ACTION argument specifies what operation to perform, and can be one of the following values: `TCOOFF' Suspend transmission of output. `TCOON' Restart transmission of output. `TCIOFF' Transmit a STOP character. `TCION' Transmit a START character. For more information about the STOP and START characters, see *Note Special Characters::. The return value is normally zero. In the event of an error, a value of -1 is returned. The following `errno' error conditions are defined for this function: `EBADF' The FILEDES is not a valid file descriptor. `ENOTTY' The FILEDES is not associated with a terminal device. `EINVAL' A bad value was supplied as the ACTION argument. File: libc.info, Node: Noncanon Example, Next: Pseudo-Terminals, Prev: Line Control, Up: Low-Level Terminal Interface Noncanonical Mode Example ========================= Here is an example program that shows how you can set up a terminal device to read single characters in noncanonical input mode, without echo. #include #include #include #include /* Use this variable to remember original terminal attributes. */ struct termios saved_attributes; void reset_input_mode (void) { tcsetattr (STDIN_FILENO, TCSANOW, &saved_attributes); } void set_input_mode (void) { struct termios tattr; char *name; /* Make sure stdin is a terminal. */ if (!isatty (STDIN_FILENO)) { fprintf (stderr, "Not a terminal.\n"); exit (EXIT_FAILURE); } /* Save the terminal attributes so we can restore them later. */ tcgetattr (STDIN_FILENO, &saved_attributes); atexit (reset_input_mode); /* Set the funny terminal modes. */ tcgetattr (STDIN_FILENO, &tattr); tattr.c_lflag &= ~(ICANON|ECHO); /* Clear ICANON and ECHO. */ tattr.c_cc[VMIN] = 1; tattr.c_cc[VTIME] = 0; tcsetattr (STDIN_FILENO, TCSAFLUSH, &tattr); } int main (void) { char c; set_input_mode (); while (1) { read (STDIN_FILENO, &c, 1); if (c == '\004') /* `C-d' */ break; else putchar (c); } return EXIT_SUCCESS; } This program is careful to restore the original terminal modes before exiting or terminating with a signal. It uses the `atexit' function (*note Cleanups on Exit::) to make sure this is done by `exit'. The shell is supposed to take care of resetting the terminal modes when a process is stopped or continued; see *Note Job Control::. But some existing shells do not actually do this, so you may wish to establish handlers for job control signals that reset terminal modes. The above example does so. File: libc.info, Node: Pseudo-Terminals, Prev: Noncanon Example, Up: Low-Level Terminal Interface Pseudo-Terminals ================ A "pseudo-terminal" is a special interprocess communication channel that acts like a terminal. One end of the channel is called the "master" side or "master pseudo-terminal device", the other side is called the "slave" side. Data written to the master side is received by the slave side as if it was the result of a user typing at an ordinary terminal, and data written to the slave side is sent to the master side as if it was written on an ordinary terminal. Pseudo terminals are the way programs like `xterm' and `emacs' implement their terminal emulation functionality. * Menu: * Allocation:: Allocating a pseudo terminal. * Pseudo-Terminal Pairs:: How to open both sides of a pseudo-terminal in a single operation. File: libc.info, Node: Allocation, Next: Pseudo-Terminal Pairs, Up: Pseudo-Terminals Allocating Pseudo-Terminals --------------------------- This subsection describes functions for allocating a pseudo-terminal, and for making this pseudo-terminal available for actual use. These functions are declared in the header file `stdlib.h'. - Function: int getpt (void) The `getpt' function returns a new file descriptor for the next available master pseudo-terminal. The normal return value from `getpt' is a non-negative integer file descriptor. In the case of an error, a value of -1 is returned instead. The following `errno' conditions are defined for this function: `ENOENT' There are no free master pseudo-terminals available. This function is a GNU extension. - Function: int grantpt (int FILEDES) The `grantpt' function changes the ownership and access permission of the slave pseudo-terminal device corresponding to the master pseudo-terminal device associated with the file descriptor FILEDES. The owner is set from the real user ID of the calling process (*note Process Persona::), and the group is set to a special group (typically "tty") or from the real group ID of the calling process. The access permission is set such that the file is both readable and writable by the owner and only writable by the group. On some systems this function is implemented by invoking a special `setuid' root program (*note How Change Persona::). As a consequence, installing a signal handler for the `SIGCHLD' signal (*note Job Control Signals::) may interfere with a call to `grantpt'. The normal return value from `grantpt' is 0; a value of -1 is returned in case of failure. The following `errno' error conditions are defined for this function: `EBADF' The FILEDES argument is not a valid file descriptor. `EINVAL' The FILEDES argument is not associated with a master pseudo-terminal device. `EACCES' The slave pseudo-terminal device corresponding to the master associated with FILEDES could not be accessed. - Function: int unlockpt (int FILEDES) The `unlockpt' function unlocks the slave pseudo-terminal device corresponding to the master pseudo-terminal device associated with the file descriptor FILEDES. On many systems, the slave can only be opened after unlocking, so portable applications should always call `unlockpt' before trying to open the slave. The normal return value from `unlockpt' is 0; a value of -1 is returned in case of failure. The following `errno' error conditions are defined for this function: `EBADF' The FILEDES argument is not a valid file descriptor. `EINVAL' The FILEDES argument is not associated with a master pseudo-terminal device. - Function: char * ptsname (int FILEDES) If the file descriptor FILEDES is associated with a master pseudo-terminal device, the `ptsname' function returns a pointer to a statically-allocated, null-terminated string containing the file name of the associated slave pseudo-terminal file. This string might be overwritten by subsequent calls to `ptsname'. - Function: int ptsname_r (int FILEDES, char *BUF, size_t LEN) The `ptsname_r' function is similar to the `ptsname' function except that it places its result into the user-specified buffer starting at BUF with length LEN. This function is a GNU extension. *Portability Note:* On System V derived systems, the file returned by the `ptsname' and `ptsname_r' functions may be STREAMS-based, and therefore require additional processing after opening before it actually behaves as a pseudo terminal. Typical usage of these functions is illustrated by the following example: int open_pty_pair (int *amaster, int *aslave) { int master, slave; char *name; master = getpt (); if (master < 0) return 0; if (grantpt (master) < 0 || unlockpt (master) < 0) goto close_master; name = ptsname (master); if (name == NULL) goto close_master; slave = open (name, O_RDWR); if (slave == -1) goto close_master; if (isastream (slave)) { if (ioctl (slave, I_PUSH, "ptem") < 0 || ioctl (slave, I_PUSH, "ldterm") < 0) goto close_slave; } *amaster = master; *aslave = slave; return 1; close_slave: close (slave); close_master: close (master); return 0; } File: libc.info, Node: Pseudo-Terminal Pairs, Prev: Allocation, Up: Pseudo-Terminals Opening a Pseudo-Terminal Pair ------------------------------ These functions, derived from BSD, are available in the separate `libutil' library, and declared in `pty.h'. - Function: int openpty (int *AMASTER, int *ASLAVE, char *NAME, struct termios *TERMP, struct winsize *WINP) This function allocates and opens a pseudo-terminal pair, returning the file descriptor for the master in *AMASTER, and the file descriptor for the slave in *ASLAVE. If the argument NAME is not a null pointer, the file name of the slave pseudo-terminal device is stored in `*name'. If TERMP is not a null pointer, the terminal attributes of the slave are set to the ones specified in the structure that TERMP points to (*note Terminal Modes::). Likewise, if the WINP is not a null pointer, the screen size of the slave is set to the values specified in the structure that WINP points to. The normal return value from `openpty' is 0; a value of -1 is returned in case of failure. The following `errno' conditions are defined for this function: `ENOENT' There are no free pseudo-terminal pairs available. *Warning:* Using the `openpty' function with NAME not set to `NULL' is *very dangerous* because it provides no protection against overflowing the string NAME. You should use the `ttyname' function on the file descriptor returned in *SLAVE to find out the file name of the slave pseudo-terminal device instead. - Function: int forkpty (int *AMASTER, char *NAME, struct termios *TERMP, struct winsize *WINP) This function is similar to the `openpty' function, but in addition, forks a new process (*note Creating a Process::) and makes the newly opened slave pseudo-terminal device the controlling terminal (*note Controlling Terminal::) for the child process. If the operation is successful, there are then both parent and child processes and both see `forkpty' return, but with different values: it returns a value of 0 in the child process and returns the child's process ID in the parent process. If the allocation of a pseudo-terminal pair or the process creation failed, `forkpty' returns a value of -1 in the parent process. *Warning:* The `forkpty' function has the same problems with respect to the NAME argument as `openpty'. File: libc.info, Node: Syslog, Next: Mathematics, Prev: Low-Level Terminal Interface, Up: Top Syslog ****** This chapter describes facilities for issuing and logging messages of system administration interest. This chapter has nothing to do with programs issuing messages to their own users or keeping private logs (One would typically do that with the facilities described in *Note I/O on Streams::). Most systems have a facility called "Syslog" that allows programs to submit messages of interest to system administrators and can be configured to pass these messages on in various ways, such as printing on the console, mailing to a particular person, or recording in a log file for future reference. A program uses the facilities in this chapter to submit such messages. * Menu: * Overview of Syslog:: Overview of a system's Syslog facility * Submitting Syslog Messages:: Functions to submit messages to Syslog File: libc.info, Node: Overview of Syslog, Next: Submitting Syslog Messages, Up: Syslog Overview of Syslog ================== System administrators have to deal with lots of different kinds of messages from a plethora of subsystems within each system, and usually lots of systems as well. For example, an FTP server might report every connection it gets. The kernel might report hardware failures on a disk drive. A DNS server might report usage statistics at regular intervals. Some of these messages need to be brought to a system administrator's attention immediately. And it may not be just any system administrator - there may be a particular system administrator who deals with a particular kind of message. Other messages just need to be recorded for future reference if there is a problem. Still others may need to have information extracted from them by an automated process that generates monthly reports. To deal with these messages, most Unix systems have a facility called "Syslog." It is generally based on a daemon called "Syslogd" Syslogd listens for messages on a Unix domain socket named `/dev/log'. Based on classification information in the messages and its configuration file (usually `/etc/syslog.conf'), Syslogd routes them in various ways. Some of the popular routings are: * Write to the system console * Mail to a specific user * Write to a log file * Pass to another daemon * Discard Syslogd can also handle messages from other systems. It listens on the `syslog' UDP port as well as the local socket for messages. Syslog can handle messages from the kernel itself. But the kernel doesn't write to `/dev/log'; rather, another daemon (sometimes called "Klogd") extracts messages from the kernel and passes them on to Syslog as any other process would (and it properly identifies them as messages from the kernel). Syslog can even handle messages that the kernel issued before Syslogd or Klogd was running. A Linux kernel, for example, stores startup messages in a kernel message ring and they are normally still there when Klogd later starts up. Assuming Syslogd is running by the time Klogd starts, Klogd then passes everything in the message ring to it. In order to classify messages for disposition, Syslog requires any process that submits a message to it to provide two pieces of classification information with it: facility This identifies who submitted the message. There are a small number of facilities defined. The kernel, the mail subsystem, and an FTP server are examples of recognized facilities. For the complete list, *Note syslog; vsyslog::. Keep in mind that these are essentially arbitrary classifications. "Mail subsystem" doesn't have any more meaning than the system administrator gives to it. priority This tells how important the content of the message is. Examples of defined priority values are: debug, informational, warning, critical. For the complete list, *Note syslog; vsyslog::. Except for the fact that the priorities have a defined order, the meaning of each of these priorities is entirely determined by the system administrator. A "facility/priority" is a number that indicates both the facility and the priority. *Warning:* This terminology is not universal. Some people use "level" to refer to the priority and "priority" to refer to the combination of facility and priority. A Linux kernel has a concept of a message "level," which corresponds both to a Syslog priority and to a Syslog facility/priority (It can be both because the facility code for the kernel is zero, and that makes priority and facility/priority the same value). The GNU C library provides functions to submit messages to Syslog. They do it by writing to the `/dev/log' socket. *Note Submitting Syslog Messages::. The GNU C library functions only work to submit messages to the Syslog facility on the same system. To submit a message to the Syslog facility on another system, use the socket I/O functions to write a UDP datagram to the `syslog' UDP port on that system. *Note Sockets::. File: libc.info, Node: Submitting Syslog Messages, Prev: Overview of Syslog, Up: Syslog Submitting Syslog Messages ========================== The GNU C library provides functions to submit messages to the Syslog facility: * Menu: * openlog:: Open connection to Syslog * syslog; vsyslog:: Submit message to Syslog * closelog:: Close connection to Syslog * setlogmask:: Cause certain messages to be ignored * Syslog Example:: Example of all of the above These functions only work to submit messages to the Syslog facility on the same system. To submit a message to the Syslog facility on another system, use the socket I/O functions to write a UDP datagram to the `syslog' UDP port on that system. *Note Sockets::. File: libc.info, Node: openlog, Next: syslog; vsyslog, Up: Submitting Syslog Messages openlog ------- The symbols referred to in this section are declared in the file `syslog.h'. - Function: void openlog (const char *IDENT, int OPTION, int FACILITY) `openlog' opens or reopens a connection to Syslog in preparation for submitting messages. IDENT is an arbitrary identification string which future `syslog' invocations will prefix to each message. This is intended to identify the source of the message, and people conventionally set it to the name of the program that will submit the messages. If IDENT is NULL, or if `openlog' is not called, the default identification string used in Syslog messages will be the program name, taken from argv[0]. Please note that the string pointer IDENT will be retained internally by the Syslog routines. You must not free the memory that IDENT points to. It is also dangerous to pass a reference to an automatic variable since leaving the scope would mean ending the lifetime of the variable. If you want to change the IDENT string, you must call `openlog' again; overwriting the string pointed to by IDENT is not thread-safe. You can cause the Syslog routines to drop the reference to IDENT and go back to the default string (the program name taken from argv[0]), by calling `closelog': *Note closelog::. In particular, if you are writing code for a shared library that might get loaded and then unloaded (e.g. a PAM module), and you use `openlog', you must call `closelog' before any point where your library might get unloaded, as in this example: #include void shared_library_function (void) { openlog ("mylibrary", option, priority); syslog (LOG_INFO, "shared library has been invoked"); closelog (); } Without the call to `closelog', future invocations of `syslog' by the program using the shared library may crash, if the library gets unloaded and the memory containing the string `"mylibrary"' becomes unmapped. This is a limitation of the BSD syslog interface. `openlog' may or may not open the `/dev/log' socket, depending on OPTION. If it does, it tries to open it and connect it as a stream socket. If that doesn't work, it tries to open it and connect it as a datagram socket. The socket has the "Close on Exec" attribute, so the kernel will close it if the process performs an exec. You don't have to use `openlog'. If you call `syslog' without having called `openlog', `syslog' just opens the connection implicitly and uses defaults for the information in IDENT and OPTIONS. OPTIONS is a bit string, with the bits as defined by the following single bit masks: `LOG_PERROR' If on, `openlog' sets up the connection so that any `syslog' on this connection writes its message to the calling process' Standard Error stream in addition to submitting it to Syslog. If off, `syslog' does not write the message to Standard Error. `LOG_CONS' If on, `openlog' sets up the connection so that a `syslog' on this connection that fails to submit a message to Syslog writes the message instead to system console. If off, `syslog' does not write to the system console (but of course Syslog may write messages it receives to the console). `LOG_PID' When on, `openlog' sets up the connection so that a `syslog' on this connection inserts the calling process' Process ID (PID) into the message. When off, `openlog' does not insert the PID. `LOG_NDELAY' When on, `openlog' opens and connects the `/dev/log' socket. When off, a future `syslog' call must open and connect the socket. *Portability note:* In early systems, the sense of this bit was exactly the opposite. `LOG_ODELAY' This bit does nothing. It exists for backward compatibility. If any other bit in OPTIONS is on, the result is undefined. FACILITY is the default facility code for this connection. A `syslog' on this connection that specifies default facility causes this facility to be associated with the message. See `syslog' for possible values. A value of zero means the default default, which is `LOG_USER'. If a Syslog connection is already open when you call `openlog', `openlog' "reopens" the connection. Reopening is like opening except that if you specify zero for the default facility code, the default facility code simply remains unchanged and if you specify LOG_NDELAY and the socket is already open and connected, `openlog' just leaves it that way. File: libc.info, Node: syslog; vsyslog, Next: closelog, Prev: openlog, Up: Submitting Syslog Messages syslog, vsyslog --------------- The symbols referred to in this section are declared in the file `syslog.h'. - Function: void syslog (int FACILITY_PRIORITY, char *FORMAT, ...) `syslog' submits a message to the Syslog facility. It does this by writing to the Unix domain socket `/dev/log'. `syslog' submits the message with the facility and priority indicated by FACILITY_PRIORITY. The macro `LOG_MAKEPRI' generates a facility/priority from a facility and a priority, as in the following example: LOG_MAKEPRI(LOG_USER, LOG_WARNING) The possible values for the facility code are (macros): `LOG_USER' A miscellaneous user process `LOG_MAIL' Mail `LOG_DAEMON' A miscellaneous system daemon `LOG_AUTH' Security (authorization) `LOG_SYSLOG' Syslog `LOG_LPR' Central printer `LOG_NEWS' Network news (e.g. Usenet) `LOG_UUCP' UUCP `LOG_CRON' Cron and At `LOG_AUTHPRIV' Private security (authorization) `LOG_FTP' Ftp server `LOG_LOCAL0' Locally defined `LOG_LOCAL1' Locally defined `LOG_LOCAL2' Locally defined `LOG_LOCAL3' Locally defined `LOG_LOCAL4' Locally defined `LOG_LOCAL5' Locally defined `LOG_LOCAL6' Locally defined `LOG_LOCAL7' Locally defined Results are undefined if the facility code is anything else. *note:* `syslog' recognizes one other facility code: that of the kernel. But you can't specify that facility code with these functions. If you try, it looks the same to `syslog' as if you are requesting the default facility. But you wouldn't want to anyway, because any program that uses the GNU C library is not the kernel. You can use just a priority code as FACILITY_PRIORITY. In that case, `syslog' assumes the default facility established when the Syslog connection was opened. *Note Syslog Example::. The possible values for the priority code are (macros): `LOG_EMERG' The message says the system is unusable. `LOG_ALERT' Action on the message must be taken immediately. `LOG_CRIT' The message states a critical condition. `LOG_ERR' The message describes an error. `LOG_WARNING' The message is a warning. `LOG_NOTICE' The message describes a normal but important event. `LOG_INFO' The message is purely informational. `LOG_DEBUG' The message is only for debugging purposes. Results are undefined if the priority code is anything else. If the process does not presently have a Syslog connection open (i.e. it did not call `openlog'), `syslog' implicitly opens the connection the same as `openlog' would, with the following defaults for information that would otherwise be included in an `openlog' call: The default identification string is the program name. The default default facility is `LOG_USER'. The default for all the connection options in OPTIONS is as if those bits were off. `syslog' leaves the Syslog connection open. If the `dev/log' socket is not open and connected, `syslog' opens and connects it, the same as `openlog' with the `LOG_NDELAY' option would. `syslog' leaves `/dev/log' open and connected unless its attempt to send the message failed, in which case `syslog' closes it (with the hope that a future implicit open will restore the Syslog connection to a usable state). Example: #include syslog (LOG_MAKEPRI(LOG_LOCAL1, LOG_ERROR), "Unable to make network connection to %s. Error=%m", host); - Function: void vsyslog (int FACILITY_PRIORITY, char *FORMAT, va_list arglist) This is functionally identical to `syslog', with the BSD style variable length argument. File: libc.info, Node: closelog, Next: setlogmask, Prev: syslog; vsyslog, Up: Submitting Syslog Messages closelog -------- The symbols referred to in this section are declared in the file `syslog.h'. - Function: void closelog (void) `closelog' closes the current Syslog connection, if there is one. This includes closing the `dev/log' socket, if it is open. `closelog' also sets the identification string for Syslog messages back to the default, if `openlog' was called with a non-NULL argument to IDENT. The default identification string is the program name taken from argv[0]. If you are writing shared library code that uses `openlog' to generate custom syslog output, you should use `closelog' to drop the GNU C library's internal reference to the IDENT pointer when you are done. Please read the section on `openlog' for more information: *Note openlog::. `closelog' does not flush any buffers. You do not have to call `closelog' before re-opening a Syslog connection with `initlog'. Syslog connections are automatically closed on exec or exit.