| This is libc.info, produced by makeinfo version 5.2 from libc.texinfo. |
| |
| This file documents the GNU C Library. |
| |
| This is 'The GNU C Library Reference Manual', for version 2.19 |
| (Buildroot). |
| |
| Copyright (C) 1993-2014 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.3 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 GNU |
| Manual", and with the Back-Cover Texts as in (a) below. A copy of the |
| license is included in the section entitled "GNU Free Documentation |
| License". |
| |
| (a) The FSF's Back-Cover Text is: "You have the freedom to copy and |
| modify this GNU manual. Buying copies from the FSF supports it in |
| developing GNU and promoting software freedom." |
| INFO-DIR-SECTION Software libraries |
| START-INFO-DIR-ENTRY |
| * Libc: (libc). C library. |
| END-INFO-DIR-ENTRY |
| |
| INFO-DIR-SECTION GNU C library functions and macros |
| START-INFO-DIR-ENTRY |
| * ALTWERASE: (libc)Local Modes. |
| * ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions. |
| * ARG_MAX: (libc)General Limits. |
| * BC_BASE_MAX: (libc)Utility Limits. |
| * BC_DIM_MAX: (libc)Utility Limits. |
| * BC_SCALE_MAX: (libc)Utility Limits. |
| * BC_STRING_MAX: (libc)Utility Limits. |
| * BRKINT: (libc)Input Modes. |
| * BUFSIZ: (libc)Controlling Buffering. |
| * CCTS_OFLOW: (libc)Control Modes. |
| * CHILD_MAX: (libc)General Limits. |
| * CIGNORE: (libc)Control Modes. |
| * CLK_TCK: (libc)Processor Time. |
| * CLOCAL: (libc)Control Modes. |
| * CLOCKS_PER_SEC: (libc)CPU Time. |
| * COLL_WEIGHTS_MAX: (libc)Utility Limits. |
| * CPU_CLR: (libc)CPU Affinity. |
| * CPU_ISSET: (libc)CPU Affinity. |
| * CPU_SET: (libc)CPU Affinity. |
| * CPU_SETSIZE: (libc)CPU Affinity. |
| * CPU_ZERO: (libc)CPU Affinity. |
| * CREAD: (libc)Control Modes. |
| * CRTS_IFLOW: (libc)Control Modes. |
| * CS5: (libc)Control Modes. |
| * CS6: (libc)Control Modes. |
| * CS7: (libc)Control Modes. |
| * CS8: (libc)Control Modes. |
| * CSIZE: (libc)Control Modes. |
| * CSTOPB: (libc)Control Modes. |
| * DES_FAILED: (libc)DES Encryption. |
| * DTTOIF: (libc)Directory Entries. |
| * E2BIG: (libc)Error Codes. |
| * EACCES: (libc)Error Codes. |
| * EADDRINUSE: (libc)Error Codes. |
| * EADDRNOTAVAIL: (libc)Error Codes. |
| * EADV: (libc)Error Codes. |
| * EAFNOSUPPORT: (libc)Error Codes. |
| * EAGAIN: (libc)Error Codes. |
| * EALREADY: (libc)Error Codes. |
| * EAUTH: (libc)Error Codes. |
| * EBACKGROUND: (libc)Error Codes. |
| * EBADE: (libc)Error Codes. |
| * EBADF: (libc)Error Codes. |
| * EBADFD: (libc)Error Codes. |
| * EBADMSG: (libc)Error Codes. |
| * EBADR: (libc)Error Codes. |
| * EBADRPC: (libc)Error Codes. |
| * EBADRQC: (libc)Error Codes. |
| * EBADSLT: (libc)Error Codes. |
| * EBFONT: (libc)Error Codes. |
| * EBUSY: (libc)Error Codes. |
| * ECANCELED: (libc)Error Codes. |
| * ECHILD: (libc)Error Codes. |
| * ECHO: (libc)Local Modes. |
| * ECHOCTL: (libc)Local Modes. |
| * ECHOE: (libc)Local Modes. |
| * ECHOK: (libc)Local Modes. |
| * ECHOKE: (libc)Local Modes. |
| * ECHONL: (libc)Local Modes. |
| * ECHOPRT: (libc)Local Modes. |
| * ECHRNG: (libc)Error Codes. |
| * ECOMM: (libc)Error Codes. |
| * ECONNABORTED: (libc)Error Codes. |
| * ECONNREFUSED: (libc)Error Codes. |
| * ECONNRESET: (libc)Error Codes. |
| * ED: (libc)Error Codes. |
| * EDEADLK: (libc)Error Codes. |
| * EDEADLOCK: (libc)Error Codes. |
| * EDESTADDRREQ: (libc)Error Codes. |
| * EDIED: (libc)Error Codes. |
| * EDOM: (libc)Error Codes. |
| * EDOTDOT: (libc)Error Codes. |
| * EDQUOT: (libc)Error Codes. |
| * EEXIST: (libc)Error Codes. |
| * EFAULT: (libc)Error Codes. |
| * EFBIG: (libc)Error Codes. |
| * EFTYPE: (libc)Error Codes. |
| * EGRATUITOUS: (libc)Error Codes. |
| * EGREGIOUS: (libc)Error Codes. |
| * EHOSTDOWN: (libc)Error Codes. |
| * EHOSTUNREACH: (libc)Error Codes. |
| * EHWPOISON: (libc)Error Codes. |
| * EIDRM: (libc)Error Codes. |
| * EIEIO: (libc)Error Codes. |
| * EILSEQ: (libc)Error Codes. |
| * EINPROGRESS: (libc)Error Codes. |
| * EINTR: (libc)Error Codes. |
| * EINVAL: (libc)Error Codes. |
| * EIO: (libc)Error Codes. |
| * EISCONN: (libc)Error Codes. |
| * EISDIR: (libc)Error Codes. |
| * EISNAM: (libc)Error Codes. |
| * EKEYEXPIRED: (libc)Error Codes. |
| * EKEYREJECTED: (libc)Error Codes. |
| * EKEYREVOKED: (libc)Error Codes. |
| * EL2HLT: (libc)Error Codes. |
| * EL2NSYNC: (libc)Error Codes. |
| * EL3HLT: (libc)Error Codes. |
| * EL3RST: (libc)Error Codes. |
| * ELIBACC: (libc)Error Codes. |
| * ELIBBAD: (libc)Error Codes. |
| * ELIBEXEC: (libc)Error Codes. |
| * ELIBMAX: (libc)Error Codes. |
| * ELIBSCN: (libc)Error Codes. |
| * ELNRNG: (libc)Error Codes. |
| * ELOOP: (libc)Error Codes. |
| * EMEDIUMTYPE: (libc)Error Codes. |
| * EMFILE: (libc)Error Codes. |
| * EMLINK: (libc)Error Codes. |
| * EMSGSIZE: (libc)Error Codes. |
| * EMULTIHOP: (libc)Error Codes. |
| * ENAMETOOLONG: (libc)Error Codes. |
| * ENAVAIL: (libc)Error Codes. |
| * ENEEDAUTH: (libc)Error Codes. |
| * ENETDOWN: (libc)Error Codes. |
| * ENETRESET: (libc)Error Codes. |
| * ENETUNREACH: (libc)Error Codes. |
| * ENFILE: (libc)Error Codes. |
| * ENOANO: (libc)Error Codes. |
| * ENOBUFS: (libc)Error Codes. |
| * ENOCSI: (libc)Error Codes. |
| * ENODATA: (libc)Error Codes. |
| * ENODEV: (libc)Error Codes. |
| * ENOENT: (libc)Error Codes. |
| * ENOEXEC: (libc)Error Codes. |
| * ENOKEY: (libc)Error Codes. |
| * ENOLCK: (libc)Error Codes. |
| * ENOLINK: (libc)Error Codes. |
| * ENOMEDIUM: (libc)Error Codes. |
| * ENOMEM: (libc)Error Codes. |
| * ENOMSG: (libc)Error Codes. |
| * ENONET: (libc)Error Codes. |
| * ENOPKG: (libc)Error Codes. |
| * ENOPROTOOPT: (libc)Error Codes. |
| * ENOSPC: (libc)Error Codes. |
| * ENOSR: (libc)Error Codes. |
| * ENOSTR: (libc)Error Codes. |
| * ENOSYS: (libc)Error Codes. |
| * ENOTBLK: (libc)Error Codes. |
| * ENOTCONN: (libc)Error Codes. |
| * ENOTDIR: (libc)Error Codes. |
| * ENOTEMPTY: (libc)Error Codes. |
| * ENOTNAM: (libc)Error Codes. |
| * ENOTRECOVERABLE: (libc)Error Codes. |
| * ENOTSOCK: (libc)Error Codes. |
| * ENOTSUP: (libc)Error Codes. |
| * ENOTTY: (libc)Error Codes. |
| * ENOTUNIQ: (libc)Error Codes. |
| * ENXIO: (libc)Error Codes. |
| * EOF: (libc)EOF and Errors. |
| * EOPNOTSUPP: (libc)Error Codes. |
| * EOVERFLOW: (libc)Error Codes. |
| * EOWNERDEAD: (libc)Error Codes. |
| * EPERM: (libc)Error Codes. |
| * EPFNOSUPPORT: (libc)Error Codes. |
| * EPIPE: (libc)Error Codes. |
| * EPROCLIM: (libc)Error Codes. |
| * EPROCUNAVAIL: (libc)Error Codes. |
| * EPROGMISMATCH: (libc)Error Codes. |
| * EPROGUNAVAIL: (libc)Error Codes. |
| * EPROTO: (libc)Error Codes. |
| * EPROTONOSUPPORT: (libc)Error Codes. |
| * EPROTOTYPE: (libc)Error Codes. |
| * EQUIV_CLASS_MAX: (libc)Utility Limits. |
| * ERANGE: (libc)Error Codes. |
| * EREMCHG: (libc)Error Codes. |
| * EREMOTE: (libc)Error Codes. |
| * EREMOTEIO: (libc)Error Codes. |
| * ERESTART: (libc)Error Codes. |
| * ERFKILL: (libc)Error Codes. |
| * EROFS: (libc)Error Codes. |
| * ERPCMISMATCH: (libc)Error Codes. |
| * ESHUTDOWN: (libc)Error Codes. |
| * ESOCKTNOSUPPORT: (libc)Error Codes. |
| * ESPIPE: (libc)Error Codes. |
| * ESRCH: (libc)Error Codes. |
| * ESRMNT: (libc)Error Codes. |
| * ESTALE: (libc)Error Codes. |
| * ESTRPIPE: (libc)Error Codes. |
| * ETIME: (libc)Error Codes. |
| * ETIMEDOUT: (libc)Error Codes. |
| * ETOOMANYREFS: (libc)Error Codes. |
| * ETXTBSY: (libc)Error Codes. |
| * EUCLEAN: (libc)Error Codes. |
| * EUNATCH: (libc)Error Codes. |
| * EUSERS: (libc)Error Codes. |
| * EWOULDBLOCK: (libc)Error Codes. |
| * EXDEV: (libc)Error Codes. |
| * EXFULL: (libc)Error Codes. |
| * EXIT_FAILURE: (libc)Exit Status. |
| * EXIT_SUCCESS: (libc)Exit Status. |
| * EXPR_NEST_MAX: (libc)Utility Limits. |
| * FD_CLOEXEC: (libc)Descriptor Flags. |
| * FD_CLR: (libc)Waiting for I/O. |
| * FD_ISSET: (libc)Waiting for I/O. |
| * FD_SET: (libc)Waiting for I/O. |
| * FD_SETSIZE: (libc)Waiting for I/O. |
| * FD_ZERO: (libc)Waiting for I/O. |
| * FILENAME_MAX: (libc)Limits for Files. |
| * FLUSHO: (libc)Local Modes. |
| * FOPEN_MAX: (libc)Opening Streams. |
| * FP_ILOGB0: (libc)Exponents and Logarithms. |
| * FP_ILOGBNAN: (libc)Exponents and Logarithms. |
| * F_DUPFD: (libc)Duplicating Descriptors. |
| * F_GETFD: (libc)Descriptor Flags. |
| * F_GETFL: (libc)Getting File Status Flags. |
| * F_GETLK: (libc)File Locks. |
| * F_GETOWN: (libc)Interrupt Input. |
| * F_OK: (libc)Testing File Access. |
| * F_SETFD: (libc)Descriptor Flags. |
| * F_SETFL: (libc)Getting File Status Flags. |
| * F_SETLK: (libc)File Locks. |
| * F_SETLKW: (libc)File Locks. |
| * F_SETOWN: (libc)Interrupt Input. |
| * HUGE_VAL: (libc)Math Error Reporting. |
| * HUGE_VALF: (libc)Math Error Reporting. |
| * HUGE_VALL: (libc)Math Error Reporting. |
| * HUPCL: (libc)Control Modes. |
| * I: (libc)Complex Numbers. |
| * ICANON: (libc)Local Modes. |
| * ICRNL: (libc)Input Modes. |
| * IEXTEN: (libc)Local Modes. |
| * IFNAMSIZ: (libc)Interface Naming. |
| * IFTODT: (libc)Directory Entries. |
| * IGNBRK: (libc)Input Modes. |
| * IGNCR: (libc)Input Modes. |
| * IGNPAR: (libc)Input Modes. |
| * IMAXBEL: (libc)Input Modes. |
| * INADDR_ANY: (libc)Host Address Data Type. |
| * INADDR_BROADCAST: (libc)Host Address Data Type. |
| * INADDR_LOOPBACK: (libc)Host Address Data Type. |
| * INADDR_NONE: (libc)Host Address Data Type. |
| * INFINITY: (libc)Infinity and NaN. |
| * INLCR: (libc)Input Modes. |
| * INPCK: (libc)Input Modes. |
| * IPPORT_RESERVED: (libc)Ports. |
| * IPPORT_USERRESERVED: (libc)Ports. |
| * ISIG: (libc)Local Modes. |
| * ISTRIP: (libc)Input Modes. |
| * IXANY: (libc)Input Modes. |
| * IXOFF: (libc)Input Modes. |
| * IXON: (libc)Input Modes. |
| * LINE_MAX: (libc)Utility Limits. |
| * LINK_MAX: (libc)Limits for Files. |
| * L_ctermid: (libc)Identifying the Terminal. |
| * L_cuserid: (libc)Who Logged In. |
| * L_tmpnam: (libc)Temporary Files. |
| * MAXNAMLEN: (libc)Limits for Files. |
| * MAXSYMLINKS: (libc)Symbolic Links. |
| * MAX_CANON: (libc)Limits for Files. |
| * MAX_INPUT: (libc)Limits for Files. |
| * MB_CUR_MAX: (libc)Selecting the Conversion. |
| * MB_LEN_MAX: (libc)Selecting the Conversion. |
| * MDMBUF: (libc)Control Modes. |
| * MSG_DONTROUTE: (libc)Socket Data Options. |
| * MSG_OOB: (libc)Socket Data Options. |
| * MSG_PEEK: (libc)Socket Data Options. |
| * NAME_MAX: (libc)Limits for Files. |
| * NAN: (libc)Infinity and NaN. |
| * NCCS: (libc)Mode Data Types. |
| * NGROUPS_MAX: (libc)General Limits. |
| * NOFLSH: (libc)Local Modes. |
| * NOKERNINFO: (libc)Local Modes. |
| * NSIG: (libc)Standard Signals. |
| * NULL: (libc)Null Pointer Constant. |
| * ONLCR: (libc)Output Modes. |
| * ONOEOT: (libc)Output Modes. |
| * OPEN_MAX: (libc)General Limits. |
| * OPOST: (libc)Output Modes. |
| * OXTABS: (libc)Output Modes. |
| * O_ACCMODE: (libc)Access Modes. |
| * O_APPEND: (libc)Operating Modes. |
| * O_ASYNC: (libc)Operating Modes. |
| * O_CREAT: (libc)Open-time Flags. |
| * O_EXCL: (libc)Open-time Flags. |
| * O_EXEC: (libc)Access Modes. |
| * O_EXLOCK: (libc)Open-time Flags. |
| * O_FSYNC: (libc)Operating Modes. |
| * O_IGNORE_CTTY: (libc)Open-time Flags. |
| * O_NDELAY: (libc)Operating Modes. |
| * O_NOATIME: (libc)Operating Modes. |
| * O_NOCTTY: (libc)Open-time Flags. |
| * O_NOLINK: (libc)Open-time Flags. |
| * O_NONBLOCK: (libc)Open-time Flags. |
| * O_NONBLOCK: (libc)Operating Modes. |
| * O_NOTRANS: (libc)Open-time Flags. |
| * O_RDONLY: (libc)Access Modes. |
| * O_RDWR: (libc)Access Modes. |
| * O_READ: (libc)Access Modes. |
| * O_SHLOCK: (libc)Open-time Flags. |
| * O_SYNC: (libc)Operating Modes. |
| * O_TRUNC: (libc)Open-time Flags. |
| * O_WRITE: (libc)Access Modes. |
| * O_WRONLY: (libc)Access Modes. |
| * PARENB: (libc)Control Modes. |
| * PARMRK: (libc)Input Modes. |
| * PARODD: (libc)Control Modes. |
| * PATH_MAX: (libc)Limits for Files. |
| * PA_FLAG_MASK: (libc)Parsing a Template String. |
| * PENDIN: (libc)Local Modes. |
| * PF_FILE: (libc)Local Namespace Details. |
| * PF_INET6: (libc)Internet Namespace. |
| * PF_INET: (libc)Internet Namespace. |
| * PF_LOCAL: (libc)Local Namespace Details. |
| * PF_UNIX: (libc)Local Namespace Details. |
| * PIPE_BUF: (libc)Limits for Files. |
| * P_tmpdir: (libc)Temporary Files. |
| * RAND_MAX: (libc)ISO Random. |
| * RE_DUP_MAX: (libc)General Limits. |
| * RLIM_INFINITY: (libc)Limits on Resources. |
| * R_OK: (libc)Testing File Access. |
| * SA_NOCLDSTOP: (libc)Flags for Sigaction. |
| * SA_ONSTACK: (libc)Flags for Sigaction. |
| * SA_RESTART: (libc)Flags for Sigaction. |
| * SEEK_CUR: (libc)File Positioning. |
| * SEEK_END: (libc)File Positioning. |
| * SEEK_SET: (libc)File Positioning. |
| * SIGABRT: (libc)Program Error Signals. |
| * SIGALRM: (libc)Alarm Signals. |
| * SIGBUS: (libc)Program Error Signals. |
| * SIGCHLD: (libc)Job Control Signals. |
| * SIGCLD: (libc)Job Control Signals. |
| * SIGCONT: (libc)Job Control Signals. |
| * SIGEMT: (libc)Program Error Signals. |
| * SIGFPE: (libc)Program Error Signals. |
| * SIGHUP: (libc)Termination Signals. |
| * SIGILL: (libc)Program Error Signals. |
| * SIGINFO: (libc)Miscellaneous Signals. |
| * SIGINT: (libc)Termination Signals. |
| * SIGIO: (libc)Asynchronous I/O Signals. |
| * SIGIOT: (libc)Program Error Signals. |
| * SIGKILL: (libc)Termination Signals. |
| * SIGLOST: (libc)Operation Error Signals. |
| * SIGPIPE: (libc)Operation Error Signals. |
| * SIGPOLL: (libc)Asynchronous I/O Signals. |
| * SIGPROF: (libc)Alarm Signals. |
| * SIGQUIT: (libc)Termination Signals. |
| * SIGSEGV: (libc)Program Error Signals. |
| * SIGSTOP: (libc)Job Control Signals. |
| * SIGSYS: (libc)Program Error Signals. |
| * SIGTERM: (libc)Termination Signals. |
| * SIGTRAP: (libc)Program Error Signals. |
| * SIGTSTP: (libc)Job Control Signals. |
| * SIGTTIN: (libc)Job Control Signals. |
| * SIGTTOU: (libc)Job Control Signals. |
| * SIGURG: (libc)Asynchronous I/O Signals. |
| * SIGUSR1: (libc)Miscellaneous Signals. |
| * SIGUSR2: (libc)Miscellaneous Signals. |
| * SIGVTALRM: (libc)Alarm Signals. |
| * SIGWINCH: (libc)Miscellaneous Signals. |
| * SIGXCPU: (libc)Operation Error Signals. |
| * SIGXFSZ: (libc)Operation Error Signals. |
| * SIG_ERR: (libc)Basic Signal Handling. |
| * SOCK_DGRAM: (libc)Communication Styles. |
| * SOCK_RAW: (libc)Communication Styles. |
| * SOCK_RDM: (libc)Communication Styles. |
| * SOCK_SEQPACKET: (libc)Communication Styles. |
| * SOCK_STREAM: (libc)Communication Styles. |
| * SOL_SOCKET: (libc)Socket-Level Options. |
| * SSIZE_MAX: (libc)General Limits. |
| * STREAM_MAX: (libc)General Limits. |
| * SUN_LEN: (libc)Local Namespace Details. |
| * SV_INTERRUPT: (libc)BSD Handler. |
| * SV_ONSTACK: (libc)BSD Handler. |
| * SV_RESETHAND: (libc)BSD Handler. |
| * S_IFMT: (libc)Testing File Type. |
| * S_ISBLK: (libc)Testing File Type. |
| * S_ISCHR: (libc)Testing File Type. |
| * S_ISDIR: (libc)Testing File Type. |
| * S_ISFIFO: (libc)Testing File Type. |
| * S_ISLNK: (libc)Testing File Type. |
| * S_ISREG: (libc)Testing File Type. |
| * S_ISSOCK: (libc)Testing File Type. |
| * S_TYPEISMQ: (libc)Testing File Type. |
| * S_TYPEISSEM: (libc)Testing File Type. |
| * S_TYPEISSHM: (libc)Testing File Type. |
| * TMP_MAX: (libc)Temporary Files. |
| * TOSTOP: (libc)Local Modes. |
| * TZNAME_MAX: (libc)General Limits. |
| * VDISCARD: (libc)Other Special. |
| * VDSUSP: (libc)Signal Characters. |
| * VEOF: (libc)Editing Characters. |
| * VEOL2: (libc)Editing Characters. |
| * VEOL: (libc)Editing Characters. |
| * VERASE: (libc)Editing Characters. |
| * VINTR: (libc)Signal Characters. |
| * VKILL: (libc)Editing Characters. |
| * VLNEXT: (libc)Other Special. |
| * VMIN: (libc)Noncanonical Input. |
| * VQUIT: (libc)Signal Characters. |
| * VREPRINT: (libc)Editing Characters. |
| * VSTART: (libc)Start/Stop Characters. |
| * VSTATUS: (libc)Other Special. |
| * VSTOP: (libc)Start/Stop Characters. |
| * VSUSP: (libc)Signal Characters. |
| * VTIME: (libc)Noncanonical Input. |
| * VWERASE: (libc)Editing Characters. |
| * WCHAR_MAX: (libc)Extended Char Intro. |
| * WCHAR_MIN: (libc)Extended Char Intro. |
| * WCOREDUMP: (libc)Process Completion Status. |
| * WEOF: (libc)EOF and Errors. |
| * WEOF: (libc)Extended Char Intro. |
| * WEXITSTATUS: (libc)Process Completion Status. |
| * WIFEXITED: (libc)Process Completion Status. |
| * WIFSIGNALED: (libc)Process Completion Status. |
| * WIFSTOPPED: (libc)Process Completion Status. |
| * WSTOPSIG: (libc)Process Completion Status. |
| * WTERMSIG: (libc)Process Completion Status. |
| * W_OK: (libc)Testing File Access. |
| * X_OK: (libc)Testing File Access. |
| * _Complex_I: (libc)Complex Numbers. |
| * _Exit: (libc)Termination Internals. |
| * _IOFBF: (libc)Controlling Buffering. |
| * _IOLBF: (libc)Controlling Buffering. |
| * _IONBF: (libc)Controlling Buffering. |
| * _Imaginary_I: (libc)Complex Numbers. |
| * _PATH_UTMP: (libc)Manipulating the Database. |
| * _PATH_WTMP: (libc)Manipulating the Database. |
| * _POSIX2_C_DEV: (libc)System Options. |
| * _POSIX2_C_VERSION: (libc)Version Supported. |
| * _POSIX2_FORT_DEV: (libc)System Options. |
| * _POSIX2_FORT_RUN: (libc)System Options. |
| * _POSIX2_LOCALEDEF: (libc)System Options. |
| * _POSIX2_SW_DEV: (libc)System Options. |
| * _POSIX_CHOWN_RESTRICTED: (libc)Options for Files. |
| * _POSIX_JOB_CONTROL: (libc)System Options. |
| * _POSIX_NO_TRUNC: (libc)Options for Files. |
| * _POSIX_SAVED_IDS: (libc)System Options. |
| * _POSIX_VDISABLE: (libc)Options for Files. |
| * _POSIX_VERSION: (libc)Version Supported. |
| * __fbufsize: (libc)Controlling Buffering. |
| * __flbf: (libc)Controlling Buffering. |
| * __fpending: (libc)Controlling Buffering. |
| * __fpurge: (libc)Flushing Buffers. |
| * __freadable: (libc)Opening Streams. |
| * __freading: (libc)Opening Streams. |
| * __fsetlocking: (libc)Streams and Threads. |
| * __fwritable: (libc)Opening Streams. |
| * __fwriting: (libc)Opening Streams. |
| * __gconv_end_fct: (libc)glibc iconv Implementation. |
| * __gconv_fct: (libc)glibc iconv Implementation. |
| * __gconv_init_fct: (libc)glibc iconv Implementation. |
| * __ppc_get_timebase: (libc)PowerPC. |
| * __ppc_get_timebase_freq: (libc)PowerPC. |
| * __ppc_mdoio: (libc)PowerPC. |
| * __ppc_mdoom: (libc)PowerPC. |
| * __ppc_set_ppr_low: (libc)PowerPC. |
| * __ppc_set_ppr_med: (libc)PowerPC. |
| * __ppc_set_ppr_med_low: (libc)PowerPC. |
| * __ppc_yield: (libc)PowerPC. |
| * __va_copy: (libc)Argument Macros. |
| * _exit: (libc)Termination Internals. |
| * _flushlbf: (libc)Flushing Buffers. |
| * _tolower: (libc)Case Conversion. |
| * _toupper: (libc)Case Conversion. |
| * a64l: (libc)Encode Binary Data. |
| * abort: (libc)Aborting a Program. |
| * abs: (libc)Absolute Value. |
| * accept: (libc)Accepting Connections. |
| * access: (libc)Testing File Access. |
| * acos: (libc)Inverse Trig Functions. |
| * acosf: (libc)Inverse Trig Functions. |
| * acosh: (libc)Hyperbolic Functions. |
| * acoshf: (libc)Hyperbolic Functions. |
| * acoshl: (libc)Hyperbolic Functions. |
| * acosl: (libc)Inverse Trig Functions. |
| * addmntent: (libc)mtab. |
| * addseverity: (libc)Adding Severity Classes. |
| * adjtime: (libc)High-Resolution Calendar. |
| * adjtimex: (libc)High-Resolution Calendar. |
| * aio_cancel64: (libc)Cancel AIO Operations. |
| * aio_cancel: (libc)Cancel AIO Operations. |
| * aio_error64: (libc)Status of AIO Operations. |
| * aio_error: (libc)Status of AIO Operations. |
| * aio_fsync64: (libc)Synchronizing AIO Operations. |
| * aio_fsync: (libc)Synchronizing AIO Operations. |
| * aio_init: (libc)Configuration of AIO. |
| * aio_read64: (libc)Asynchronous Reads/Writes. |
| * aio_read: (libc)Asynchronous Reads/Writes. |
| * aio_return64: (libc)Status of AIO Operations. |
| * aio_return: (libc)Status of AIO Operations. |
| * aio_suspend64: (libc)Synchronizing AIO Operations. |
| * aio_suspend: (libc)Synchronizing AIO Operations. |
| * aio_write64: (libc)Asynchronous Reads/Writes. |
| * aio_write: (libc)Asynchronous Reads/Writes. |
| * alarm: (libc)Setting an Alarm. |
| * aligned_alloc: (libc)Aligned Memory Blocks. |
| * alloca: (libc)Variable Size Automatic. |
| * alphasort64: (libc)Scanning Directory Content. |
| * alphasort: (libc)Scanning Directory Content. |
| * argp_error: (libc)Argp Helper Functions. |
| * argp_failure: (libc)Argp Helper Functions. |
| * argp_help: (libc)Argp Help. |
| * argp_parse: (libc)Argp. |
| * argp_state_help: (libc)Argp Helper Functions. |
| * argp_usage: (libc)Argp Helper Functions. |
| * argz_add: (libc)Argz Functions. |
| * argz_add_sep: (libc)Argz Functions. |
| * argz_append: (libc)Argz Functions. |
| * argz_count: (libc)Argz Functions. |
| * argz_create: (libc)Argz Functions. |
| * argz_create_sep: (libc)Argz Functions. |
| * argz_delete: (libc)Argz Functions. |
| * argz_extract: (libc)Argz Functions. |
| * argz_insert: (libc)Argz Functions. |
| * argz_next: (libc)Argz Functions. |
| * argz_replace: (libc)Argz Functions. |
| * argz_stringify: (libc)Argz Functions. |
| * asctime: (libc)Formatting Calendar Time. |
| * asctime_r: (libc)Formatting Calendar Time. |
| * asin: (libc)Inverse Trig Functions. |
| * asinf: (libc)Inverse Trig Functions. |
| * asinh: (libc)Hyperbolic Functions. |
| * asinhf: (libc)Hyperbolic Functions. |
| * asinhl: (libc)Hyperbolic Functions. |
| * asinl: (libc)Inverse Trig Functions. |
| * asprintf: (libc)Dynamic Output. |
| * assert: (libc)Consistency Checking. |
| * assert_perror: (libc)Consistency Checking. |
| * atan2: (libc)Inverse Trig Functions. |
| * atan2f: (libc)Inverse Trig Functions. |
| * atan2l: (libc)Inverse Trig Functions. |
| * atan: (libc)Inverse Trig Functions. |
| * atanf: (libc)Inverse Trig Functions. |
| * atanh: (libc)Hyperbolic Functions. |
| * atanhf: (libc)Hyperbolic Functions. |
| * atanhl: (libc)Hyperbolic Functions. |
| * atanl: (libc)Inverse Trig Functions. |
| * atexit: (libc)Cleanups on Exit. |
| * atof: (libc)Parsing of Floats. |
| * atoi: (libc)Parsing of Integers. |
| * atol: (libc)Parsing of Integers. |
| * atoll: (libc)Parsing of Integers. |
| * backtrace: (libc)Backtraces. |
| * backtrace_symbols: (libc)Backtraces. |
| * backtrace_symbols_fd: (libc)Backtraces. |
| * basename: (libc)Finding Tokens in a String. |
| * basename: (libc)Finding Tokens in a String. |
| * bcmp: (libc)String/Array Comparison. |
| * bcopy: (libc)Copying and Concatenation. |
| * bind: (libc)Setting Address. |
| * bind_textdomain_codeset: (libc)Charset conversion in gettext. |
| * bindtextdomain: (libc)Locating gettext catalog. |
| * brk: (libc)Resizing the Data Segment. |
| * bsearch: (libc)Array Search Function. |
| * btowc: (libc)Converting a Character. |
| * bzero: (libc)Copying and Concatenation. |
| * cabs: (libc)Absolute Value. |
| * cabsf: (libc)Absolute Value. |
| * cabsl: (libc)Absolute Value. |
| * cacos: (libc)Inverse Trig Functions. |
| * cacosf: (libc)Inverse Trig Functions. |
| * cacosh: (libc)Hyperbolic Functions. |
| * cacoshf: (libc)Hyperbolic Functions. |
| * cacoshl: (libc)Hyperbolic Functions. |
| * cacosl: (libc)Inverse Trig Functions. |
| * calloc: (libc)Allocating Cleared Space. |
| * canonicalize_file_name: (libc)Symbolic Links. |
| * carg: (libc)Operations on Complex. |
| * cargf: (libc)Operations on Complex. |
| * cargl: (libc)Operations on Complex. |
| * casin: (libc)Inverse Trig Functions. |
| * casinf: (libc)Inverse Trig Functions. |
| * casinh: (libc)Hyperbolic Functions. |
| * casinhf: (libc)Hyperbolic Functions. |
| * casinhl: (libc)Hyperbolic Functions. |
| * casinl: (libc)Inverse Trig Functions. |
| * catan: (libc)Inverse Trig Functions. |
| * catanf: (libc)Inverse Trig Functions. |
| * catanh: (libc)Hyperbolic Functions. |
| * catanhf: (libc)Hyperbolic Functions. |
| * catanhl: (libc)Hyperbolic Functions. |
| * catanl: (libc)Inverse Trig Functions. |
| * catclose: (libc)The catgets Functions. |
| * catgets: (libc)The catgets Functions. |
| * catopen: (libc)The catgets Functions. |
| * cbc_crypt: (libc)DES Encryption. |
| * cbrt: (libc)Exponents and Logarithms. |
| * cbrtf: (libc)Exponents and Logarithms. |
| * cbrtl: (libc)Exponents and Logarithms. |
| * ccos: (libc)Trig Functions. |
| * ccosf: (libc)Trig Functions. |
| * ccosh: (libc)Hyperbolic Functions. |
| * ccoshf: (libc)Hyperbolic Functions. |
| * ccoshl: (libc)Hyperbolic Functions. |
| * ccosl: (libc)Trig Functions. |
| * ceil: (libc)Rounding Functions. |
| * ceilf: (libc)Rounding Functions. |
| * ceill: (libc)Rounding Functions. |
| * cexp: (libc)Exponents and Logarithms. |
| * cexpf: (libc)Exponents and Logarithms. |
| * cexpl: (libc)Exponents and Logarithms. |
| * cfgetispeed: (libc)Line Speed. |
| * cfgetospeed: (libc)Line Speed. |
| * cfmakeraw: (libc)Noncanonical Input. |
| * cfree: (libc)Freeing after Malloc. |
| * cfsetispeed: (libc)Line Speed. |
| * cfsetospeed: (libc)Line Speed. |
| * cfsetspeed: (libc)Line Speed. |
| * chdir: (libc)Working Directory. |
| * chmod: (libc)Setting Permissions. |
| * chown: (libc)File Owner. |
| * cimag: (libc)Operations on Complex. |
| * cimagf: (libc)Operations on Complex. |
| * cimagl: (libc)Operations on Complex. |
| * clearenv: (libc)Environment Access. |
| * clearerr: (libc)Error Recovery. |
| * clearerr_unlocked: (libc)Error Recovery. |
| * clock: (libc)CPU Time. |
| * clog10: (libc)Exponents and Logarithms. |
| * clog10f: (libc)Exponents and Logarithms. |
| * clog10l: (libc)Exponents and Logarithms. |
| * clog: (libc)Exponents and Logarithms. |
| * clogf: (libc)Exponents and Logarithms. |
| * clogl: (libc)Exponents and Logarithms. |
| * close: (libc)Opening and Closing Files. |
| * closedir: (libc)Reading/Closing Directory. |
| * closelog: (libc)closelog. |
| * confstr: (libc)String Parameters. |
| * conj: (libc)Operations on Complex. |
| * conjf: (libc)Operations on Complex. |
| * conjl: (libc)Operations on Complex. |
| * connect: (libc)Connecting. |
| * copysign: (libc)FP Bit Twiddling. |
| * copysignf: (libc)FP Bit Twiddling. |
| * copysignl: (libc)FP Bit Twiddling. |
| * cos: (libc)Trig Functions. |
| * cosf: (libc)Trig Functions. |
| * cosh: (libc)Hyperbolic Functions. |
| * coshf: (libc)Hyperbolic Functions. |
| * coshl: (libc)Hyperbolic Functions. |
| * cosl: (libc)Trig Functions. |
| * cpow: (libc)Exponents and Logarithms. |
| * cpowf: (libc)Exponents and Logarithms. |
| * cpowl: (libc)Exponents and Logarithms. |
| * cproj: (libc)Operations on Complex. |
| * cprojf: (libc)Operations on Complex. |
| * cprojl: (libc)Operations on Complex. |
| * creal: (libc)Operations on Complex. |
| * crealf: (libc)Operations on Complex. |
| * creall: (libc)Operations on Complex. |
| * creat64: (libc)Opening and Closing Files. |
| * creat: (libc)Opening and Closing Files. |
| * crypt: (libc)crypt. |
| * crypt_r: (libc)crypt. |
| * csin: (libc)Trig Functions. |
| * csinf: (libc)Trig Functions. |
| * csinh: (libc)Hyperbolic Functions. |
| * csinhf: (libc)Hyperbolic Functions. |
| * csinhl: (libc)Hyperbolic Functions. |
| * csinl: (libc)Trig Functions. |
| * csqrt: (libc)Exponents and Logarithms. |
| * csqrtf: (libc)Exponents and Logarithms. |
| * csqrtl: (libc)Exponents and Logarithms. |
| * ctan: (libc)Trig Functions. |
| * ctanf: (libc)Trig Functions. |
| * ctanh: (libc)Hyperbolic Functions. |
| * ctanhf: (libc)Hyperbolic Functions. |
| * ctanhl: (libc)Hyperbolic Functions. |
| * ctanl: (libc)Trig Functions. |
| * ctermid: (libc)Identifying the Terminal. |
| * ctime: (libc)Formatting Calendar Time. |
| * ctime_r: (libc)Formatting Calendar Time. |
| * cuserid: (libc)Who Logged In. |
| * dcgettext: (libc)Translation with gettext. |
| * dcngettext: (libc)Advanced gettext functions. |
| * des_setparity: (libc)DES Encryption. |
| * dgettext: (libc)Translation with gettext. |
| * difftime: (libc)Elapsed Time. |
| * dirfd: (libc)Opening a Directory. |
| * dirname: (libc)Finding Tokens in a String. |
| * div: (libc)Integer Division. |
| * dngettext: (libc)Advanced gettext functions. |
| * drand48: (libc)SVID Random. |
| * drand48_r: (libc)SVID Random. |
| * drem: (libc)Remainder Functions. |
| * dremf: (libc)Remainder Functions. |
| * dreml: (libc)Remainder Functions. |
| * dup2: (libc)Duplicating Descriptors. |
| * dup: (libc)Duplicating Descriptors. |
| * ecb_crypt: (libc)DES Encryption. |
| * ecvt: (libc)System V Number Conversion. |
| * ecvt_r: (libc)System V Number Conversion. |
| * encrypt: (libc)DES Encryption. |
| * encrypt_r: (libc)DES Encryption. |
| * endfsent: (libc)fstab. |
| * endgrent: (libc)Scanning All Groups. |
| * endhostent: (libc)Host Names. |
| * endmntent: (libc)mtab. |
| * endnetent: (libc)Networks Database. |
| * endnetgrent: (libc)Lookup Netgroup. |
| * endprotoent: (libc)Protocols Database. |
| * endpwent: (libc)Scanning All Users. |
| * endservent: (libc)Services Database. |
| * endutent: (libc)Manipulating the Database. |
| * endutxent: (libc)XPG Functions. |
| * envz_add: (libc)Envz Functions. |
| * envz_entry: (libc)Envz Functions. |
| * envz_get: (libc)Envz Functions. |
| * envz_merge: (libc)Envz Functions. |
| * envz_strip: (libc)Envz Functions. |
| * erand48: (libc)SVID Random. |
| * erand48_r: (libc)SVID Random. |
| * erf: (libc)Special Functions. |
| * erfc: (libc)Special Functions. |
| * erfcf: (libc)Special Functions. |
| * erfcl: (libc)Special Functions. |
| * erff: (libc)Special Functions. |
| * erfl: (libc)Special Functions. |
| * err: (libc)Error Messages. |
| * errno: (libc)Checking for Errors. |
| * error: (libc)Error Messages. |
| * error_at_line: (libc)Error Messages. |
| * errx: (libc)Error Messages. |
| * execl: (libc)Executing a File. |
| * execle: (libc)Executing a File. |
| * execlp: (libc)Executing a File. |
| * execv: (libc)Executing a File. |
| * execve: (libc)Executing a File. |
| * execvp: (libc)Executing a File. |
| * exit: (libc)Normal Termination. |
| * exp10: (libc)Exponents and Logarithms. |
| * exp10f: (libc)Exponents and Logarithms. |
| * exp10l: (libc)Exponents and Logarithms. |
| * exp2: (libc)Exponents and Logarithms. |
| * exp2f: (libc)Exponents and Logarithms. |
| * exp2l: (libc)Exponents and Logarithms. |
| * exp: (libc)Exponents and Logarithms. |
| * expf: (libc)Exponents and Logarithms. |
| * expl: (libc)Exponents and Logarithms. |
| * expm1: (libc)Exponents and Logarithms. |
| * expm1f: (libc)Exponents and Logarithms. |
| * expm1l: (libc)Exponents and Logarithms. |
| * fabs: (libc)Absolute Value. |
| * fabsf: (libc)Absolute Value. |
| * fabsl: (libc)Absolute Value. |
| * fchdir: (libc)Working Directory. |
| * fchmod: (libc)Setting Permissions. |
| * fchown: (libc)File Owner. |
| * fclose: (libc)Closing Streams. |
| * fcloseall: (libc)Closing Streams. |
| * fcntl: (libc)Control Operations. |
| * fcvt: (libc)System V Number Conversion. |
| * fcvt_r: (libc)System V Number Conversion. |
| * fdatasync: (libc)Synchronizing I/O. |
| * fdim: (libc)Misc FP Arithmetic. |
| * fdimf: (libc)Misc FP Arithmetic. |
| * fdiml: (libc)Misc FP Arithmetic. |
| * fdopen: (libc)Descriptors and Streams. |
| * fdopendir: (libc)Opening a Directory. |
| * feclearexcept: (libc)Status bit operations. |
| * fedisableexcept: (libc)Control Functions. |
| * feenableexcept: (libc)Control Functions. |
| * fegetenv: (libc)Control Functions. |
| * fegetexcept: (libc)Control Functions. |
| * fegetexceptflag: (libc)Status bit operations. |
| * fegetround: (libc)Rounding. |
| * feholdexcept: (libc)Control Functions. |
| * feof: (libc)EOF and Errors. |
| * feof_unlocked: (libc)EOF and Errors. |
| * feraiseexcept: (libc)Status bit operations. |
| * ferror: (libc)EOF and Errors. |
| * ferror_unlocked: (libc)EOF and Errors. |
| * fesetenv: (libc)Control Functions. |
| * fesetexceptflag: (libc)Status bit operations. |
| * fesetround: (libc)Rounding. |
| * fetestexcept: (libc)Status bit operations. |
| * feupdateenv: (libc)Control Functions. |
| * fflush: (libc)Flushing Buffers. |
| * fflush_unlocked: (libc)Flushing Buffers. |
| * fgetc: (libc)Character Input. |
| * fgetc_unlocked: (libc)Character Input. |
| * fgetgrent: (libc)Scanning All Groups. |
| * fgetgrent_r: (libc)Scanning All Groups. |
| * fgetpos64: (libc)Portable Positioning. |
| * fgetpos: (libc)Portable Positioning. |
| * fgetpwent: (libc)Scanning All Users. |
| * fgetpwent_r: (libc)Scanning All Users. |
| * fgets: (libc)Line Input. |
| * fgets_unlocked: (libc)Line Input. |
| * fgetwc: (libc)Character Input. |
| * fgetwc_unlocked: (libc)Character Input. |
| * fgetws: (libc)Line Input. |
| * fgetws_unlocked: (libc)Line Input. |
| * fileno: (libc)Descriptors and Streams. |
| * fileno_unlocked: (libc)Descriptors and Streams. |
| * finite: (libc)Floating Point Classes. |
| * finitef: (libc)Floating Point Classes. |
| * finitel: (libc)Floating Point Classes. |
| * flockfile: (libc)Streams and Threads. |
| * floor: (libc)Rounding Functions. |
| * floorf: (libc)Rounding Functions. |
| * floorl: (libc)Rounding Functions. |
| * fma: (libc)Misc FP Arithmetic. |
| * fmaf: (libc)Misc FP Arithmetic. |
| * fmal: (libc)Misc FP Arithmetic. |
| * fmax: (libc)Misc FP Arithmetic. |
| * fmaxf: (libc)Misc FP Arithmetic. |
| * fmaxl: (libc)Misc FP Arithmetic. |
| * fmemopen: (libc)String Streams. |
| * fmin: (libc)Misc FP Arithmetic. |
| * fminf: (libc)Misc FP Arithmetic. |
| * fminl: (libc)Misc FP Arithmetic. |
| * fmod: (libc)Remainder Functions. |
| * fmodf: (libc)Remainder Functions. |
| * fmodl: (libc)Remainder Functions. |
| * fmtmsg: (libc)Printing Formatted Messages. |
| * fnmatch: (libc)Wildcard Matching. |
| * fopen64: (libc)Opening Streams. |
| * fopen: (libc)Opening Streams. |
| * fopencookie: (libc)Streams and Cookies. |
| * fork: (libc)Creating a Process. |
| * forkpty: (libc)Pseudo-Terminal Pairs. |
| * fpathconf: (libc)Pathconf. |
| * fpclassify: (libc)Floating Point Classes. |
| * fprintf: (libc)Formatted Output Functions. |
| * fputc: (libc)Simple Output. |
| * fputc_unlocked: (libc)Simple Output. |
| * fputs: (libc)Simple Output. |
| * fputs_unlocked: (libc)Simple Output. |
| * fputwc: (libc)Simple Output. |
| * fputwc_unlocked: (libc)Simple Output. |
| * fputws: (libc)Simple Output. |
| * fputws_unlocked: (libc)Simple Output. |
| * fread: (libc)Block Input/Output. |
| * fread_unlocked: (libc)Block Input/Output. |
| * free: (libc)Freeing after Malloc. |
| * freopen64: (libc)Opening Streams. |
| * freopen: (libc)Opening Streams. |
| * frexp: (libc)Normalization Functions. |
| * frexpf: (libc)Normalization Functions. |
| * frexpl: (libc)Normalization Functions. |
| * fscanf: (libc)Formatted Input Functions. |
| * fseek: (libc)File Positioning. |
| * fseeko64: (libc)File Positioning. |
| * fseeko: (libc)File Positioning. |
| * fsetpos64: (libc)Portable Positioning. |
| * fsetpos: (libc)Portable Positioning. |
| * fstat64: (libc)Reading Attributes. |
| * fstat: (libc)Reading Attributes. |
| * fsync: (libc)Synchronizing I/O. |
| * ftell: (libc)File Positioning. |
| * ftello64: (libc)File Positioning. |
| * ftello: (libc)File Positioning. |
| * ftruncate64: (libc)File Size. |
| * ftruncate: (libc)File Size. |
| * ftrylockfile: (libc)Streams and Threads. |
| * ftw64: (libc)Working with Directory Trees. |
| * ftw: (libc)Working with Directory Trees. |
| * funlockfile: (libc)Streams and Threads. |
| * futimes: (libc)File Times. |
| * fwide: (libc)Streams and I18N. |
| * fwprintf: (libc)Formatted Output Functions. |
| * fwrite: (libc)Block Input/Output. |
| * fwrite_unlocked: (libc)Block Input/Output. |
| * fwscanf: (libc)Formatted Input Functions. |
| * gamma: (libc)Special Functions. |
| * gammaf: (libc)Special Functions. |
| * gammal: (libc)Special Functions. |
| * gcvt: (libc)System V Number Conversion. |
| * get_avphys_pages: (libc)Query Memory Parameters. |
| * get_current_dir_name: (libc)Working Directory. |
| * get_nprocs: (libc)Processor Resources. |
| * get_nprocs_conf: (libc)Processor Resources. |
| * get_phys_pages: (libc)Query Memory Parameters. |
| * getauxval: (libc)Auxiliary Vector. |
| * getc: (libc)Character Input. |
| * getc_unlocked: (libc)Character Input. |
| * getchar: (libc)Character Input. |
| * getchar_unlocked: (libc)Character Input. |
| * getcontext: (libc)System V contexts. |
| * getcwd: (libc)Working Directory. |
| * getdate: (libc)General Time String Parsing. |
| * getdate_r: (libc)General Time String Parsing. |
| * getdelim: (libc)Line Input. |
| * getdomainnname: (libc)Host Identification. |
| * getegid: (libc)Reading Persona. |
| * getenv: (libc)Environment Access. |
| * geteuid: (libc)Reading Persona. |
| * getfsent: (libc)fstab. |
| * getfsfile: (libc)fstab. |
| * getfsspec: (libc)fstab. |
| * getgid: (libc)Reading Persona. |
| * getgrent: (libc)Scanning All Groups. |
| * getgrent_r: (libc)Scanning All Groups. |
| * getgrgid: (libc)Lookup Group. |
| * getgrgid_r: (libc)Lookup Group. |
| * getgrnam: (libc)Lookup Group. |
| * getgrnam_r: (libc)Lookup Group. |
| * getgrouplist: (libc)Setting Groups. |
| * getgroups: (libc)Reading Persona. |
| * gethostbyaddr: (libc)Host Names. |
| * gethostbyaddr_r: (libc)Host Names. |
| * gethostbyname2: (libc)Host Names. |
| * gethostbyname2_r: (libc)Host Names. |
| * gethostbyname: (libc)Host Names. |
| * gethostbyname_r: (libc)Host Names. |
| * gethostent: (libc)Host Names. |
| * gethostid: (libc)Host Identification. |
| * gethostname: (libc)Host Identification. |
| * getitimer: (libc)Setting an Alarm. |
| * getline: (libc)Line Input. |
| * getloadavg: (libc)Processor Resources. |
| * getlogin: (libc)Who Logged In. |
| * getmntent: (libc)mtab. |
| * getmntent_r: (libc)mtab. |
| * getnetbyaddr: (libc)Networks Database. |
| * getnetbyname: (libc)Networks Database. |
| * getnetent: (libc)Networks Database. |
| * getnetgrent: (libc)Lookup Netgroup. |
| * getnetgrent_r: (libc)Lookup Netgroup. |
| * getopt: (libc)Using Getopt. |
| * getopt_long: (libc)Getopt Long Options. |
| * getopt_long_only: (libc)Getopt Long Options. |
| * getpagesize: (libc)Query Memory Parameters. |
| * getpass: (libc)getpass. |
| * getpeername: (libc)Who is Connected. |
| * getpgid: (libc)Process Group Functions. |
| * getpgrp: (libc)Process Group Functions. |
| * getpid: (libc)Process Identification. |
| * getppid: (libc)Process Identification. |
| * getpriority: (libc)Traditional Scheduling Functions. |
| * getprotobyname: (libc)Protocols Database. |
| * getprotobynumber: (libc)Protocols Database. |
| * getprotoent: (libc)Protocols Database. |
| * getpt: (libc)Allocation. |
| * getpwent: (libc)Scanning All Users. |
| * getpwent_r: (libc)Scanning All Users. |
| * getpwnam: (libc)Lookup User. |
| * getpwnam_r: (libc)Lookup User. |
| * getpwuid: (libc)Lookup User. |
| * getpwuid_r: (libc)Lookup User. |
| * getrlimit64: (libc)Limits on Resources. |
| * getrlimit: (libc)Limits on Resources. |
| * getrusage: (libc)Resource Usage. |
| * gets: (libc)Line Input. |
| * getservbyname: (libc)Services Database. |
| * getservbyport: (libc)Services Database. |
| * getservent: (libc)Services Database. |
| * getsid: (libc)Process Group Functions. |
| * getsockname: (libc)Reading Address. |
| * getsockopt: (libc)Socket Option Functions. |
| * getsubopt: (libc)Suboptions. |
| * gettext: (libc)Translation with gettext. |
| * gettimeofday: (libc)High-Resolution Calendar. |
| * getuid: (libc)Reading Persona. |
| * getumask: (libc)Setting Permissions. |
| * getutent: (libc)Manipulating the Database. |
| * getutent_r: (libc)Manipulating the Database. |
| * getutid: (libc)Manipulating the Database. |
| * getutid_r: (libc)Manipulating the Database. |
| * getutline: (libc)Manipulating the Database. |
| * getutline_r: (libc)Manipulating the Database. |
| * getutmp: (libc)XPG Functions. |
| * getutmpx: (libc)XPG Functions. |
| * getutxent: (libc)XPG Functions. |
| * getutxid: (libc)XPG Functions. |
| * getutxline: (libc)XPG Functions. |
| * getw: (libc)Character Input. |
| * getwc: (libc)Character Input. |
| * getwc_unlocked: (libc)Character Input. |
| * getwchar: (libc)Character Input. |
| * getwchar_unlocked: (libc)Character Input. |
| * getwd: (libc)Working Directory. |
| * glob64: (libc)Calling Glob. |
| * glob: (libc)Calling Glob. |
| * globfree64: (libc)More Flags for Globbing. |
| * globfree: (libc)More Flags for Globbing. |
| * gmtime: (libc)Broken-down Time. |
| * gmtime_r: (libc)Broken-down Time. |
| * grantpt: (libc)Allocation. |
| * gsignal: (libc)Signaling Yourself. |
| * gtty: (libc)BSD Terminal Modes. |
| * hasmntopt: (libc)mtab. |
| * hcreate: (libc)Hash Search Function. |
| * hcreate_r: (libc)Hash Search Function. |
| * hdestroy: (libc)Hash Search Function. |
| * hdestroy_r: (libc)Hash Search Function. |
| * hsearch: (libc)Hash Search Function. |
| * hsearch_r: (libc)Hash Search Function. |
| * htonl: (libc)Byte Order. |
| * htons: (libc)Byte Order. |
| * hypot: (libc)Exponents and Logarithms. |
| * hypotf: (libc)Exponents and Logarithms. |
| * hypotl: (libc)Exponents and Logarithms. |
| * iconv: (libc)Generic Conversion Interface. |
| * iconv_close: (libc)Generic Conversion Interface. |
| * iconv_open: (libc)Generic Conversion Interface. |
| * if_freenameindex: (libc)Interface Naming. |
| * if_indextoname: (libc)Interface Naming. |
| * if_nameindex: (libc)Interface Naming. |
| * if_nametoindex: (libc)Interface Naming. |
| * ilogb: (libc)Exponents and Logarithms. |
| * ilogbf: (libc)Exponents and Logarithms. |
| * ilogbl: (libc)Exponents and Logarithms. |
| * imaxabs: (libc)Absolute Value. |
| * imaxdiv: (libc)Integer Division. |
| * in6addr_any: (libc)Host Address Data Type. |
| * in6addr_loopback: (libc)Host Address Data Type. |
| * index: (libc)Search Functions. |
| * inet_addr: (libc)Host Address Functions. |
| * inet_aton: (libc)Host Address Functions. |
| * inet_lnaof: (libc)Host Address Functions. |
| * inet_makeaddr: (libc)Host Address Functions. |
| * inet_netof: (libc)Host Address Functions. |
| * inet_network: (libc)Host Address Functions. |
| * inet_ntoa: (libc)Host Address Functions. |
| * inet_ntop: (libc)Host Address Functions. |
| * inet_pton: (libc)Host Address Functions. |
| * initgroups: (libc)Setting Groups. |
| * initstate: (libc)BSD Random. |
| * initstate_r: (libc)BSD Random. |
| * innetgr: (libc)Netgroup Membership. |
| * ioctl: (libc)IOCTLs. |
| * isalnum: (libc)Classification of Characters. |
| * isalpha: (libc)Classification of Characters. |
| * isascii: (libc)Classification of Characters. |
| * isatty: (libc)Is It a Terminal. |
| * isblank: (libc)Classification of Characters. |
| * iscntrl: (libc)Classification of Characters. |
| * isdigit: (libc)Classification of Characters. |
| * isfinite: (libc)Floating Point Classes. |
| * isgraph: (libc)Classification of Characters. |
| * isgreater: (libc)FP Comparison Functions. |
| * isgreaterequal: (libc)FP Comparison Functions. |
| * isinf: (libc)Floating Point Classes. |
| * isinff: (libc)Floating Point Classes. |
| * isinfl: (libc)Floating Point Classes. |
| * isless: (libc)FP Comparison Functions. |
| * islessequal: (libc)FP Comparison Functions. |
| * islessgreater: (libc)FP Comparison Functions. |
| * islower: (libc)Classification of Characters. |
| * isnan: (libc)Floating Point Classes. |
| * isnan: (libc)Floating Point Classes. |
| * isnanf: (libc)Floating Point Classes. |
| * isnanl: (libc)Floating Point Classes. |
| * isnormal: (libc)Floating Point Classes. |
| * isprint: (libc)Classification of Characters. |
| * ispunct: (libc)Classification of Characters. |
| * issignaling: (libc)Floating Point Classes. |
| * isspace: (libc)Classification of Characters. |
| * isunordered: (libc)FP Comparison Functions. |
| * isupper: (libc)Classification of Characters. |
| * iswalnum: (libc)Classification of Wide Characters. |
| * iswalpha: (libc)Classification of Wide Characters. |
| * iswblank: (libc)Classification of Wide Characters. |
| * iswcntrl: (libc)Classification of Wide Characters. |
| * iswctype: (libc)Classification of Wide Characters. |
| * iswdigit: (libc)Classification of Wide Characters. |
| * iswgraph: (libc)Classification of Wide Characters. |
| * iswlower: (libc)Classification of Wide Characters. |
| * iswprint: (libc)Classification of Wide Characters. |
| * iswpunct: (libc)Classification of Wide Characters. |
| * iswspace: (libc)Classification of Wide Characters. |
| * iswupper: (libc)Classification of Wide Characters. |
| * iswxdigit: (libc)Classification of Wide Characters. |
| * isxdigit: (libc)Classification of Characters. |
| * j0: (libc)Special Functions. |
| * j0f: (libc)Special Functions. |
| * j0l: (libc)Special Functions. |
| * j1: (libc)Special Functions. |
| * j1f: (libc)Special Functions. |
| * j1l: (libc)Special Functions. |
| * jn: (libc)Special Functions. |
| * jnf: (libc)Special Functions. |
| * jnl: (libc)Special Functions. |
| * jrand48: (libc)SVID Random. |
| * jrand48_r: (libc)SVID Random. |
| * kill: (libc)Signaling Another Process. |
| * killpg: (libc)Signaling Another Process. |
| * l64a: (libc)Encode Binary Data. |
| * labs: (libc)Absolute Value. |
| * lcong48: (libc)SVID Random. |
| * lcong48_r: (libc)SVID Random. |
| * ldexp: (libc)Normalization Functions. |
| * ldexpf: (libc)Normalization Functions. |
| * ldexpl: (libc)Normalization Functions. |
| * ldiv: (libc)Integer Division. |
| * lfind: (libc)Array Search Function. |
| * lgamma: (libc)Special Functions. |
| * lgamma_r: (libc)Special Functions. |
| * lgammaf: (libc)Special Functions. |
| * lgammaf_r: (libc)Special Functions. |
| * lgammal: (libc)Special Functions. |
| * lgammal_r: (libc)Special Functions. |
| * link: (libc)Hard Links. |
| * lio_listio64: (libc)Asynchronous Reads/Writes. |
| * lio_listio: (libc)Asynchronous Reads/Writes. |
| * listen: (libc)Listening. |
| * llabs: (libc)Absolute Value. |
| * lldiv: (libc)Integer Division. |
| * llrint: (libc)Rounding Functions. |
| * llrintf: (libc)Rounding Functions. |
| * llrintl: (libc)Rounding Functions. |
| * llround: (libc)Rounding Functions. |
| * llroundf: (libc)Rounding Functions. |
| * llroundl: (libc)Rounding Functions. |
| * localeconv: (libc)The Lame Way to Locale Data. |
| * localtime: (libc)Broken-down Time. |
| * localtime_r: (libc)Broken-down Time. |
| * log10: (libc)Exponents and Logarithms. |
| * log10f: (libc)Exponents and Logarithms. |
| * log10l: (libc)Exponents and Logarithms. |
| * log1p: (libc)Exponents and Logarithms. |
| * log1pf: (libc)Exponents and Logarithms. |
| * log1pl: (libc)Exponents and Logarithms. |
| * log2: (libc)Exponents and Logarithms. |
| * log2f: (libc)Exponents and Logarithms. |
| * log2l: (libc)Exponents and Logarithms. |
| * log: (libc)Exponents and Logarithms. |
| * logb: (libc)Exponents and Logarithms. |
| * logbf: (libc)Exponents and Logarithms. |
| * logbl: (libc)Exponents and Logarithms. |
| * logf: (libc)Exponents and Logarithms. |
| * login: (libc)Logging In and Out. |
| * login_tty: (libc)Logging In and Out. |
| * logl: (libc)Exponents and Logarithms. |
| * logout: (libc)Logging In and Out. |
| * logwtmp: (libc)Logging In and Out. |
| * longjmp: (libc)Non-Local Details. |
| * lrand48: (libc)SVID Random. |
| * lrand48_r: (libc)SVID Random. |
| * lrint: (libc)Rounding Functions. |
| * lrintf: (libc)Rounding Functions. |
| * lrintl: (libc)Rounding Functions. |
| * lround: (libc)Rounding Functions. |
| * lroundf: (libc)Rounding Functions. |
| * lroundl: (libc)Rounding Functions. |
| * lsearch: (libc)Array Search Function. |
| * lseek64: (libc)File Position Primitive. |
| * lseek: (libc)File Position Primitive. |
| * lstat64: (libc)Reading Attributes. |
| * lstat: (libc)Reading Attributes. |
| * lutimes: (libc)File Times. |
| * madvise: (libc)Memory-mapped I/O. |
| * makecontext: (libc)System V contexts. |
| * mallinfo: (libc)Statistics of Malloc. |
| * malloc: (libc)Basic Allocation. |
| * mallopt: (libc)Malloc Tunable Parameters. |
| * mblen: (libc)Non-reentrant Character Conversion. |
| * mbrlen: (libc)Converting a Character. |
| * mbrtowc: (libc)Converting a Character. |
| * mbsinit: (libc)Keeping the state. |
| * mbsnrtowcs: (libc)Converting Strings. |
| * mbsrtowcs: (libc)Converting Strings. |
| * mbstowcs: (libc)Non-reentrant String Conversion. |
| * mbtowc: (libc)Non-reentrant Character Conversion. |
| * mcheck: (libc)Heap Consistency Checking. |
| * memalign: (libc)Aligned Memory Blocks. |
| * memccpy: (libc)Copying and Concatenation. |
| * memchr: (libc)Search Functions. |
| * memcmp: (libc)String/Array Comparison. |
| * memcpy: (libc)Copying and Concatenation. |
| * memfrob: (libc)Trivial Encryption. |
| * memmem: (libc)Search Functions. |
| * memmove: (libc)Copying and Concatenation. |
| * mempcpy: (libc)Copying and Concatenation. |
| * memrchr: (libc)Search Functions. |
| * memset: (libc)Copying and Concatenation. |
| * mkdir: (libc)Creating Directories. |
| * mkdtemp: (libc)Temporary Files. |
| * mkfifo: (libc)FIFO Special Files. |
| * mknod: (libc)Making Special Files. |
| * mkstemp: (libc)Temporary Files. |
| * mktemp: (libc)Temporary Files. |
| * mktime: (libc)Broken-down Time. |
| * mlock: (libc)Page Lock Functions. |
| * mlockall: (libc)Page Lock Functions. |
| * mmap64: (libc)Memory-mapped I/O. |
| * mmap: (libc)Memory-mapped I/O. |
| * modf: (libc)Rounding Functions. |
| * modff: (libc)Rounding Functions. |
| * modfl: (libc)Rounding Functions. |
| * mount: (libc)Mount-Unmount-Remount. |
| * mprobe: (libc)Heap Consistency Checking. |
| * mrand48: (libc)SVID Random. |
| * mrand48_r: (libc)SVID Random. |
| * mremap: (libc)Memory-mapped I/O. |
| * msync: (libc)Memory-mapped I/O. |
| * mtrace: (libc)Tracing malloc. |
| * munlock: (libc)Page Lock Functions. |
| * munlockall: (libc)Page Lock Functions. |
| * munmap: (libc)Memory-mapped I/O. |
| * muntrace: (libc)Tracing malloc. |
| * nan: (libc)FP Bit Twiddling. |
| * nanf: (libc)FP Bit Twiddling. |
| * nanl: (libc)FP Bit Twiddling. |
| * nanosleep: (libc)Sleeping. |
| * nearbyint: (libc)Rounding Functions. |
| * nearbyintf: (libc)Rounding Functions. |
| * nearbyintl: (libc)Rounding Functions. |
| * nextafter: (libc)FP Bit Twiddling. |
| * nextafterf: (libc)FP Bit Twiddling. |
| * nextafterl: (libc)FP Bit Twiddling. |
| * nexttoward: (libc)FP Bit Twiddling. |
| * nexttowardf: (libc)FP Bit Twiddling. |
| * nexttowardl: (libc)FP Bit Twiddling. |
| * nftw64: (libc)Working with Directory Trees. |
| * nftw: (libc)Working with Directory Trees. |
| * ngettext: (libc)Advanced gettext functions. |
| * nice: (libc)Traditional Scheduling Functions. |
| * nl_langinfo: (libc)The Elegant and Fast Way. |
| * nrand48: (libc)SVID Random. |
| * nrand48_r: (libc)SVID Random. |
| * ntohl: (libc)Byte Order. |
| * ntohs: (libc)Byte Order. |
| * ntp_adjtime: (libc)High Accuracy Clock. |
| * ntp_gettime: (libc)High Accuracy Clock. |
| * obstack_1grow: (libc)Growing Objects. |
| * obstack_1grow_fast: (libc)Extra Fast Growing. |
| * obstack_alignment_mask: (libc)Obstacks Data Alignment. |
| * obstack_alloc: (libc)Allocation in an Obstack. |
| * obstack_base: (libc)Status of an Obstack. |
| * obstack_blank: (libc)Growing Objects. |
| * obstack_blank_fast: (libc)Extra Fast Growing. |
| * obstack_chunk_size: (libc)Obstack Chunks. |
| * obstack_copy0: (libc)Allocation in an Obstack. |
| * obstack_copy: (libc)Allocation in an Obstack. |
| * obstack_finish: (libc)Growing Objects. |
| * obstack_free: (libc)Freeing Obstack Objects. |
| * obstack_grow0: (libc)Growing Objects. |
| * obstack_grow: (libc)Growing Objects. |
| * obstack_init: (libc)Preparing for Obstacks. |
| * obstack_int_grow: (libc)Growing Objects. |
| * obstack_int_grow_fast: (libc)Extra Fast Growing. |
| * obstack_next_free: (libc)Status of an Obstack. |
| * obstack_object_size: (libc)Growing Objects. |
| * obstack_object_size: (libc)Status of an Obstack. |
| * obstack_printf: (libc)Dynamic Output. |
| * obstack_ptr_grow: (libc)Growing Objects. |
| * obstack_ptr_grow_fast: (libc)Extra Fast Growing. |
| * obstack_room: (libc)Extra Fast Growing. |
| * obstack_vprintf: (libc)Variable Arguments Output. |
| * offsetof: (libc)Structure Measurement. |
| * on_exit: (libc)Cleanups on Exit. |
| * open64: (libc)Opening and Closing Files. |
| * open: (libc)Opening and Closing Files. |
| * open_memstream: (libc)String Streams. |
| * opendir: (libc)Opening a Directory. |
| * openlog: (libc)openlog. |
| * openpty: (libc)Pseudo-Terminal Pairs. |
| * parse_printf_format: (libc)Parsing a Template String. |
| * pathconf: (libc)Pathconf. |
| * pause: (libc)Using Pause. |
| * pclose: (libc)Pipe to a Subprocess. |
| * perror: (libc)Error Messages. |
| * pipe: (libc)Creating a Pipe. |
| * popen: (libc)Pipe to a Subprocess. |
| * posix_memalign: (libc)Aligned Memory Blocks. |
| * pow10: (libc)Exponents and Logarithms. |
| * pow10f: (libc)Exponents and Logarithms. |
| * pow10l: (libc)Exponents and Logarithms. |
| * pow: (libc)Exponents and Logarithms. |
| * powf: (libc)Exponents and Logarithms. |
| * powl: (libc)Exponents and Logarithms. |
| * pread64: (libc)I/O Primitives. |
| * pread: (libc)I/O Primitives. |
| * printf: (libc)Formatted Output Functions. |
| * printf_size: (libc)Predefined Printf Handlers. |
| * printf_size_info: (libc)Predefined Printf Handlers. |
| * psignal: (libc)Signal Messages. |
| * pthread_getattr_default_np: (libc)Default Thread Attributes. |
| * pthread_getspecific: (libc)Thread-specific Data. |
| * pthread_key_create: (libc)Thread-specific Data. |
| * pthread_key_delete: (libc)Thread-specific Data. |
| * pthread_setattr_default_np: (libc)Default Thread Attributes. |
| * pthread_setspecific: (libc)Thread-specific Data. |
| * ptsname: (libc)Allocation. |
| * ptsname_r: (libc)Allocation. |
| * putc: (libc)Simple Output. |
| * putc_unlocked: (libc)Simple Output. |
| * putchar: (libc)Simple Output. |
| * putchar_unlocked: (libc)Simple Output. |
| * putenv: (libc)Environment Access. |
| * putpwent: (libc)Writing a User Entry. |
| * puts: (libc)Simple Output. |
| * pututline: (libc)Manipulating the Database. |
| * pututxline: (libc)XPG Functions. |
| * putw: (libc)Simple Output. |
| * putwc: (libc)Simple Output. |
| * putwc_unlocked: (libc)Simple Output. |
| * putwchar: (libc)Simple Output. |
| * putwchar_unlocked: (libc)Simple Output. |
| * pwrite64: (libc)I/O Primitives. |
| * pwrite: (libc)I/O Primitives. |
| * qecvt: (libc)System V Number Conversion. |
| * qecvt_r: (libc)System V Number Conversion. |
| * qfcvt: (libc)System V Number Conversion. |
| * qfcvt_r: (libc)System V Number Conversion. |
| * qgcvt: (libc)System V Number Conversion. |
| * qsort: (libc)Array Sort Function. |
| * raise: (libc)Signaling Yourself. |
| * rand: (libc)ISO Random. |
| * rand_r: (libc)ISO Random. |
| * random: (libc)BSD Random. |
| * random_r: (libc)BSD Random. |
| * rawmemchr: (libc)Search Functions. |
| * read: (libc)I/O Primitives. |
| * readdir64: (libc)Reading/Closing Directory. |
| * readdir64_r: (libc)Reading/Closing Directory. |
| * readdir: (libc)Reading/Closing Directory. |
| * readdir_r: (libc)Reading/Closing Directory. |
| * readlink: (libc)Symbolic Links. |
| * readv: (libc)Scatter-Gather. |
| * realloc: (libc)Changing Block Size. |
| * realpath: (libc)Symbolic Links. |
| * recv: (libc)Receiving Data. |
| * recvfrom: (libc)Receiving Datagrams. |
| * recvmsg: (libc)Receiving Datagrams. |
| * regcomp: (libc)POSIX Regexp Compilation. |
| * regerror: (libc)Regexp Cleanup. |
| * regexec: (libc)Matching POSIX Regexps. |
| * regfree: (libc)Regexp Cleanup. |
| * register_printf_function: (libc)Registering New Conversions. |
| * remainder: (libc)Remainder Functions. |
| * remainderf: (libc)Remainder Functions. |
| * remainderl: (libc)Remainder Functions. |
| * remove: (libc)Deleting Files. |
| * rename: (libc)Renaming Files. |
| * rewind: (libc)File Positioning. |
| * rewinddir: (libc)Random Access Directory. |
| * rindex: (libc)Search Functions. |
| * rint: (libc)Rounding Functions. |
| * rintf: (libc)Rounding Functions. |
| * rintl: (libc)Rounding Functions. |
| * rmdir: (libc)Deleting Files. |
| * round: (libc)Rounding Functions. |
| * roundf: (libc)Rounding Functions. |
| * roundl: (libc)Rounding Functions. |
| * rpmatch: (libc)Yes-or-No Questions. |
| * sbrk: (libc)Resizing the Data Segment. |
| * scalb: (libc)Normalization Functions. |
| * scalbf: (libc)Normalization Functions. |
| * scalbl: (libc)Normalization Functions. |
| * scalbln: (libc)Normalization Functions. |
| * scalblnf: (libc)Normalization Functions. |
| * scalblnl: (libc)Normalization Functions. |
| * scalbn: (libc)Normalization Functions. |
| * scalbnf: (libc)Normalization Functions. |
| * scalbnl: (libc)Normalization Functions. |
| * scandir64: (libc)Scanning Directory Content. |
| * scandir: (libc)Scanning Directory Content. |
| * scanf: (libc)Formatted Input Functions. |
| * sched_get_priority_max: (libc)Basic Scheduling Functions. |
| * sched_get_priority_min: (libc)Basic Scheduling Functions. |
| * sched_getaffinity: (libc)CPU Affinity. |
| * sched_getparam: (libc)Basic Scheduling Functions. |
| * sched_getscheduler: (libc)Basic Scheduling Functions. |
| * sched_rr_get_interval: (libc)Basic Scheduling Functions. |
| * sched_setaffinity: (libc)CPU Affinity. |
| * sched_setparam: (libc)Basic Scheduling Functions. |
| * sched_setscheduler: (libc)Basic Scheduling Functions. |
| * sched_yield: (libc)Basic Scheduling Functions. |
| * secure_getenv: (libc)Environment Access. |
| * seed48: (libc)SVID Random. |
| * seed48_r: (libc)SVID Random. |
| * seekdir: (libc)Random Access Directory. |
| * select: (libc)Waiting for I/O. |
| * send: (libc)Sending Data. |
| * sendmsg: (libc)Receiving Datagrams. |
| * sendto: (libc)Sending Datagrams. |
| * setbuf: (libc)Controlling Buffering. |
| * setbuffer: (libc)Controlling Buffering. |
| * setcontext: (libc)System V contexts. |
| * setdomainname: (libc)Host Identification. |
| * setegid: (libc)Setting Groups. |
| * setenv: (libc)Environment Access. |
| * seteuid: (libc)Setting User ID. |
| * setfsent: (libc)fstab. |
| * setgid: (libc)Setting Groups. |
| * setgrent: (libc)Scanning All Groups. |
| * setgroups: (libc)Setting Groups. |
| * sethostent: (libc)Host Names. |
| * sethostid: (libc)Host Identification. |
| * sethostname: (libc)Host Identification. |
| * setitimer: (libc)Setting an Alarm. |
| * setjmp: (libc)Non-Local Details. |
| * setkey: (libc)DES Encryption. |
| * setkey_r: (libc)DES Encryption. |
| * setlinebuf: (libc)Controlling Buffering. |
| * setlocale: (libc)Setting the Locale. |
| * setlogmask: (libc)setlogmask. |
| * setmntent: (libc)mtab. |
| * setnetent: (libc)Networks Database. |
| * setnetgrent: (libc)Lookup Netgroup. |
| * setpgid: (libc)Process Group Functions. |
| * setpgrp: (libc)Process Group Functions. |
| * setpriority: (libc)Traditional Scheduling Functions. |
| * setprotoent: (libc)Protocols Database. |
| * setpwent: (libc)Scanning All Users. |
| * setregid: (libc)Setting Groups. |
| * setreuid: (libc)Setting User ID. |
| * setrlimit64: (libc)Limits on Resources. |
| * setrlimit: (libc)Limits on Resources. |
| * setservent: (libc)Services Database. |
| * setsid: (libc)Process Group Functions. |
| * setsockopt: (libc)Socket Option Functions. |
| * setstate: (libc)BSD Random. |
| * setstate_r: (libc)BSD Random. |
| * settimeofday: (libc)High-Resolution Calendar. |
| * setuid: (libc)Setting User ID. |
| * setutent: (libc)Manipulating the Database. |
| * setutxent: (libc)XPG Functions. |
| * setvbuf: (libc)Controlling Buffering. |
| * shm_open: (libc)Memory-mapped I/O. |
| * shm_unlink: (libc)Memory-mapped I/O. |
| * shutdown: (libc)Closing a Socket. |
| * sigaction: (libc)Advanced Signal Handling. |
| * sigaddset: (libc)Signal Sets. |
| * sigaltstack: (libc)Signal Stack. |
| * sigblock: (libc)Blocking in BSD. |
| * sigdelset: (libc)Signal Sets. |
| * sigemptyset: (libc)Signal Sets. |
| * sigfillset: (libc)Signal Sets. |
| * siginterrupt: (libc)BSD Handler. |
| * sigismember: (libc)Signal Sets. |
| * siglongjmp: (libc)Non-Local Exits and Signals. |
| * sigmask: (libc)Blocking in BSD. |
| * signal: (libc)Basic Signal Handling. |
| * signbit: (libc)FP Bit Twiddling. |
| * significand: (libc)Normalization Functions. |
| * significandf: (libc)Normalization Functions. |
| * significandl: (libc)Normalization Functions. |
| * sigpause: (libc)Blocking in BSD. |
| * sigpending: (libc)Checking for Pending Signals. |
| * sigprocmask: (libc)Process Signal Mask. |
| * sigsetjmp: (libc)Non-Local Exits and Signals. |
| * sigsetmask: (libc)Blocking in BSD. |
| * sigstack: (libc)Signal Stack. |
| * sigsuspend: (libc)Sigsuspend. |
| * sigvec: (libc)BSD Handler. |
| * sin: (libc)Trig Functions. |
| * sincos: (libc)Trig Functions. |
| * sincosf: (libc)Trig Functions. |
| * sincosl: (libc)Trig Functions. |
| * sinf: (libc)Trig Functions. |
| * sinh: (libc)Hyperbolic Functions. |
| * sinhf: (libc)Hyperbolic Functions. |
| * sinhl: (libc)Hyperbolic Functions. |
| * sinl: (libc)Trig Functions. |
| * sleep: (libc)Sleeping. |
| * snprintf: (libc)Formatted Output Functions. |
| * socket: (libc)Creating a Socket. |
| * socketpair: (libc)Socket Pairs. |
| * sprintf: (libc)Formatted Output Functions. |
| * sqrt: (libc)Exponents and Logarithms. |
| * sqrtf: (libc)Exponents and Logarithms. |
| * sqrtl: (libc)Exponents and Logarithms. |
| * srand48: (libc)SVID Random. |
| * srand48_r: (libc)SVID Random. |
| * srand: (libc)ISO Random. |
| * srandom: (libc)BSD Random. |
| * srandom_r: (libc)BSD Random. |
| * sscanf: (libc)Formatted Input Functions. |
| * ssignal: (libc)Basic Signal Handling. |
| * stat64: (libc)Reading Attributes. |
| * stat: (libc)Reading Attributes. |
| * stime: (libc)Simple Calendar Time. |
| * stpcpy: (libc)Copying and Concatenation. |
| * stpncpy: (libc)Copying and Concatenation. |
| * strcasecmp: (libc)String/Array Comparison. |
| * strcasestr: (libc)Search Functions. |
| * strcat: (libc)Copying and Concatenation. |
| * strchr: (libc)Search Functions. |
| * strchrnul: (libc)Search Functions. |
| * strcmp: (libc)String/Array Comparison. |
| * strcoll: (libc)Collation Functions. |
| * strcpy: (libc)Copying and Concatenation. |
| * strcspn: (libc)Search Functions. |
| * strdup: (libc)Copying and Concatenation. |
| * strdupa: (libc)Copying and Concatenation. |
| * strerror: (libc)Error Messages. |
| * strerror_r: (libc)Error Messages. |
| * strfmon: (libc)Formatting Numbers. |
| * strfry: (libc)strfry. |
| * strftime: (libc)Formatting Calendar Time. |
| * strlen: (libc)String Length. |
| * strncasecmp: (libc)String/Array Comparison. |
| * strncat: (libc)Copying and Concatenation. |
| * strncmp: (libc)String/Array Comparison. |
| * strncpy: (libc)Copying and Concatenation. |
| * strndup: (libc)Copying and Concatenation. |
| * strndupa: (libc)Copying and Concatenation. |
| * strnlen: (libc)String Length. |
| * strpbrk: (libc)Search Functions. |
| * strptime: (libc)Low-Level Time String Parsing. |
| * strrchr: (libc)Search Functions. |
| * strsep: (libc)Finding Tokens in a String. |
| * strsignal: (libc)Signal Messages. |
| * strspn: (libc)Search Functions. |
| * strstr: (libc)Search Functions. |
| * strtod: (libc)Parsing of Floats. |
| * strtof: (libc)Parsing of Floats. |
| * strtoimax: (libc)Parsing of Integers. |
| * strtok: (libc)Finding Tokens in a String. |
| * strtok_r: (libc)Finding Tokens in a String. |
| * strtol: (libc)Parsing of Integers. |
| * strtold: (libc)Parsing of Floats. |
| * strtoll: (libc)Parsing of Integers. |
| * strtoq: (libc)Parsing of Integers. |
| * strtoul: (libc)Parsing of Integers. |
| * strtoull: (libc)Parsing of Integers. |
| * strtoumax: (libc)Parsing of Integers. |
| * strtouq: (libc)Parsing of Integers. |
| * strverscmp: (libc)String/Array Comparison. |
| * strxfrm: (libc)Collation Functions. |
| * stty: (libc)BSD Terminal Modes. |
| * swapcontext: (libc)System V contexts. |
| * swprintf: (libc)Formatted Output Functions. |
| * swscanf: (libc)Formatted Input Functions. |
| * symlink: (libc)Symbolic Links. |
| * sync: (libc)Synchronizing I/O. |
| * syscall: (libc)System Calls. |
| * sysconf: (libc)Sysconf Definition. |
| * sysctl: (libc)System Parameters. |
| * syslog: (libc)syslog; vsyslog. |
| * system: (libc)Running a Command. |
| * sysv_signal: (libc)Basic Signal Handling. |
| * tan: (libc)Trig Functions. |
| * tanf: (libc)Trig Functions. |
| * tanh: (libc)Hyperbolic Functions. |
| * tanhf: (libc)Hyperbolic Functions. |
| * tanhl: (libc)Hyperbolic Functions. |
| * tanl: (libc)Trig Functions. |
| * tcdrain: (libc)Line Control. |
| * tcflow: (libc)Line Control. |
| * tcflush: (libc)Line Control. |
| * tcgetattr: (libc)Mode Functions. |
| * tcgetpgrp: (libc)Terminal Access Functions. |
| * tcgetsid: (libc)Terminal Access Functions. |
| * tcsendbreak: (libc)Line Control. |
| * tcsetattr: (libc)Mode Functions. |
| * tcsetpgrp: (libc)Terminal Access Functions. |
| * tdelete: (libc)Tree Search Function. |
| * tdestroy: (libc)Tree Search Function. |
| * telldir: (libc)Random Access Directory. |
| * tempnam: (libc)Temporary Files. |
| * textdomain: (libc)Locating gettext catalog. |
| * tfind: (libc)Tree Search Function. |
| * tgamma: (libc)Special Functions. |
| * tgammaf: (libc)Special Functions. |
| * tgammal: (libc)Special Functions. |
| * time: (libc)Simple Calendar Time. |
| * timegm: (libc)Broken-down Time. |
| * timelocal: (libc)Broken-down Time. |
| * times: (libc)Processor Time. |
| * tmpfile64: (libc)Temporary Files. |
| * tmpfile: (libc)Temporary Files. |
| * tmpnam: (libc)Temporary Files. |
| * tmpnam_r: (libc)Temporary Files. |
| * toascii: (libc)Case Conversion. |
| * tolower: (libc)Case Conversion. |
| * toupper: (libc)Case Conversion. |
| * towctrans: (libc)Wide Character Case Conversion. |
| * towlower: (libc)Wide Character Case Conversion. |
| * towupper: (libc)Wide Character Case Conversion. |
| * trunc: (libc)Rounding Functions. |
| * truncate64: (libc)File Size. |
| * truncate: (libc)File Size. |
| * truncf: (libc)Rounding Functions. |
| * truncl: (libc)Rounding Functions. |
| * tsearch: (libc)Tree Search Function. |
| * ttyname: (libc)Is It a Terminal. |
| * ttyname_r: (libc)Is It a Terminal. |
| * twalk: (libc)Tree Search Function. |
| * tzset: (libc)Time Zone Functions. |
| * ulimit: (libc)Limits on Resources. |
| * umask: (libc)Setting Permissions. |
| * umount2: (libc)Mount-Unmount-Remount. |
| * umount: (libc)Mount-Unmount-Remount. |
| * uname: (libc)Platform Type. |
| * ungetc: (libc)How Unread. |
| * ungetwc: (libc)How Unread. |
| * unlink: (libc)Deleting Files. |
| * unlockpt: (libc)Allocation. |
| * unsetenv: (libc)Environment Access. |
| * updwtmp: (libc)Manipulating the Database. |
| * utime: (libc)File Times. |
| * utimes: (libc)File Times. |
| * utmpname: (libc)Manipulating the Database. |
| * utmpxname: (libc)XPG Functions. |
| * va_arg: (libc)Argument Macros. |
| * va_copy: (libc)Argument Macros. |
| * va_end: (libc)Argument Macros. |
| * va_start: (libc)Argument Macros. |
| * valloc: (libc)Aligned Memory Blocks. |
| * vasprintf: (libc)Variable Arguments Output. |
| * verr: (libc)Error Messages. |
| * verrx: (libc)Error Messages. |
| * versionsort64: (libc)Scanning Directory Content. |
| * versionsort: (libc)Scanning Directory Content. |
| * vfork: (libc)Creating a Process. |
| * vfprintf: (libc)Variable Arguments Output. |
| * vfscanf: (libc)Variable Arguments Input. |
| * vfwprintf: (libc)Variable Arguments Output. |
| * vfwscanf: (libc)Variable Arguments Input. |
| * vlimit: (libc)Limits on Resources. |
| * vprintf: (libc)Variable Arguments Output. |
| * vscanf: (libc)Variable Arguments Input. |
| * vsnprintf: (libc)Variable Arguments Output. |
| * vsprintf: (libc)Variable Arguments Output. |
| * vsscanf: (libc)Variable Arguments Input. |
| * vswprintf: (libc)Variable Arguments Output. |
| * vswscanf: (libc)Variable Arguments Input. |
| * vsyslog: (libc)syslog; vsyslog. |
| * vtimes: (libc)Resource Usage. |
| * vwarn: (libc)Error Messages. |
| * vwarnx: (libc)Error Messages. |
| * vwprintf: (libc)Variable Arguments Output. |
| * vwscanf: (libc)Variable Arguments Input. |
| * wait3: (libc)BSD Wait Functions. |
| * wait4: (libc)Process Completion. |
| * wait: (libc)Process Completion. |
| * waitpid: (libc)Process Completion. |
| * warn: (libc)Error Messages. |
| * warnx: (libc)Error Messages. |
| * wcpcpy: (libc)Copying and Concatenation. |
| * wcpncpy: (libc)Copying and Concatenation. |
| * wcrtomb: (libc)Converting a Character. |
| * wcscasecmp: (libc)String/Array Comparison. |
| * wcscat: (libc)Copying and Concatenation. |
| * wcschr: (libc)Search Functions. |
| * wcschrnul: (libc)Search Functions. |
| * wcscmp: (libc)String/Array Comparison. |
| * wcscoll: (libc)Collation Functions. |
| * wcscpy: (libc)Copying and Concatenation. |
| * wcscspn: (libc)Search Functions. |
| * wcsdup: (libc)Copying and Concatenation. |
| * wcsftime: (libc)Formatting Calendar Time. |
| * wcslen: (libc)String Length. |
| * wcsncasecmp: (libc)String/Array Comparison. |
| * wcsncat: (libc)Copying and Concatenation. |
| * wcsncmp: (libc)String/Array Comparison. |
| * wcsncpy: (libc)Copying and Concatenation. |
| * wcsnlen: (libc)String Length. |
| * wcsnrtombs: (libc)Converting Strings. |
| * wcspbrk: (libc)Search Functions. |
| * wcsrchr: (libc)Search Functions. |
| * wcsrtombs: (libc)Converting Strings. |
| * wcsspn: (libc)Search Functions. |
| * wcsstr: (libc)Search Functions. |
| * wcstod: (libc)Parsing of Floats. |
| * wcstof: (libc)Parsing of Floats. |
| * wcstoimax: (libc)Parsing of Integers. |
| * wcstok: (libc)Finding Tokens in a String. |
| * wcstol: (libc)Parsing of Integers. |
| * wcstold: (libc)Parsing of Floats. |
| * wcstoll: (libc)Parsing of Integers. |
| * wcstombs: (libc)Non-reentrant String Conversion. |
| * wcstoq: (libc)Parsing of Integers. |
| * wcstoul: (libc)Parsing of Integers. |
| * wcstoull: (libc)Parsing of Integers. |
| * wcstoumax: (libc)Parsing of Integers. |
| * wcstouq: (libc)Parsing of Integers. |
| * wcswcs: (libc)Search Functions. |
| * wcsxfrm: (libc)Collation Functions. |
| * wctob: (libc)Converting a Character. |
| * wctomb: (libc)Non-reentrant Character Conversion. |
| * wctrans: (libc)Wide Character Case Conversion. |
| * wctype: (libc)Classification of Wide Characters. |
| * wmemchr: (libc)Search Functions. |
| * wmemcmp: (libc)String/Array Comparison. |
| * wmemcpy: (libc)Copying and Concatenation. |
| * wmemmove: (libc)Copying and Concatenation. |
| * wmempcpy: (libc)Copying and Concatenation. |
| * wmemset: (libc)Copying and Concatenation. |
| * wordexp: (libc)Calling Wordexp. |
| * wordfree: (libc)Calling Wordexp. |
| * wprintf: (libc)Formatted Output Functions. |
| * write: (libc)I/O Primitives. |
| * writev: (libc)Scatter-Gather. |
| * wscanf: (libc)Formatted Input Functions. |
| * y0: (libc)Special Functions. |
| * y0f: (libc)Special Functions. |
| * y0l: (libc)Special Functions. |
| * y1: (libc)Special Functions. |
| * y1f: (libc)Special Functions. |
| * y1l: (libc)Special Functions. |
| * yn: (libc)Special Functions. |
| * ynf: (libc)Special Functions. |
| * ynl: (libc)Special Functions. |
| END-INFO-DIR-ENTRY |
| |
| |
| File: libc.info, Node: CPU Affinity, Prev: Traditional Scheduling, Up: Priority |
| |
| 22.3.5 Limiting execution to certain CPUs |
| ----------------------------------------- |
| |
| On a multi-processor system the operating system usually distributes the |
| different processes which are runnable on all available CPUs in a way |
| which allows the system to work most efficiently. Which processes and |
| threads run can be to some extend be control with the scheduling |
| functionality described in the last sections. But which CPU finally |
| executes which process or thread is not covered. |
| |
| There are a number of reasons why a program might want to have |
| control over this aspect of the system as well: |
| |
| * One thread or process is responsible for absolutely critical work |
| which under no circumstances must be interrupted or hindered from |
| making process by other process or threads using CPU resources. In |
| this case the special process would be confined to a CPU which no |
| other process or thread is allowed to use. |
| |
| * The access to certain resources (RAM, I/O ports) has different |
| costs from different CPUs. This is the case in NUMA (Non-Uniform |
| Memory Architecture) machines. Preferably memory should be |
| accessed locally but this requirement is usually not visible to the |
| scheduler. Therefore forcing a process or thread to the CPUs which |
| have local access to the mostly used memory helps to significantly |
| boost the performance. |
| |
| * In controlled runtimes resource allocation and book-keeping work |
| (for instance garbage collection) is performance local to |
| processors. This can help to reduce locking costs if the resources |
| do not have to be protected from concurrent accesses from different |
| processors. |
| |
| The POSIX standard up to this date is of not much help to solve this |
| problem. The Linux kernel provides a set of interfaces to allow |
| specifying _affinity sets_ for a process. The scheduler will schedule |
| the thread or process on CPUs specified by the affinity masks. The |
| interfaces which the GNU C Library define follow to some extend the |
| Linux kernel interface. |
| |
| -- Data Type: cpu_set_t |
| This data set is a bitset where each bit represents a CPU. How the |
| system's CPUs are mapped to bits in the bitset is system dependent. |
| The data type has a fixed size; in the unlikely case that the |
| number of bits are not sufficient to describe the CPUs of the |
| system a different interface has to be used. |
| |
| This type is a GNU extension and is defined in 'sched.h'. |
| |
| To manipulate the bitset, to set and reset bits, a number of macros |
| is defined. Some of the macros take a CPU number as a parameter. Here |
| it is important to never exceed the size of the bitset. The following |
| macro specifies the number of bits in the 'cpu_set_t' bitset. |
| |
| -- Macro: int CPU_SETSIZE |
| The value of this macro is the maximum number of CPUs which can be |
| handled with a 'cpu_set_t' object. |
| |
| The type 'cpu_set_t' should be considered opaque; all manipulation |
| should happen via the next four macros. |
| |
| -- Macro: void CPU_ZERO (cpu_set_t *SET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro initializes the CPU set SET to be the empty set. |
| |
| This macro is a GNU extension and is defined in 'sched.h'. |
| |
| -- Macro: void CPU_SET (int CPU, cpu_set_t *SET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro adds CPU to the CPU set SET. |
| |
| The CPU parameter must not have side effects since it is evaluated |
| more than once. |
| |
| This macro is a GNU extension and is defined in 'sched.h'. |
| |
| -- Macro: void CPU_CLR (int CPU, cpu_set_t *SET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro removes CPU from the CPU set SET. |
| |
| The CPU parameter must not have side effects since it is evaluated |
| more than once. |
| |
| This macro is a GNU extension and is defined in 'sched.h'. |
| |
| -- Macro: int CPU_ISSET (int CPU, const cpu_set_t *SET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro returns a nonzero value (true) if CPU is a member of the |
| CPU set SET, and zero (false) otherwise. |
| |
| The CPU parameter must not have side effects since it is evaluated |
| more than once. |
| |
| This macro is a GNU extension and is defined in 'sched.h'. |
| |
| CPU bitsets can be constructed from scratch or the currently |
| installed affinity mask can be retrieved from the system. |
| |
| -- Function: int sched_getaffinity (pid_t PID, size_t CPUSETSIZE, |
| cpu_set_t *CPUSET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This functions stores the CPU affinity mask for the process or |
| thread with the ID PID in the CPUSETSIZE bytes long bitmap pointed |
| to by CPUSET. If successful, the function always initializes all |
| bits in the 'cpu_set_t' object and returns zero. |
| |
| If PID does not correspond to a process or thread on the system the |
| or the function fails for some other reason, it returns '-1' and |
| 'errno' is set to represent the error condition. |
| |
| 'ESRCH' |
| No process or thread with the given ID found. |
| |
| 'EFAULT' |
| The pointer CPUSET is does not point to a valid object. |
| |
| This function is a GNU extension and is declared in 'sched.h'. |
| |
| Note that it is not portably possible to use this information to |
| retrieve the information for different POSIX threads. A separate |
| interface must be provided for that. |
| |
| -- Function: int sched_setaffinity (pid_t PID, size_t CPUSETSIZE, const |
| cpu_set_t *CPUSET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function installs the CPUSETSIZE bytes long affinity mask |
| pointed to by CPUSET for the process or thread with the ID PID. If |
| successful the function returns zero and the scheduler will in |
| future take the affinity information into account. |
| |
| If the function fails it will return '-1' and 'errno' is set to the |
| error code: |
| |
| 'ESRCH' |
| No process or thread with the given ID found. |
| |
| 'EFAULT' |
| The pointer CPUSET is does not point to a valid object. |
| |
| 'EINVAL' |
| The bitset is not valid. This might mean that the affinity |
| set might not leave a processor for the process or thread to |
| run on. |
| |
| This function is a GNU extension and is declared in 'sched.h'. |
| |
| |
| File: libc.info, Node: Memory Resources, Next: Processor Resources, Prev: Priority, Up: Resource Usage And Limitation |
| |
| 22.4 Querying memory available resources |
| ======================================== |
| |
| The amount of memory available in the system and the way it is organized |
| determines oftentimes the way programs can and have to work. For |
| functions like 'mmap' it is necessary to know about the size of |
| individual memory pages and knowing how much memory is available enables |
| a program to select appropriate sizes for, say, caches. Before we get |
| into these details a few words about memory subsystems in traditional |
| Unix systems will be given. |
| |
| * Menu: |
| |
| * Memory Subsystem:: Overview about traditional Unix memory handling. |
| * Query Memory Parameters:: How to get information about the memory |
| subsystem? |
| |
| |
| File: libc.info, Node: Memory Subsystem, Next: Query Memory Parameters, Up: Memory Resources |
| |
| 22.4.1 Overview about traditional Unix memory handling |
| ------------------------------------------------------ |
| |
| Unix systems normally provide processes virtual address spaces. This |
| means that the addresses of the memory regions do not have to correspond |
| directly to the addresses of the actual physical memory which stores the |
| data. An extra level of indirection is introduced which translates |
| virtual addresses into physical addresses. This is normally done by the |
| hardware of the processor. |
| |
| Using a virtual address space has several advantage. The most |
| important is process isolation. The different processes running on the |
| system cannot interfere directly with each other. No process can write |
| into the address space of another process (except when shared memory is |
| used but then it is wanted and controlled). |
| |
| Another advantage of virtual memory is that the address space the |
| processes see can actually be larger than the physical memory available. |
| The physical memory can be extended by storage on an external media |
| where the content of currently unused memory regions is stored. The |
| address translation can then intercept accesses to these memory regions |
| and make memory content available again by loading the data back into |
| memory. This concept makes it necessary that programs which have to use |
| lots of memory know the difference between available virtual address |
| space and available physical memory. If the working set of virtual |
| memory of all the processes is larger than the available physical memory |
| the system will slow down dramatically due to constant swapping of |
| memory content from the memory to the storage media and back. This is |
| called "thrashing". |
| |
| A final aspect of virtual memory which is important and follows from |
| what is said in the last paragraph is the granularity of the virtual |
| address space handling. When we said that the virtual address handling |
| stores memory content externally it cannot do this on a byte-by-byte |
| basis. The administrative overhead does not allow this (leaving alone |
| the processor hardware). Instead several thousand bytes are handled |
| together and form a "page". The size of each page is always a power of |
| two byte. The smallest page size in use today is 4096, with 8192, |
| 16384, and 65536 being other popular sizes. |
| |
| |
| File: libc.info, Node: Query Memory Parameters, Prev: Memory Subsystem, Up: Memory Resources |
| |
| 22.4.2 How to get information about the memory subsystem? |
| --------------------------------------------------------- |
| |
| The page size of the virtual memory the process sees is essential to |
| know in several situations. Some programming interface (e.g., 'mmap', |
| *note Memory-mapped I/O::) require the user to provide information |
| adjusted to the page size. In the case of 'mmap' is it necessary to |
| provide a length argument which is a multiple of the page size. Another |
| place where the knowledge about the page size is useful is in memory |
| allocation. If one allocates pieces of memory in larger chunks which |
| are then subdivided by the application code it is useful to adjust the |
| size of the larger blocks to the page size. If the total memory |
| requirement for the block is close (but not larger) to a multiple of the |
| page size the kernel's memory handling can work more effectively since |
| it only has to allocate memory pages which are fully used. (To do this |
| optimization it is necessary to know a bit about the memory allocator |
| which will require a bit of memory itself for each block and this |
| overhead must not push the total size over the page size multiple. |
| |
| The page size traditionally was a compile time constant. But recent |
| development of processors changed this. Processors now support |
| different page sizes and they can possibly even vary among different |
| processes on the same system. Therefore the system should be queried at |
| runtime about the current page size and no assumptions (except about it |
| being a power of two) should be made. |
| |
| The correct interface to query about the page size is 'sysconf' |
| (*note Sysconf Definition::) with the parameter '_SC_PAGESIZE'. There |
| is a much older interface available, too. |
| |
| -- Function: int getpagesize (void) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'getpagesize' function returns the page size of the process. |
| This value is fixed for the runtime of the process but can vary in |
| different runs of the application. |
| |
| The function is declared in 'unistd.h'. |
| |
| Widely available on System V derived systems is a method to get |
| information about the physical memory the system has. The call |
| |
| sysconf (_SC_PHYS_PAGES) |
| |
| returns the total number of pages of physical the system has. This does |
| not mean all this memory is available. This information can be found |
| using |
| |
| sysconf (_SC_AVPHYS_PAGES) |
| |
| These two values help to optimize applications. The value returned |
| for '_SC_AVPHYS_PAGES' is the amount of memory the application can use |
| without hindering any other process (given that no other process |
| increases its memory usage). The value returned for '_SC_PHYS_PAGES' is |
| more or less a hard limit for the working set. If all applications |
| together constantly use more than that amount of memory the system is in |
| trouble. |
| |
| The GNU C Library provides in addition to these already described way |
| to get this information two functions. They are declared in the file |
| 'sys/sysinfo.h'. Programmers should prefer to use the 'sysconf' method |
| described above. |
| |
| -- Function: long int get_phys_pages (void) |
| Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock fd |
| mem | *Note POSIX Safety Concepts::. |
| |
| The 'get_phys_pages' function returns the total number of pages of |
| physical the system has. To get the amount of memory this number |
| has to be multiplied by the page size. |
| |
| This function is a GNU extension. |
| |
| -- Function: long int get_avphys_pages (void) |
| Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock fd |
| mem | *Note POSIX Safety Concepts::. |
| |
| The 'get_phys_pages' function returns the number of available pages |
| of physical the system has. To get the amount of memory this |
| number has to be multiplied by the page size. |
| |
| This function is a GNU extension. |
| |
| |
| File: libc.info, Node: Processor Resources, Prev: Memory Resources, Up: Resource Usage And Limitation |
| |
| 22.5 Learn about the processors available |
| ========================================= |
| |
| The use of threads or processes with shared memory allows an application |
| to take advantage of all the processing power a system can provide. If |
| the task can be parallelized the optimal way to write an application is |
| to have at any time as many processes running as there are processors. |
| To determine the number of processors available to the system one can |
| run |
| |
| sysconf (_SC_NPROCESSORS_CONF) |
| |
| which returns the number of processors the operating system configured. |
| But it might be possible for the operating system to disable individual |
| processors and so the call |
| |
| sysconf (_SC_NPROCESSORS_ONLN) |
| |
| returns the number of processors which are currently online (i.e., |
| available). |
| |
| For these two pieces of information the GNU C Library also provides |
| functions to get the information directly. The functions are declared |
| in 'sys/sysinfo.h'. |
| |
| -- Function: int get_nprocs_conf (void) |
| Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock fd |
| mem | *Note POSIX Safety Concepts::. |
| |
| The 'get_nprocs_conf' function returns the number of processors the |
| operating system configured. |
| |
| This function is a GNU extension. |
| |
| -- Function: int get_nprocs (void) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety |
| Concepts::. |
| |
| The 'get_nprocs' function returns the number of available |
| processors. |
| |
| This function is a GNU extension. |
| |
| Before starting more threads it should be checked whether the |
| processors are not already overused. Unix systems calculate something |
| called the "load average". This is a number indicating how many |
| processes were running. This number is average over different periods |
| of times (normally 1, 5, and 15 minutes). |
| |
| -- Function: int getloadavg (double LOADAVG[], int NELEM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety |
| Concepts::. |
| |
| This function gets the 1, 5 and 15 minute load averages of the |
| system. The values are placed in LOADAVG. 'getloadavg' will place |
| at most NELEM elements into the array but never more than three |
| elements. The return value is the number of elements written to |
| LOADAVG, or -1 on error. |
| |
| This function is declared in 'stdlib.h'. |
| |
| |
| File: libc.info, Node: Non-Local Exits, Next: Signal Handling, Prev: Resource Usage And Limitation, Up: Top |
| |
| 23 Non-Local Exits |
| ****************** |
| |
| Sometimes when your program detects an unusual situation inside a deeply |
| nested set of function calls, you would like to be able to immediately |
| return to an outer level of control. This section describes how you can |
| do such "non-local exits" using the 'setjmp' and 'longjmp' functions. |
| |
| * Menu: |
| |
| * Intro: Non-Local Intro. When and how to use these facilities. |
| * Details: Non-Local Details. Functions for non-local exits. |
| * Non-Local Exits and Signals:: Portability issues. |
| * System V contexts:: Complete context control a la System V. |
| |
| |
| File: libc.info, Node: Non-Local Intro, Next: Non-Local Details, Up: Non-Local Exits |
| |
| 23.1 Introduction to Non-Local Exits |
| ==================================== |
| |
| As an example of a situation where a non-local exit can be useful, |
| suppose you have an interactive program that has a "main loop" that |
| prompts for and executes commands. Suppose the "read" command reads |
| input from a file, doing some lexical analysis and parsing of the input |
| while processing it. If a low-level input error is detected, it would |
| be useful to be able to return immediately to the "main loop" instead of |
| having to make each of the lexical analysis, parsing, and processing |
| phases all have to explicitly deal with error situations initially |
| detected by nested calls. |
| |
| (On the other hand, if each of these phases has to do a substantial |
| amount of cleanup when it exits--such as closing files, deallocating |
| buffers or other data structures, and the like--then it can be more |
| appropriate to do a normal return and have each phase do its own |
| cleanup, because a non-local exit would bypass the intervening phases |
| and their associated cleanup code entirely. Alternatively, you could |
| use a non-local exit but do the cleanup explicitly either before or |
| after returning to the "main loop".) |
| |
| In some ways, a non-local exit is similar to using the 'return' |
| statement to return from a function. But while 'return' abandons only a |
| single function call, transferring control back to the point at which it |
| was called, a non-local exit can potentially abandon many levels of |
| nested function calls. |
| |
| You identify return points for non-local exits by calling the |
| function 'setjmp'. This function saves information about the execution |
| environment in which the call to 'setjmp' appears in an object of type |
| 'jmp_buf'. Execution of the program continues normally after the call |
| to 'setjmp', but if an exit is later made to this return point by |
| calling 'longjmp' with the corresponding 'jmp_buf' object, control is |
| transferred back to the point where 'setjmp' was called. The return |
| value from 'setjmp' is used to distinguish between an ordinary return |
| and a return made by a call to 'longjmp', so calls to 'setjmp' usually |
| appear in an 'if' statement. |
| |
| Here is how the example program described above might be set up: |
| |
| |
| #include <setjmp.h> |
| #include <stdlib.h> |
| #include <stdio.h> |
| |
| jmp_buf main_loop; |
| |
| void |
| abort_to_main_loop (int status) |
| { |
| longjmp (main_loop, status); |
| } |
| |
| int |
| main (void) |
| { |
| while (1) |
| if (setjmp (main_loop)) |
| puts ("Back at main loop...."); |
| else |
| do_command (); |
| } |
| |
| |
| void |
| do_command (void) |
| { |
| char buffer[128]; |
| if (fgets (buffer, 128, stdin) == NULL) |
| abort_to_main_loop (-1); |
| else |
| exit (EXIT_SUCCESS); |
| } |
| |
| The function 'abort_to_main_loop' causes an immediate transfer of |
| control back to the main loop of the program, no matter where it is |
| called from. |
| |
| The flow of control inside the 'main' function may appear a little |
| mysterious at first, but it is actually a common idiom with 'setjmp'. A |
| normal call to 'setjmp' returns zero, so the "else" clause of the |
| conditional is executed. If 'abort_to_main_loop' is called somewhere |
| within the execution of 'do_command', then it actually appears as if the |
| _same_ call to 'setjmp' in 'main' were returning a second time with a |
| value of '-1'. |
| |
| So, the general pattern for using 'setjmp' looks something like: |
| |
| if (setjmp (BUFFER)) |
| /* Code to clean up after premature return. */ |
| ... |
| else |
| /* Code to be executed normally after setting up the return point. */ |
| ... |
| |
| |
| File: libc.info, Node: Non-Local Details, Next: Non-Local Exits and Signals, Prev: Non-Local Intro, Up: Non-Local Exits |
| |
| 23.2 Details of Non-Local Exits |
| =============================== |
| |
| Here are the details on the functions and data structures used for |
| performing non-local exits. These facilities are declared in |
| 'setjmp.h'. |
| |
| -- Data Type: jmp_buf |
| Objects of type 'jmp_buf' hold the state information to be restored |
| by a non-local exit. The contents of a 'jmp_buf' identify a |
| specific place to return to. |
| |
| -- Macro: int setjmp (jmp_buf STATE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| When called normally, 'setjmp' stores information about the |
| execution state of the program in STATE and returns zero. If |
| 'longjmp' is later used to perform a non-local exit to this STATE, |
| 'setjmp' returns a nonzero value. |
| |
| -- Function: void longjmp (jmp_buf STATE, int VALUE) |
| Preliminary: | MT-Safe | AS-Unsafe plugin corrupt lock/hurd | |
| AC-Unsafe corrupt lock/hurd | *Note POSIX Safety Concepts::. |
| |
| This function restores current execution to the state saved in |
| STATE, and continues execution from the call to 'setjmp' that |
| established that return point. Returning from 'setjmp' by means of |
| 'longjmp' returns the VALUE argument that was passed to 'longjmp', |
| rather than '0'. (But if VALUE is given as '0', 'setjmp' returns |
| '1'). |
| |
| There are a lot of obscure but important restrictions on the use of |
| 'setjmp' and 'longjmp'. Most of these restrictions are present because |
| non-local exits require a fair amount of magic on the part of the C |
| compiler and can interact with other parts of the language in strange |
| ways. |
| |
| The 'setjmp' function is actually a macro without an actual function |
| definition, so you shouldn't try to '#undef' it or take its address. In |
| addition, calls to 'setjmp' are safe in only the following contexts: |
| |
| * As the test expression of a selection or iteration statement (such |
| as 'if', 'switch', or 'while'). |
| |
| * As one operand of an equality or comparison operator that appears |
| as the test expression of a selection or iteration statement. The |
| other operand must be an integer constant expression. |
| |
| * As the operand of a unary '!' operator, that appears as the test |
| expression of a selection or iteration statement. |
| |
| * By itself as an expression statement. |
| |
| Return points are valid only during the dynamic extent of the |
| function that called 'setjmp' to establish them. If you 'longjmp' to a |
| return point that was established in a function that has already |
| returned, unpredictable and disastrous things are likely to happen. |
| |
| You should use a nonzero VALUE argument to 'longjmp'. While |
| 'longjmp' refuses to pass back a zero argument as the return value from |
| 'setjmp', this is intended as a safety net against accidental misuse and |
| is not really good programming style. |
| |
| When you perform a non-local exit, accessible objects generally |
| retain whatever values they had at the time 'longjmp' was called. The |
| exception is that the values of automatic variables local to the |
| function containing the 'setjmp' call that have been changed since the |
| call to 'setjmp' are indeterminate, unless you have declared them |
| 'volatile'. |
| |
| |
| File: libc.info, Node: Non-Local Exits and Signals, Next: System V contexts, Prev: Non-Local Details, Up: Non-Local Exits |
| |
| 23.3 Non-Local Exits and Signals |
| ================================ |
| |
| In BSD Unix systems, 'setjmp' and 'longjmp' also save and restore the |
| set of blocked signals; see *note Blocking Signals::. However, the |
| POSIX.1 standard requires 'setjmp' and 'longjmp' not to change the set |
| of blocked signals, and provides an additional pair of functions |
| ('sigsetjmp' and 'siglongjmp') to get the BSD behavior. |
| |
| The behavior of 'setjmp' and 'longjmp' in the GNU C Library is |
| controlled by feature test macros; see *note Feature Test Macros::. The |
| default in the GNU C Library is the POSIX.1 behavior rather than the BSD |
| behavior. |
| |
| The facilities in this section are declared in the header file |
| 'setjmp.h'. |
| |
| -- Data Type: sigjmp_buf |
| This is similar to 'jmp_buf', except that it can also store state |
| information about the set of blocked signals. |
| |
| -- Function: int sigsetjmp (sigjmp_buf STATE, int SAVESIGS) |
| Preliminary: | MT-Safe | AS-Unsafe lock/hurd | AC-Unsafe lock/hurd |
| | *Note POSIX Safety Concepts::. |
| |
| This is similar to 'setjmp'. If SAVESIGS is nonzero, the set of |
| blocked signals is saved in STATE and will be restored if a |
| 'siglongjmp' is later performed with this STATE. |
| |
| -- Function: void siglongjmp (sigjmp_buf STATE, int VALUE) |
| Preliminary: | MT-Safe | AS-Unsafe plugin corrupt lock/hurd | |
| AC-Unsafe corrupt lock/hurd | *Note POSIX Safety Concepts::. |
| |
| This is similar to 'longjmp' except for the type of its STATE |
| argument. If the 'sigsetjmp' call that set this STATE used a |
| nonzero SAVESIGS flag, 'siglongjmp' also restores the set of |
| blocked signals. |
| |
| |
| File: libc.info, Node: System V contexts, Prev: Non-Local Exits and Signals, Up: Non-Local Exits |
| |
| 23.4 Complete Context Control |
| ============================= |
| |
| The Unix standard provides one more set of functions to control the |
| execution path and these functions are more powerful than those |
| discussed in this chapter so far. These function were part of the |
| original System V API and by this route were added to the Unix API. |
| Beside on branded Unix implementations these interfaces are not widely |
| available. Not all platforms and/or architectures the GNU C Library is |
| available on provide this interface. Use 'configure' to detect the |
| availability. |
| |
| Similar to the 'jmp_buf' and 'sigjmp_buf' types used for the |
| variables to contain the state of the 'longjmp' functions the interfaces |
| of interest here have an appropriate type as well. Objects of this type |
| are normally much larger since more information is contained. The type |
| is also used in a few more places as we will see. The types and |
| functions described in this section are all defined and declared |
| respectively in the 'ucontext.h' header file. |
| |
| -- Data Type: ucontext_t |
| |
| The 'ucontext_t' type is defined as a structure with as least the |
| following elements: |
| |
| 'ucontext_t *uc_link' |
| This is a pointer to the next context structure which is used |
| if the context described in the current structure returns. |
| |
| 'sigset_t uc_sigmask' |
| Set of signals which are blocked when this context is used. |
| |
| 'stack_t uc_stack' |
| Stack used for this context. The value need not be (and |
| normally is not) the stack pointer. *Note Signal Stack::. |
| |
| 'mcontext_t uc_mcontext' |
| This element contains the actual state of the process. The |
| 'mcontext_t' type is also defined in this header but the |
| definition should be treated as opaque. Any use of knowledge |
| of the type makes applications less portable. |
| |
| Objects of this type have to be created by the user. The |
| initialization and modification happens through one of the following |
| functions: |
| |
| -- Function: int getcontext (ucontext_t *UCP) |
| Preliminary: | MT-Safe race:ucp | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The 'getcontext' function initializes the variable pointed to by |
| UCP with the context of the calling thread. The context contains |
| the content of the registers, the signal mask, and the current |
| stack. Executing the contents would start at the point where the |
| 'getcontext' call just returned. |
| |
| The function returns '0' if successful. Otherwise it returns '-1' |
| and sets ERRNO accordingly. |
| |
| The 'getcontext' function is similar to 'setjmp' but it does not |
| provide an indication of whether the function returns for the first time |
| or whether the initialized context was used and the execution is resumed |
| at just that point. If this is necessary the user has to take determine |
| this herself. This must be done carefully since the context contains |
| registers which might contain register variables. This is a good |
| situation to define variables with 'volatile'. |
| |
| Once the context variable is initialized it can be used as is or it |
| can be modified. The latter is normally done to implement co-routines |
| or similar constructs. The 'makecontext' function is what has to be |
| used to do that. |
| |
| -- Function: void makecontext (ucontext_t *UCP, void (*FUNC) (void), |
| int ARGC, ...) |
| Preliminary: | MT-Safe race:ucp | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The UCP parameter passed to the 'makecontext' shall be initialized |
| by a call to 'getcontext'. The context will be modified to in a |
| way so that if the context is resumed it will start by calling the |
| function 'func' which gets ARGC integer arguments passed. The |
| integer arguments which are to be passed should follow the ARGC |
| parameter in the call to 'makecontext'. |
| |
| Before the call to this function the 'uc_stack' and 'uc_link' |
| element of the UCP structure should be initialized. The 'uc_stack' |
| element describes the stack which is used for this context. No two |
| contexts which are used at the same time should use the same memory |
| region for a stack. |
| |
| The 'uc_link' element of the object pointed to by UCP should be a |
| pointer to the context to be executed when the function FUNC |
| returns or it should be a null pointer. See 'setcontext' for more |
| information about the exact use. |
| |
| While allocating the memory for the stack one has to be careful. |
| Most modern processors keep track of whether a certain memory region is |
| allowed to contain code which is executed or not. Data segments and |
| heap memory is normally not tagged to allow this. The result is that |
| programs would fail. Examples for such code include the calling |
| sequences the GNU C compiler generates for calls to nested functions. |
| Safe ways to allocate stacks correctly include using memory on the |
| original threads stack or explicitly allocate memory tagged for |
| execution using (*note Memory-mapped I/O::). |
| |
| *Compatibility note*: The current Unix standard is very imprecise |
| about the way the stack is allocated. All implementations seem to agree |
| that the 'uc_stack' element must be used but the values stored in the |
| elements of the 'stack_t' value are unclear. The GNU C Library and most |
| other Unix implementations require the 'ss_sp' value of the 'uc_stack' |
| element to point to the base of the memory region allocated for the |
| stack and the size of the memory region is stored in 'ss_size'. There |
| are implements out there which require 'ss_sp' to be set to the value |
| the stack pointer will have (which can depending on the direction the |
| stack grows be different). This difference makes the 'makecontext' |
| function hard to use and it requires detection of the platform at |
| compile time. |
| |
| -- Function: int setcontext (const ucontext_t *UCP) |
| Preliminary: | MT-Safe race:ucp | AS-Unsafe corrupt | AC-Unsafe |
| corrupt | *Note POSIX Safety Concepts::. |
| |
| The 'setcontext' function restores the context described by UCP. |
| The context is not modified and can be reused as often as wanted. |
| |
| If the context was created by 'getcontext' execution resumes with |
| the registers filled with the same values and the same stack as if |
| the 'getcontext' call just returned. |
| |
| If the context was modified with a call to 'makecontext' execution |
| continues with the function passed to 'makecontext' which gets the |
| specified parameters passed. If this function returns execution is |
| resumed in the context which was referenced by the 'uc_link' |
| element of the context structure passed to 'makecontext' at the |
| time of the call. If 'uc_link' was a null pointer the application |
| terminates normally with an exit status value of 'EXIT_SUCCESS' |
| (*note Program Termination::). |
| |
| Since the context contains information about the stack no two |
| threads should use the same context at the same time. The result |
| in most cases would be disastrous. |
| |
| The 'setcontext' function does not return unless an error occurred |
| in which case it returns '-1'. |
| |
| The 'setcontext' function simply replaces the current context with |
| the one described by the UCP parameter. This is often useful but there |
| are situations where the current context has to be preserved. |
| |
| -- Function: int swapcontext (ucontext_t *restrict OUCP, const |
| ucontext_t *restrict UCP) |
| Preliminary: | MT-Safe race:oucp race:ucp | AS-Unsafe corrupt | |
| AC-Unsafe corrupt | *Note POSIX Safety Concepts::. |
| |
| The 'swapcontext' function is similar to 'setcontext' but instead |
| of just replacing the current context the latter is first saved in |
| the object pointed to by OUCP as if this was a call to |
| 'getcontext'. The saved context would resume after the call to |
| 'swapcontext'. |
| |
| Once the current context is saved the context described in UCP is |
| installed and execution continues as described in this context. |
| |
| If 'swapcontext' succeeds the function does not return unless the |
| context OUCP is used without prior modification by 'makecontext'. |
| The return value in this case is '0'. If the function fails it |
| returns '-1' and set ERRNO accordingly. |
| |
| Example for SVID Context Handling |
| ================================= |
| |
| The easiest way to use the context handling functions is as a |
| replacement for 'setjmp' and 'longjmp'. The context contains on most |
| platforms more information which might lead to less surprises but this |
| also means using these functions is more expensive (beside being less |
| portable). |
| |
| int |
| random_search (int n, int (*fp) (int, ucontext_t *)) |
| { |
| volatile int cnt = 0; |
| ucontext_t uc; |
| |
| /* Safe current context. */ |
| if (getcontext (&uc) < 0) |
| return -1; |
| |
| /* If we have not tried N times try again. */ |
| if (cnt++ < n) |
| /* Call the function with a new random number |
| and the context. */ |
| if (fp (rand (), &uc) != 0) |
| /* We found what we were looking for. */ |
| return 1; |
| |
| /* Not found. */ |
| return 0; |
| } |
| |
| Using contexts in such a way enables emulating exception handling. |
| The search functions passed in the FP parameter could be very large, |
| nested, and complex which would make it complicated (or at least would |
| require a lot of code) to leave the function with an error value which |
| has to be passed down to the caller. By using the context it is |
| possible to leave the search function in one step and allow restarting |
| the search which also has the nice side effect that it can be |
| significantly faster. |
| |
| Something which is harder to implement with 'setjmp' and 'longjmp' is |
| to switch temporarily to a different execution path and then resume |
| where execution was stopped. |
| |
| |
| #include <signal.h> |
| #include <stdio.h> |
| #include <stdlib.h> |
| #include <ucontext.h> |
| #include <sys/time.h> |
| |
| /* Set by the signal handler. */ |
| static volatile int expired; |
| |
| /* The contexts. */ |
| static ucontext_t uc[3]; |
| |
| /* We do only a certain number of switches. */ |
| static int switches; |
| |
| |
| /* This is the function doing the work. It is just a |
| skeleton, real code has to be filled in. */ |
| static void |
| f (int n) |
| { |
| int m = 0; |
| while (1) |
| { |
| /* This is where the work would be done. */ |
| if (++m % 100 == 0) |
| { |
| putchar ('.'); |
| fflush (stdout); |
| } |
| |
| /* Regularly the EXPIRE variable must be checked. */ |
| if (expired) |
| { |
| /* We do not want the program to run forever. */ |
| if (++switches == 20) |
| return; |
| |
| printf ("\nswitching from %d to %d\n", n, 3 - n); |
| expired = 0; |
| /* Switch to the other context, saving the current one. */ |
| swapcontext (&uc[n], &uc[3 - n]); |
| } |
| } |
| } |
| |
| /* This is the signal handler which simply set the variable. */ |
| void |
| handler (int signal) |
| { |
| expired = 1; |
| } |
| |
| |
| int |
| main (void) |
| { |
| struct sigaction sa; |
| struct itimerval it; |
| char st1[8192]; |
| char st2[8192]; |
| |
| /* Initialize the data structures for the interval timer. */ |
| sa.sa_flags = SA_RESTART; |
| sigfillset (&sa.sa_mask); |
| sa.sa_handler = handler; |
| it.it_interval.tv_sec = 0; |
| it.it_interval.tv_usec = 1; |
| it.it_value = it.it_interval; |
| |
| /* Install the timer and get the context we can manipulate. */ |
| if (sigaction (SIGPROF, &sa, NULL) < 0 |
| || setitimer (ITIMER_PROF, &it, NULL) < 0 |
| || getcontext (&uc[1]) == -1 |
| || getcontext (&uc[2]) == -1) |
| abort (); |
| |
| /* Create a context with a separate stack which causes the |
| function 'f' to be call with the parameter '1'. |
| Note that the 'uc_link' points to the main context |
| which will cause the program to terminate once the function |
| return. */ |
| uc[1].uc_link = &uc[0]; |
| uc[1].uc_stack.ss_sp = st1; |
| uc[1].uc_stack.ss_size = sizeof st1; |
| makecontext (&uc[1], (void (*) (void)) f, 1, 1); |
| |
| /* Similarly, but '2' is passed as the parameter to 'f'. */ |
| uc[2].uc_link = &uc[0]; |
| uc[2].uc_stack.ss_sp = st2; |
| uc[2].uc_stack.ss_size = sizeof st2; |
| makecontext (&uc[2], (void (*) (void)) f, 1, 2); |
| |
| /* Start running. */ |
| swapcontext (&uc[0], &uc[1]); |
| putchar ('\n'); |
| |
| return 0; |
| } |
| |
| This an example how the context functions can be used to implement |
| co-routines or cooperative multi-threading. All that has to be done is |
| to call every once in a while 'swapcontext' to continue running a |
| different context. It is not allowed to do the context switching from |
| the signal handler directly since neither 'setcontext' nor 'swapcontext' |
| are functions which can be called from a signal handler. But setting a |
| variable in the signal handler and checking it in the body of the |
| functions which are executed. Since 'swapcontext' is saving the current |
| context it is possible to have multiple different scheduling points in |
| the code. Execution will always resume where it was left. |
| |
| |
| File: libc.info, Node: Signal Handling, Next: Program Basics, Prev: Non-Local Exits, Up: Top |
| |
| 24 Signal Handling |
| ****************** |
| |
| A "signal" is a software interrupt delivered to a process. The |
| operating system uses signals to report exceptional situations to an |
| executing program. Some signals report errors such as references to |
| invalid memory addresses; others report asynchronous events, such as |
| disconnection of a phone line. |
| |
| The GNU C Library defines a variety of signal types, each for a |
| particular kind of event. Some kinds of events make it inadvisable or |
| impossible for the program to proceed as usual, and the corresponding |
| signals normally abort the program. Other kinds of signals that report |
| harmless events are ignored by default. |
| |
| If you anticipate an event that causes signals, you can define a |
| handler function and tell the operating system to run it when that |
| particular type of signal arrives. |
| |
| Finally, one process can send a signal to another process; this |
| allows a parent process to abort a child, or two related processes to |
| communicate and synchronize. |
| |
| * Menu: |
| |
| * Concepts of Signals:: Introduction to the signal facilities. |
| * Standard Signals:: Particular kinds of signals with |
| standard names and meanings. |
| * Signal Actions:: Specifying what happens when a |
| particular signal is delivered. |
| * Defining Handlers:: How to write a signal handler function. |
| * Interrupted Primitives:: Signal handlers affect use of 'open', |
| 'read', 'write' and other functions. |
| * Generating Signals:: How to send a signal to a process. |
| * Blocking Signals:: Making the system hold signals temporarily. |
| * Waiting for a Signal:: Suspending your program until a signal |
| arrives. |
| * Signal Stack:: Using a Separate Signal Stack. |
| * BSD Signal Handling:: Additional functions for backward |
| compatibility with BSD. |
| |
| |
| File: libc.info, Node: Concepts of Signals, Next: Standard Signals, Up: Signal Handling |
| |
| 24.1 Basic Concepts of Signals |
| ============================== |
| |
| This section explains basic concepts of how signals are generated, what |
| happens after a signal is delivered, and how programs can handle |
| signals. |
| |
| * Menu: |
| |
| * Kinds of Signals:: Some examples of what can cause a signal. |
| * Signal Generation:: Concepts of why and how signals occur. |
| * Delivery of Signal:: Concepts of what a signal does to the |
| process. |
| |
| |
| File: libc.info, Node: Kinds of Signals, Next: Signal Generation, Up: Concepts of Signals |
| |
| 24.1.1 Some Kinds of Signals |
| ---------------------------- |
| |
| A signal reports the occurrence of an exceptional event. These are some |
| of the events that can cause (or "generate", or "raise") a signal: |
| |
| * A program error such as dividing by zero or issuing an address |
| outside the valid range. |
| |
| * A user request to interrupt or terminate the program. Most |
| environments are set up to let a user suspend the program by typing |
| 'C-z', or terminate it with 'C-c'. Whatever key sequence is used, |
| the operating system sends the proper signal to interrupt the |
| process. |
| |
| * The termination of a child process. |
| |
| * Expiration of a timer or alarm. |
| |
| * A call to 'kill' or 'raise' by the same process. |
| |
| * A call to 'kill' from another process. Signals are a limited but |
| useful form of interprocess communication. |
| |
| * An attempt to perform an I/O operation that cannot be done. |
| Examples are reading from a pipe that has no writer (*note Pipes |
| and FIFOs::), and reading or writing to a terminal in certain |
| situations (*note Job Control::). |
| |
| Each of these kinds of events (excepting explicit calls to 'kill' and |
| 'raise') generates its own particular kind of signal. The various kinds |
| of signals are listed and described in detail in *note Standard |
| Signals::. |
| |
| |
| File: libc.info, Node: Signal Generation, Next: Delivery of Signal, Prev: Kinds of Signals, Up: Concepts of Signals |
| |
| 24.1.2 Concepts of Signal Generation |
| ------------------------------------ |
| |
| In general, the events that generate signals fall into three major |
| categories: errors, external events, and explicit requests. |
| |
| An error means that a program has done something invalid and cannot |
| continue execution. But not all kinds of errors generate signals--in |
| fact, most do not. For example, opening a nonexistent file is an error, |
| but it does not raise a signal; instead, 'open' returns '-1'. In |
| general, errors that are necessarily associated with certain library |
| functions are reported by returning a value that indicates an error. |
| The errors which raise signals are those which can happen anywhere in |
| the program, not just in library calls. These include division by zero |
| and invalid memory addresses. |
| |
| An external event generally has to do with I/O or other processes. |
| These include the arrival of input, the expiration of a timer, and the |
| termination of a child process. |
| |
| An explicit request means the use of a library function such as |
| 'kill' whose purpose is specifically to generate a signal. |
| |
| Signals may be generated "synchronously" or "asynchronously". A |
| synchronous signal pertains to a specific action in the program, and is |
| delivered (unless blocked) during that action. Most errors generate |
| signals synchronously, and so do explicit requests by a process to |
| generate a signal for that same process. On some machines, certain |
| kinds of hardware errors (usually floating-point exceptions) are not |
| reported completely synchronously, but may arrive a few instructions |
| later. |
| |
| Asynchronous signals are generated by events outside the control of |
| the process that receives them. These signals arrive at unpredictable |
| times during execution. External events generate signals |
| asynchronously, and so do explicit requests that apply to some other |
| process. |
| |
| A given type of signal is either typically synchronous or typically |
| asynchronous. For example, signals for errors are typically synchronous |
| because errors generate signals synchronously. But any type of signal |
| can be generated synchronously or asynchronously with an explicit |
| request. |
| |
| |
| File: libc.info, Node: Delivery of Signal, Prev: Signal Generation, Up: Concepts of Signals |
| |
| 24.1.3 How Signals Are Delivered |
| -------------------------------- |
| |
| When a signal is generated, it becomes "pending". Normally it remains |
| pending for just a short period of time and then is "delivered" to the |
| process that was signaled. However, if that kind of signal is currently |
| "blocked", it may remain pending indefinitely--until signals of that |
| kind are "unblocked". Once unblocked, it will be delivered immediately. |
| *Note Blocking Signals::. |
| |
| When the signal is delivered, whether right away or after a long |
| delay, the "specified action" for that signal is taken. For certain |
| signals, such as 'SIGKILL' and 'SIGSTOP', the action is fixed, but for |
| most signals, the program has a choice: ignore the signal, specify a |
| "handler function", or accept the "default action" for that kind of |
| signal. The program specifies its choice using functions such as |
| 'signal' or 'sigaction' (*note Signal Actions::). We sometimes say that |
| a handler "catches" the signal. While the handler is running, that |
| particular signal is normally blocked. |
| |
| If the specified action for a kind of signal is to ignore it, then |
| any such signal which is generated is discarded immediately. This |
| happens even if the signal is also blocked at the time. A signal |
| discarded in this way will never be delivered, not even if the program |
| subsequently specifies a different action for that kind of signal and |
| then unblocks it. |
| |
| If a signal arrives which the program has neither handled nor |
| ignored, its "default action" takes place. Each kind of signal has its |
| own default action, documented below (*note Standard Signals::). For |
| most kinds of signals, the default action is to terminate the process. |
| For certain kinds of signals that represent "harmless" events, the |
| default action is to do nothing. |
| |
| When a signal terminates a process, its parent process can determine |
| the cause of termination by examining the termination status code |
| reported by the 'wait' or 'waitpid' functions. (This is discussed in |
| more detail in *note Process Completion::.) The information it can get |
| includes the fact that termination was due to a signal and the kind of |
| signal involved. If a program you run from a shell is terminated by a |
| signal, the shell typically prints some kind of error message. |
| |
| The signals that normally represent program errors have a special |
| property: when one of these signals terminates the process, it also |
| writes a "core dump file" which records the state of the process at the |
| time of termination. You can examine the core dump with a debugger to |
| investigate what caused the error. |
| |
| If you raise a "program error" signal by explicit request, and this |
| terminates the process, it makes a core dump file just as if the signal |
| had been due directly to an error. |
| |
| |
| File: libc.info, Node: Standard Signals, Next: Signal Actions, Prev: Concepts of Signals, Up: Signal Handling |
| |
| 24.2 Standard Signals |
| ===================== |
| |
| This section lists the names for various standard kinds of signals and |
| describes what kind of event they mean. Each signal name is a macro |
| which stands for a positive integer--the "signal number" for that kind |
| of signal. Your programs should never make assumptions about the |
| numeric code for a particular kind of signal, but rather refer to them |
| always by the names defined here. This is because the number for a |
| given kind of signal can vary from system to system, but the meanings of |
| the names are standardized and fairly uniform. |
| |
| The signal names are defined in the header file 'signal.h'. |
| |
| -- Macro: int NSIG |
| The value of this symbolic constant is the total number of signals |
| defined. Since the signal numbers are allocated consecutively, |
| 'NSIG' is also one greater than the largest defined signal number. |
| |
| * Menu: |
| |
| * Program Error Signals:: Used to report serious program errors. |
| * Termination Signals:: Used to interrupt and/or terminate the |
| program. |
| * Alarm Signals:: Used to indicate expiration of timers. |
| * Asynchronous I/O Signals:: Used to indicate input is available. |
| * Job Control Signals:: Signals used to support job control. |
| * Operation Error Signals:: Used to report operational system errors. |
| * Miscellaneous Signals:: Miscellaneous Signals. |
| * Signal Messages:: Printing a message describing a signal. |
| |
| |
| File: libc.info, Node: Program Error Signals, Next: Termination Signals, Up: Standard Signals |
| |
| 24.2.1 Program Error Signals |
| ---------------------------- |
| |
| The following signals are generated when a serious program error is |
| detected by the operating system or the computer itself. In general, |
| all of these signals are indications that your program is seriously |
| broken in some way, and there's usually no way to continue the |
| computation which encountered the error. |
| |
| Some programs handle program error signals in order to tidy up before |
| terminating; for example, programs that turn off echoing of terminal |
| input should handle program error signals in order to turn echoing back |
| on. The handler should end by specifying the default action for the |
| signal that happened and then reraising it; this will cause the program |
| to terminate with that signal, as if it had not had a handler. (*Note |
| Termination in Handler::.) |
| |
| Termination is the sensible ultimate outcome from a program error in |
| most programs. However, programming systems such as Lisp that can load |
| compiled user programs might need to keep executing even if a user |
| program incurs an error. These programs have handlers which use |
| 'longjmp' to return control to the command level. |
| |
| The default action for all of these signals is to cause the process |
| to terminate. If you block or ignore these signals or establish |
| handlers for them that return normally, your program will probably break |
| horribly when such signals happen, unless they are generated by 'raise' |
| or 'kill' instead of a real error. |
| |
| When one of these program error signals terminates a process, it also |
| writes a "core dump file" which records the state of the process at the |
| time of termination. The core dump file is named 'core' and is written |
| in whichever directory is current in the process at the time. (On |
| GNU/Hurd systems, you can specify the file name for core dumps with the |
| environment variable 'COREFILE'.) The purpose of core dump files is so |
| that you can examine them with a debugger to investigate what caused the |
| error. |
| |
| -- Macro: int SIGFPE |
| The 'SIGFPE' signal reports a fatal arithmetic error. Although the |
| name is derived from "floating-point exception", this signal |
| actually covers all arithmetic errors, including division by zero |
| and overflow. If a program stores integer data in a location which |
| is then used in a floating-point operation, this often causes an |
| "invalid operation" exception, because the processor cannot |
| recognize the data as a floating-point number. |
| |
| Actual floating-point exceptions are a complicated subject because |
| there are many types of exceptions with subtly different meanings, |
| and the 'SIGFPE' signal doesn't distinguish between them. The |
| 'IEEE Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Std |
| 754-1985 and ANSI/IEEE Std 854-1987)' defines various |
| floating-point exceptions and requires conforming computer systems |
| to report their occurrences. However, this standard does not |
| specify how the exceptions are reported, or what kinds of handling |
| and control the operating system can offer to the programmer. |
| |
| BSD systems provide the 'SIGFPE' handler with an extra argument that |
| distinguishes various causes of the exception. In order to access this |
| argument, you must define the handler to accept two arguments, which |
| means you must cast it to a one-argument function type in order to |
| establish the handler. The GNU C Library does provide this extra |
| argument, but the value is meaningful only on operating systems that |
| provide the information (BSD systems and GNU systems). |
| |
| 'FPE_INTOVF_TRAP' |
| Integer overflow (impossible in a C program unless you enable |
| overflow trapping in a hardware-specific fashion). |
| 'FPE_INTDIV_TRAP' |
| Integer division by zero. |
| 'FPE_SUBRNG_TRAP' |
| Subscript-range (something that C programs never check for). |
| 'FPE_FLTOVF_TRAP' |
| Floating overflow trap. |
| 'FPE_FLTDIV_TRAP' |
| Floating/decimal division by zero. |
| 'FPE_FLTUND_TRAP' |
| Floating underflow trap. (Trapping on floating underflow is not |
| normally enabled.) |
| 'FPE_DECOVF_TRAP' |
| Decimal overflow trap. (Only a few machines have decimal |
| arithmetic and C never uses it.) |
| |
| -- Macro: int SIGILL |
| The name of this signal is derived from "illegal instruction"; it |
| usually means your program is trying to execute garbage or a |
| privileged instruction. Since the C compiler generates only valid |
| instructions, 'SIGILL' typically indicates that the executable file |
| is corrupted, or that you are trying to execute data. Some common |
| ways of getting into the latter situation are by passing an invalid |
| object where a pointer to a function was expected, or by writing |
| past the end of an automatic array (or similar problems with |
| pointers to automatic variables) and corrupting other data on the |
| stack such as the return address of a stack frame. |
| |
| 'SIGILL' can also be generated when the stack overflows, or when |
| the system has trouble running the handler for a signal. |
| |
| -- Macro: int SIGSEGV |
| This signal is generated when a program tries to read or write |
| outside the memory that is allocated for it, or to write memory |
| that can only be read. (Actually, the signals only occur when the |
| program goes far enough outside to be detected by the system's |
| memory protection mechanism.) The name is an abbreviation for |
| "segmentation violation". |
| |
| Common ways of getting a 'SIGSEGV' condition include dereferencing |
| a null or uninitialized pointer, or when you use a pointer to step |
| through an array, but fail to check for the end of the array. It |
| varies among systems whether dereferencing a null pointer generates |
| 'SIGSEGV' or 'SIGBUS'. |
| |
| -- Macro: int SIGBUS |
| This signal is generated when an invalid pointer is dereferenced. |
| Like 'SIGSEGV', this signal is typically the result of |
| dereferencing an uninitialized pointer. The difference between the |
| two is that 'SIGSEGV' indicates an invalid access to valid memory, |
| while 'SIGBUS' indicates an access to an invalid address. In |
| particular, 'SIGBUS' signals often result from dereferencing a |
| misaligned pointer, such as referring to a four-word integer at an |
| address not divisible by four. (Each kind of computer has its own |
| requirements for address alignment.) |
| |
| The name of this signal is an abbreviation for "bus error". |
| |
| -- Macro: int SIGABRT |
| This signal indicates an error detected by the program itself and |
| reported by calling 'abort'. *Note Aborting a Program::. |
| |
| -- Macro: int SIGIOT |
| Generated by the PDP-11 "iot" instruction. On most machines, this |
| is just another name for 'SIGABRT'. |
| |
| -- Macro: int SIGTRAP |
| Generated by the machine's breakpoint instruction, and possibly |
| other trap instructions. This signal is used by debuggers. Your |
| program will probably only see 'SIGTRAP' if it is somehow executing |
| bad instructions. |
| |
| -- Macro: int SIGEMT |
| Emulator trap; this results from certain unimplemented instructions |
| which might be emulated in software, or the operating system's |
| failure to properly emulate them. |
| |
| -- Macro: int SIGSYS |
| Bad system call; that is to say, the instruction to trap to the |
| operating system was executed, but the code number for the system |
| call to perform was invalid. |
| |
| |
| File: libc.info, Node: Termination Signals, Next: Alarm Signals, Prev: Program Error Signals, Up: Standard Signals |
| |
| 24.2.2 Termination Signals |
| -------------------------- |
| |
| These signals are all used to tell a process to terminate, in one way or |
| another. They have different names because they're used for slightly |
| different purposes, and programs might want to handle them differently. |
| |
| The reason for handling these signals is usually so your program can |
| tidy up as appropriate before actually terminating. For example, you |
| might want to save state information, delete temporary files, or restore |
| the previous terminal modes. Such a handler should end by specifying |
| the default action for the signal that happened and then reraising it; |
| this will cause the program to terminate with that signal, as if it had |
| not had a handler. (*Note Termination in Handler::.) |
| |
| The (obvious) default action for all of these signals is to cause the |
| process to terminate. |
| |
| -- Macro: int SIGTERM |
| The 'SIGTERM' signal is a generic signal used to cause program |
| termination. Unlike 'SIGKILL', this signal can be blocked, |
| handled, and ignored. It is the normal way to politely ask a |
| program to terminate. |
| |
| The shell command 'kill' generates 'SIGTERM' by default. |
| |
| -- Macro: int SIGINT |
| The 'SIGINT' ("program interrupt") signal is sent when the user |
| types the INTR character (normally 'C-c'). *Note Special |
| Characters::, for information about terminal driver support for |
| 'C-c'. |
| |
| -- Macro: int SIGQUIT |
| The 'SIGQUIT' signal is similar to 'SIGINT', except that it's |
| controlled by a different key--the QUIT character, usually |
| 'C-\'--and produces a core dump when it terminates the process, |
| just like a program error signal. You can think of this as a |
| program error condition "detected" by the user. |
| |
| *Note Program Error Signals::, for information about core dumps. |
| *Note Special Characters::, for information about terminal driver |
| support. |
| |
| Certain kinds of cleanups are best omitted in handling 'SIGQUIT'. |
| For example, if the program creates temporary files, it should |
| handle the other termination requests by deleting the temporary |
| files. But it is better for 'SIGQUIT' not to delete them, so that |
| the user can examine them in conjunction with the core dump. |
| |
| -- Macro: int SIGKILL |
| The 'SIGKILL' signal is used to cause immediate program |
| termination. It cannot be handled or ignored, and is therefore |
| always fatal. It is also not possible to block this signal. |
| |
| This signal is usually generated only by explicit request. Since |
| it cannot be handled, you should generate it only as a last resort, |
| after first trying a less drastic method such as 'C-c' or |
| 'SIGTERM'. If a process does not respond to any other termination |
| signals, sending it a 'SIGKILL' signal will almost always cause it |
| to go away. |
| |
| In fact, if 'SIGKILL' fails to terminate a process, that by itself |
| constitutes an operating system bug which you should report. |
| |
| The system will generate 'SIGKILL' for a process itself under some |
| unusual conditions where the program cannot possibly continue to |
| run (even to run a signal handler). |
| |
| -- Macro: int SIGHUP |
| The 'SIGHUP' ("hang-up") signal is used to report that the user's |
| terminal is disconnected, perhaps because a network or telephone |
| connection was broken. For more information about this, see *note |
| Control Modes::. |
| |
| This signal is also used to report the termination of the |
| controlling process on a terminal to jobs associated with that |
| session; this termination effectively disconnects all processes in |
| the session from the controlling terminal. For more information, |
| see *note Termination Internals::. |
| |
| |
| File: libc.info, Node: Alarm Signals, Next: Asynchronous I/O Signals, Prev: Termination Signals, Up: Standard Signals |
| |
| 24.2.3 Alarm Signals |
| -------------------- |
| |
| These signals are used to indicate the expiration of timers. *Note |
| Setting an Alarm::, for information about functions that cause these |
| signals to be sent. |
| |
| The default behavior for these signals is to cause program |
| termination. This default is rarely useful, but no other default would |
| be useful; most of the ways of using these signals would require handler |
| functions in any case. |
| |
| -- Macro: int SIGALRM |
| This signal typically indicates expiration of a timer that measures |
| real or clock time. It is used by the 'alarm' function, for |
| example. |
| |
| -- Macro: int SIGVTALRM |
| This signal typically indicates expiration of a timer that measures |
| CPU time used by the current process. The name is an abbreviation |
| for "virtual time alarm". |
| |
| -- Macro: int SIGPROF |
| This signal typically indicates expiration of a timer that measures |
| both CPU time used by the current process, and CPU time expended on |
| behalf of the process by the system. Such a timer is used to |
| implement code profiling facilities, hence the name of this signal. |
| |
| |
| File: libc.info, Node: Asynchronous I/O Signals, Next: Job Control Signals, Prev: Alarm Signals, Up: Standard Signals |
| |
| 24.2.4 Asynchronous I/O Signals |
| ------------------------------- |
| |
| The signals listed in this section are used in conjunction with |
| asynchronous I/O facilities. You have to take explicit action by |
| calling 'fcntl' to enable a particular file descriptor to generate these |
| signals (*note Interrupt Input::). The default action for these signals |
| is to ignore them. |
| |
| -- Macro: int SIGIO |
| This signal is sent when a file descriptor is ready to perform |
| input or output. |
| |
| On most operating systems, terminals and sockets are the only kinds |
| of files that can generate 'SIGIO'; other kinds, including ordinary |
| files, never generate 'SIGIO' even if you ask them to. |
| |
| On GNU systems 'SIGIO' will always be generated properly if you |
| successfully set asynchronous mode with 'fcntl'. |
| |
| -- Macro: int SIGURG |
| This signal is sent when "urgent" or out-of-band data arrives on a |
| socket. *Note Out-of-Band Data::. |
| |
| -- Macro: int SIGPOLL |
| This is a System V signal name, more or less similar to 'SIGIO'. |
| It is defined only for compatibility. |
| |
| |
| File: libc.info, Node: Job Control Signals, Next: Operation Error Signals, Prev: Asynchronous I/O Signals, Up: Standard Signals |
| |
| 24.2.5 Job Control Signals |
| -------------------------- |
| |
| These signals are used to support job control. If your system doesn't |
| support job control, then these macros are defined but the signals |
| themselves can't be raised or handled. |
| |
| You should generally leave these signals alone unless you really |
| understand how job control works. *Note Job Control::. |
| |
| -- Macro: int SIGCHLD |
| This signal is sent to a parent process whenever one of its child |
| processes terminates or stops. |
| |
| The default action for this signal is to ignore it. If you |
| establish a handler for this signal while there are child processes |
| that have terminated but not reported their status via 'wait' or |
| 'waitpid' (*note Process Completion::), whether your new handler |
| applies to those processes or not depends on the particular |
| operating system. |
| |
| -- Macro: int SIGCLD |
| This is an obsolete name for 'SIGCHLD'. |
| |
| -- Macro: int SIGCONT |
| You can send a 'SIGCONT' signal to a process to make it continue. |
| This signal is special--it always makes the process continue if it |
| is stopped, before the signal is delivered. The default behavior |
| is to do nothing else. You cannot block this signal. You can set |
| a handler, but 'SIGCONT' always makes the process continue |
| regardless. |
| |
| Most programs have no reason to handle 'SIGCONT'; they simply |
| resume execution without realizing they were ever stopped. You can |
| use a handler for 'SIGCONT' to make a program do something special |
| when it is stopped and continued--for example, to reprint a prompt |
| when it is suspended while waiting for input. |
| |
| -- Macro: int SIGSTOP |
| The 'SIGSTOP' signal stops the process. It cannot be handled, |
| ignored, or blocked. |
| |
| -- Macro: int SIGTSTP |
| The 'SIGTSTP' signal is an interactive stop signal. Unlike |
| 'SIGSTOP', this signal can be handled and ignored. |
| |
| Your program should handle this signal if you have a special need |
| to leave files or system tables in a secure state when a process is |
| stopped. For example, programs that turn off echoing should handle |
| 'SIGTSTP' so they can turn echoing back on before stopping. |
| |
| This signal is generated when the user types the SUSP character |
| (normally 'C-z'). For more information about terminal driver |
| support, see *note Special Characters::. |
| |
| -- Macro: int SIGTTIN |
| A process cannot read from the user's terminal while it is running |
| as a background job. When any process in a background job tries to |
| read from the terminal, all of the processes in the job are sent a |
| 'SIGTTIN' signal. The default action for this signal is to stop |
| the process. For more information about how this interacts with |
| the terminal driver, see *note Access to the Terminal::. |
| |
| -- Macro: int SIGTTOU |
| This is similar to 'SIGTTIN', but is generated when a process in a |
| background job attempts to write to the terminal or set its modes. |
| Again, the default action is to stop the process. 'SIGTTOU' is |
| only generated for an attempt to write to the terminal if the |
| 'TOSTOP' output mode is set; *note Output Modes::. |
| |
| While a process is stopped, no more signals can be delivered to it |
| until it is continued, except 'SIGKILL' signals and (obviously) |
| 'SIGCONT' signals. The signals are marked as pending, but not delivered |
| until the process is continued. The 'SIGKILL' signal always causes |
| termination of the process and can't be blocked, handled or ignored. |
| You can ignore 'SIGCONT', but it always causes the process to be |
| continued anyway if it is stopped. Sending a 'SIGCONT' signal to a |
| process causes any pending stop signals for that process to be |
| discarded. Likewise, any pending 'SIGCONT' signals for a process are |
| discarded when it receives a stop signal. |
| |
| When a process in an orphaned process group (*note Orphaned Process |
| Groups::) receives a 'SIGTSTP', 'SIGTTIN', or 'SIGTTOU' signal and does |
| not handle it, the process does not stop. Stopping the process would |
| probably not be very useful, since there is no shell program that will |
| notice it stop and allow the user to continue it. What happens instead |
| depends on the operating system you are using. Some systems may do |
| nothing; others may deliver another signal instead, such as 'SIGKILL' or |
| 'SIGHUP'. On GNU/Hurd systems, the process dies with 'SIGKILL'; this |
| avoids the problem of many stopped, orphaned processes lying around the |
| system. |
| |
| |
| File: libc.info, Node: Operation Error Signals, Next: Miscellaneous Signals, Prev: Job Control Signals, Up: Standard Signals |
| |
| 24.2.6 Operation Error Signals |
| ------------------------------ |
| |
| These signals are used to report various errors generated by an |
| operation done by the program. They do not necessarily indicate a |
| programming error in the program, but an error that prevents an |
| operating system call from completing. The default action for all of |
| them is to cause the process to terminate. |
| |
| -- Macro: int SIGPIPE |
| Broken pipe. If you use pipes or FIFOs, you have to design your |
| application so that one process opens the pipe for reading before |
| another starts writing. If the reading process never starts, or |
| terminates unexpectedly, writing to the pipe or FIFO raises a |
| 'SIGPIPE' signal. If 'SIGPIPE' is blocked, handled or ignored, the |
| offending call fails with 'EPIPE' instead. |
| |
| Pipes and FIFO special files are discussed in more detail in *note |
| Pipes and FIFOs::. |
| |
| Another cause of 'SIGPIPE' is when you try to output to a socket |
| that isn't connected. *Note Sending Data::. |
| |
| -- Macro: int SIGLOST |
| Resource lost. This signal is generated when you have an advisory |
| lock on an NFS file, and the NFS server reboots and forgets about |
| your lock. |
| |
| On GNU/Hurd systems, 'SIGLOST' is generated when any server program |
| dies unexpectedly. It is usually fine to ignore the signal; |
| whatever call was made to the server that died just returns an |
| error. |
| |
| -- Macro: int SIGXCPU |
| CPU time limit exceeded. This signal is generated when the process |
| exceeds its soft resource limit on CPU time. *Note Limits on |
| Resources::. |
| |
| -- Macro: int SIGXFSZ |
| File size limit exceeded. This signal is generated when the |
| process attempts to extend a file so it exceeds the process's soft |
| resource limit on file size. *Note Limits on Resources::. |
| |
| |
| File: libc.info, Node: Miscellaneous Signals, Next: Signal Messages, Prev: Operation Error Signals, Up: Standard Signals |
| |
| 24.2.7 Miscellaneous Signals |
| ---------------------------- |
| |
| These signals are used for various other purposes. In general, they |
| will not affect your program unless it explicitly uses them for |
| something. |
| |
| -- Macro: int SIGUSR1 |
| -- Macro: int SIGUSR2 |
| The 'SIGUSR1' and 'SIGUSR2' signals are set aside for you to use |
| any way you want. They're useful for simple interprocess |
| communication, if you write a signal handler for them in the |
| program that receives the signal. |
| |
| There is an example showing the use of 'SIGUSR1' and 'SIGUSR2' in |
| *note Signaling Another Process::. |
| |
| The default action is to terminate the process. |
| |
| -- Macro: int SIGWINCH |
| Window size change. This is generated on some systems (including |
| GNU) when the terminal driver's record of the number of rows and |
| columns on the screen is changed. The default action is to ignore |
| it. |
| |
| If a program does full-screen display, it should handle 'SIGWINCH'. |
| When the signal arrives, it should fetch the new screen size and |
| reformat its display accordingly. |
| |
| -- Macro: int SIGINFO |
| Information request. On 4.4 BSD and GNU/Hurd systems, this signal |
| is sent to all the processes in the foreground process group of the |
| controlling terminal when the user types the STATUS character in |
| canonical mode; *note Signal Characters::. |
| |
| If the process is the leader of the process group, the default |
| action is to print some status information about the system and |
| what the process is doing. Otherwise the default is to do nothing. |
| |
| |
| File: libc.info, Node: Signal Messages, Prev: Miscellaneous Signals, Up: Standard Signals |
| |
| 24.2.8 Signal Messages |
| ---------------------- |
| |
| We mentioned above that the shell prints a message describing the signal |
| that terminated a child process. The clean way to print a message |
| describing a signal is to use the functions 'strsignal' and 'psignal'. |
| These functions use a signal number to specify which kind of signal to |
| describe. The signal number may come from the termination status of a |
| child process (*note Process Completion::) or it may come from a signal |
| handler in the same process. |
| |
| -- Function: char * strsignal (int SIGNUM) |
| Preliminary: | MT-Unsafe race:strsignal locale | AS-Unsafe init |
| i18n corrupt heap | AC-Unsafe init corrupt mem | *Note POSIX Safety |
| Concepts::. |
| |
| This function returns a pointer to a statically-allocated string |
| containing a message describing the signal SIGNUM. You should not |
| modify the contents of this string; and, since it can be rewritten |
| on subsequent calls, you should save a copy of it if you need to |
| reference it later. |
| |
| This function is a GNU extension, declared in the header file |
| 'string.h'. |
| |
| -- Function: void psignal (int SIGNUM, const char *MESSAGE) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt i18n heap | |
| AC-Unsafe lock corrupt mem | *Note POSIX Safety Concepts::. |
| |
| This function prints a message describing the signal SIGNUM to the |
| standard error output stream 'stderr'; see *note Standard |
| Streams::. |
| |
| If you call 'psignal' with a MESSAGE that is either a null pointer |
| or an empty string, 'psignal' just prints the message corresponding |
| to SIGNUM, adding a trailing newline. |
| |
| If you supply a non-null MESSAGE argument, then 'psignal' prefixes |
| its output with this string. It adds a colon and a space character |
| to separate the MESSAGE from the string corresponding to SIGNUM. |
| |
| This function is a BSD feature, declared in the header file |
| 'signal.h'. |
| |
| There is also an array 'sys_siglist' which contains the messages for |
| the various signal codes. This array exists on BSD systems, unlike |
| 'strsignal'. |
| |
| |
| File: libc.info, Node: Signal Actions, Next: Defining Handlers, Prev: Standard Signals, Up: Signal Handling |
| |
| 24.3 Specifying Signal Actions |
| ============================== |
| |
| The simplest way to change the action for a signal is to use the |
| 'signal' function. You can specify a built-in action (such as to ignore |
| the signal), or you can "establish a handler". |
| |
| The GNU C Library also implements the more versatile 'sigaction' |
| facility. This section describes both facilities and gives suggestions |
| on which to use when. |
| |
| * Menu: |
| |
| * Basic Signal Handling:: The simple 'signal' function. |
| * Advanced Signal Handling:: The more powerful 'sigaction' function. |
| * Signal and Sigaction:: How those two functions interact. |
| * Sigaction Function Example:: An example of using the sigaction function. |
| * Flags for Sigaction:: Specifying options for signal handling. |
| * Initial Signal Actions:: How programs inherit signal actions. |
| |
| |
| File: libc.info, Node: Basic Signal Handling, Next: Advanced Signal Handling, Up: Signal Actions |
| |
| 24.3.1 Basic Signal Handling |
| ---------------------------- |
| |
| The 'signal' function provides a simple interface for establishing an |
| action for a particular signal. The function and associated macros are |
| declared in the header file 'signal.h'. |
| |
| -- Data Type: sighandler_t |
| This is the type of signal handler functions. Signal handlers take |
| one integer argument specifying the signal number, and have return |
| type 'void'. So, you should define handler functions like this: |
| |
| void HANDLER (int signum) { ... } |
| |
| The name 'sighandler_t' for this data type is a GNU extension. |
| |
| -- Function: sighandler_t signal (int SIGNUM, sighandler_t ACTION) |
| Preliminary: | MT-Safe sigintr | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The 'signal' function establishes ACTION as the action for the |
| signal SIGNUM. |
| |
| The first argument, SIGNUM, identifies the signal whose behavior |
| you want to control, and should be a signal number. The proper way |
| to specify a signal number is with one of the symbolic signal names |
| (*note Standard Signals::)--don't use an explicit number, because |
| the numerical code for a given kind of signal may vary from |
| operating system to operating system. |
| |
| The second argument, ACTION, specifies the action to use for the |
| signal SIGNUM. This can be one of the following: |
| |
| 'SIG_DFL' |
| 'SIG_DFL' specifies the default action for the particular |
| signal. The default actions for various kinds of signals are |
| stated in *note Standard Signals::. |
| |
| 'SIG_IGN' |
| 'SIG_IGN' specifies that the signal should be ignored. |
| |
| Your program generally should not ignore signals that |
| represent serious events or that are normally used to request |
| termination. You cannot ignore the 'SIGKILL' or 'SIGSTOP' |
| signals at all. You can ignore program error signals like |
| 'SIGSEGV', but ignoring the error won't enable the program to |
| continue executing meaningfully. Ignoring user requests such |
| as 'SIGINT', 'SIGQUIT', and 'SIGTSTP' is unfriendly. |
| |
| When you do not wish signals to be delivered during a certain |
| part of the program, the thing to do is to block them, not |
| ignore them. *Note Blocking Signals::. |
| |
| 'HANDLER' |
| Supply the address of a handler function in your program, to |
| specify running this handler as the way to deliver the signal. |
| |
| For more information about defining signal handler functions, |
| see *note Defining Handlers::. |
| |
| If you set the action for a signal to 'SIG_IGN', or if you set it |
| to 'SIG_DFL' and the default action is to ignore that signal, then |
| any pending signals of that type are discarded (even if they are |
| blocked). Discarding the pending signals means that they will |
| never be delivered, not even if you subsequently specify another |
| action and unblock this kind of signal. |
| |
| The 'signal' function returns the action that was previously in |
| effect for the specified SIGNUM. You can save this value and |
| restore it later by calling 'signal' again. |
| |
| If 'signal' can't honor the request, it returns 'SIG_ERR' instead. |
| The following 'errno' error conditions are defined for this |
| function: |
| |
| 'EINVAL' |
| You specified an invalid SIGNUM; or you tried to ignore or |
| provide a handler for 'SIGKILL' or 'SIGSTOP'. |
| |
| *Compatibility Note:* A problem encountered when working with the |
| 'signal' function is that it has different semantics on BSD and SVID |
| systems. The difference is that on SVID systems the signal handler is |
| deinstalled after signal delivery. On BSD systems the handler must be |
| explicitly deinstalled. In the GNU C Library we use the BSD version by |
| default. To use the SVID version you can either use the function |
| 'sysv_signal' (see below) or use the '_XOPEN_SOURCE' feature select |
| macro (*note Feature Test Macros::). In general, use of these functions |
| should be avoided because of compatibility problems. It is better to |
| use 'sigaction' if it is available since the results are much more |
| reliable. |
| |
| Here is a simple example of setting up a handler to delete temporary |
| files when certain fatal signals happen: |
| |
| #include <signal.h> |
| |
| void |
| termination_handler (int signum) |
| { |
| struct temp_file *p; |
| |
| for (p = temp_file_list; p; p = p->next) |
| unlink (p->name); |
| } |
| |
| int |
| main (void) |
| { |
| ... |
| if (signal (SIGINT, termination_handler) == SIG_IGN) |
| signal (SIGINT, SIG_IGN); |
| if (signal (SIGHUP, termination_handler) == SIG_IGN) |
| signal (SIGHUP, SIG_IGN); |
| if (signal (SIGTERM, termination_handler) == SIG_IGN) |
| signal (SIGTERM, SIG_IGN); |
| ... |
| } |
| |
| Note that if a given signal was previously set to be ignored, this code |
| avoids altering that setting. This is because non-job-control shells |
| often ignore certain signals when starting children, and it is important |
| for the children to respect this. |
| |
| We do not handle 'SIGQUIT' or the program error signals in this |
| example because these are designed to provide information for debugging |
| (a core dump), and the temporary files may give useful information. |
| |
| -- Function: sighandler_t sysv_signal (int SIGNUM, sighandler_t ACTION) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'sysv_signal' implements the behavior of the standard 'signal' |
| function as found on SVID systems. The difference to BSD systems |
| is that the handler is deinstalled after a delivery of a signal. |
| |
| *Compatibility Note:* As said above for 'signal', this function |
| should be avoided when possible. 'sigaction' is the preferred |
| method. |
| |
| -- Function: sighandler_t ssignal (int SIGNUM, sighandler_t ACTION) |
| Preliminary: | MT-Safe sigintr | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The 'ssignal' function does the same thing as 'signal'; it is |
| provided only for compatibility with SVID. |
| |
| -- Macro: sighandler_t SIG_ERR |
| The value of this macro is used as the return value from 'signal' |
| to indicate an error. |
| |
| |
| File: libc.info, Node: Advanced Signal Handling, Next: Signal and Sigaction, Prev: Basic Signal Handling, Up: Signal Actions |
| |
| 24.3.2 Advanced Signal Handling |
| ------------------------------- |
| |
| The 'sigaction' function has the same basic effect as 'signal': to |
| specify how a signal should be handled by the process. However, |
| 'sigaction' offers more control, at the expense of more complexity. In |
| particular, 'sigaction' allows you to specify additional flags to |
| control when the signal is generated and how the handler is invoked. |
| |
| The 'sigaction' function is declared in 'signal.h'. |
| |
| -- Data Type: struct sigaction |
| Structures of type 'struct sigaction' are used in the 'sigaction' |
| function to specify all the information about how to handle a |
| particular signal. This structure contains at least the following |
| members: |
| |
| 'sighandler_t sa_handler' |
| This is used in the same way as the ACTION argument to the |
| 'signal' function. The value can be 'SIG_DFL', 'SIG_IGN', or |
| a function pointer. *Note Basic Signal Handling::. |
| |
| 'sigset_t sa_mask' |
| This specifies a set of signals to be blocked while the |
| handler runs. Blocking is explained in *note Blocking for |
| Handler::. Note that the signal that was delivered is |
| automatically blocked by default before its handler is |
| started; this is true regardless of the value in 'sa_mask'. |
| If you want that signal not to be blocked within its handler, |
| you must write code in the handler to unblock it. |
| |
| 'int sa_flags' |
| This specifies various flags which can affect the behavior of |
| the signal. These are described in more detail in *note Flags |
| for Sigaction::. |
| |
| -- Function: int sigaction (int SIGNUM, const struct sigaction |
| *restrict ACTION, struct sigaction *restrict OLD-ACTION) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The ACTION argument is used to set up a new action for the signal |
| SIGNUM, while the OLD-ACTION argument is used to return information |
| about the action previously associated with this symbol. (In other |
| words, OLD-ACTION has the same purpose as the 'signal' function's |
| return value--you can check to see what the old action in effect |
| for the signal was, and restore it later if you want.) |
| |
| Either ACTION or OLD-ACTION can be a null pointer. If OLD-ACTION |
| is a null pointer, this simply suppresses the return of information |
| about the old action. If ACTION is a null pointer, the action |
| associated with the signal SIGNUM is unchanged; this allows you to |
| inquire about how a signal is being handled without changing that |
| handling. |
| |
| The return value from 'sigaction' is zero if it succeeds, and '-1' |
| on failure. The following 'errno' error conditions are defined for |
| this function: |
| |
| 'EINVAL' |
| The SIGNUM argument is not valid, or you are trying to trap or |
| ignore 'SIGKILL' or 'SIGSTOP'. |
| |
| |
| File: libc.info, Node: Signal and Sigaction, Next: Sigaction Function Example, Prev: Advanced Signal Handling, Up: Signal Actions |
| |
| 24.3.3 Interaction of 'signal' and 'sigaction' |
| ---------------------------------------------- |
| |
| It's possible to use both the 'signal' and 'sigaction' functions within |
| a single program, but you have to be careful because they can interact |
| in slightly strange ways. |
| |
| The 'sigaction' function specifies more information than the 'signal' |
| function, so the return value from 'signal' cannot express the full |
| range of 'sigaction' possibilities. Therefore, if you use 'signal' to |
| save and later reestablish an action, it may not be able to reestablish |
| properly a handler that was established with 'sigaction'. |
| |
| To avoid having problems as a result, always use 'sigaction' to save |
| and restore a handler if your program uses 'sigaction' at all. Since |
| 'sigaction' is more general, it can properly save and reestablish any |
| action, regardless of whether it was established originally with |
| 'signal' or 'sigaction'. |
| |
| On some systems if you establish an action with 'signal' and then |
| examine it with 'sigaction', the handler address that you get may not be |
| the same as what you specified with 'signal'. It may not even be |
| suitable for use as an action argument with 'signal'. But you can rely |
| on using it as an argument to 'sigaction'. This problem never happens |
| on GNU systems. |
| |
| So, you're better off using one or the other of the mechanisms |
| consistently within a single program. |
| |
| *Portability Note:* The basic 'signal' function is a feature of |
| ISO C, while 'sigaction' is part of the POSIX.1 standard. If you are |
| concerned about portability to non-POSIX systems, then you should use |
| the 'signal' function instead. |
| |
| |
| File: libc.info, Node: Sigaction Function Example, Next: Flags for Sigaction, Prev: Signal and Sigaction, Up: Signal Actions |
| |
| 24.3.4 'sigaction' Function Example |
| ----------------------------------- |
| |
| In *note Basic Signal Handling::, we gave an example of establishing a |
| simple handler for termination signals using 'signal'. Here is an |
| equivalent example using 'sigaction': |
| |
| #include <signal.h> |
| |
| void |
| termination_handler (int signum) |
| { |
| struct temp_file *p; |
| |
| for (p = temp_file_list; p; p = p->next) |
| unlink (p->name); |
| } |
| |
| int |
| main (void) |
| { |
| ... |
| struct sigaction new_action, old_action; |
| |
| /* Set up the structure to specify the new action. */ |
| new_action.sa_handler = termination_handler; |
| sigemptyset (&new_action.sa_mask); |
| new_action.sa_flags = 0; |
| |
| sigaction (SIGINT, NULL, &old_action); |
| if (old_action.sa_handler != SIG_IGN) |
| sigaction (SIGINT, &new_action, NULL); |
| sigaction (SIGHUP, NULL, &old_action); |
| if (old_action.sa_handler != SIG_IGN) |
| sigaction (SIGHUP, &new_action, NULL); |
| sigaction (SIGTERM, NULL, &old_action); |
| if (old_action.sa_handler != SIG_IGN) |
| sigaction (SIGTERM, &new_action, NULL); |
| ... |
| } |
| |
| The program just loads the 'new_action' structure with the desired |
| parameters and passes it in the 'sigaction' call. The usage of |
| 'sigemptyset' is described later; see *note Blocking Signals::. |
| |
| As in the example using 'signal', we avoid handling signals |
| previously set to be ignored. Here we can avoid altering the signal |
| handler even momentarily, by using the feature of 'sigaction' that lets |
| us examine the current action without specifying a new one. |
| |
| Here is another example. It retrieves information about the current |
| action for 'SIGINT' without changing that action. |
| |
| struct sigaction query_action; |
| |
| if (sigaction (SIGINT, NULL, &query_action) < 0) |
| /* 'sigaction' returns -1 in case of error. */ |
| else if (query_action.sa_handler == SIG_DFL) |
| /* 'SIGINT' is handled in the default, fatal manner. */ |
| else if (query_action.sa_handler == SIG_IGN) |
| /* 'SIGINT' is ignored. */ |
| else |
| /* A programmer-defined signal handler is in effect. */ |
| |
| |
| File: libc.info, Node: Flags for Sigaction, Next: Initial Signal Actions, Prev: Sigaction Function Example, Up: Signal Actions |
| |
| 24.3.5 Flags for 'sigaction' |
| ---------------------------- |
| |
| The 'sa_flags' member of the 'sigaction' structure is a catch-all for |
| special features. Most of the time, 'SA_RESTART' is a good value to use |
| for this field. |
| |
| The value of 'sa_flags' is interpreted as a bit mask. Thus, you |
| should choose the flags you want to set, OR those flags together, and |
| store the result in the 'sa_flags' member of your 'sigaction' structure. |
| |
| Each signal number has its own set of flags. Each call to |
| 'sigaction' affects one particular signal number, and the flags that you |
| specify apply only to that particular signal. |
| |
| In the GNU C Library, establishing a handler with 'signal' sets all |
| the flags to zero except for 'SA_RESTART', whose value depends on the |
| settings you have made with 'siginterrupt'. *Note Interrupted |
| Primitives::, to see what this is about. |
| |
| These macros are defined in the header file 'signal.h'. |
| |
| -- Macro: int SA_NOCLDSTOP |
| This flag is meaningful only for the 'SIGCHLD' signal. When the |
| flag is set, the system delivers the signal for a terminated child |
| process but not for one that is stopped. By default, 'SIGCHLD' is |
| delivered for both terminated children and stopped children. |
| |
| Setting this flag for a signal other than 'SIGCHLD' has no effect. |
| |
| -- Macro: int SA_ONSTACK |
| If this flag is set for a particular signal number, the system uses |
| the signal stack when delivering that kind of signal. *Note Signal |
| Stack::. If a signal with this flag arrives and you have not set a |
| signal stack, the system terminates the program with 'SIGILL'. |
| |
| -- Macro: int SA_RESTART |
| This flag controls what happens when a signal is delivered during |
| certain primitives (such as 'open', 'read' or 'write'), and the |
| signal handler returns normally. There are two alternatives: the |
| library function can resume, or it can return failure with error |
| code 'EINTR'. |
| |
| The choice is controlled by the 'SA_RESTART' flag for the |
| particular kind of signal that was delivered. If the flag is set, |
| returning from a handler resumes the library function. If the flag |
| is clear, returning from a handler makes the function fail. *Note |
| Interrupted Primitives::. |
| |
| |
| File: libc.info, Node: Initial Signal Actions, Prev: Flags for Sigaction, Up: Signal Actions |
| |
| 24.3.6 Initial Signal Actions |
| ----------------------------- |
| |
| When a new process is created (*note Creating a Process::), it inherits |
| handling of signals from its parent process. However, when you load a |
| new process image using the 'exec' function (*note Executing a File::), |
| any signals that you've defined your own handlers for revert to their |
| 'SIG_DFL' handling. (If you think about it a little, this makes sense; |
| the handler functions from the old program are specific to that program, |
| and aren't even present in the address space of the new program image.) |
| Of course, the new program can establish its own handlers. |
| |
| When a program is run by a shell, the shell normally sets the initial |
| actions for the child process to 'SIG_DFL' or 'SIG_IGN', as appropriate. |
| It's a good idea to check to make sure that the shell has not set up an |
| initial action of 'SIG_IGN' before you establish your own signal |
| handlers. |
| |
| Here is an example of how to establish a handler for 'SIGHUP', but |
| not if 'SIGHUP' is currently ignored: |
| |
| ... |
| struct sigaction temp; |
| |
| sigaction (SIGHUP, NULL, &temp); |
| |
| if (temp.sa_handler != SIG_IGN) |
| { |
| temp.sa_handler = handle_sighup; |
| sigemptyset (&temp.sa_mask); |
| sigaction (SIGHUP, &temp, NULL); |
| } |
| |
| |
| File: libc.info, Node: Defining Handlers, Next: Interrupted Primitives, Prev: Signal Actions, Up: Signal Handling |
| |
| 24.4 Defining Signal Handlers |
| ============================= |
| |
| This section describes how to write a signal handler function that can |
| be established with the 'signal' or 'sigaction' functions. |
| |
| A signal handler is just a function that you compile together with |
| the rest of the program. Instead of directly invoking the function, you |
| use 'signal' or 'sigaction' to tell the operating system to call it when |
| a signal arrives. This is known as "establishing" the handler. *Note |
| Signal Actions::. |
| |
| There are two basic strategies you can use in signal handler |
| functions: |
| |
| * You can have the handler function note that the signal arrived by |
| tweaking some global data structures, and then return normally. |
| |
| * You can have the handler function terminate the program or transfer |
| control to a point where it can recover from the situation that |
| caused the signal. |
| |
| You need to take special care in writing handler functions because |
| they can be called asynchronously. That is, a handler might be called |
| at any point in the program, unpredictably. If two signals arrive |
| during a very short interval, one handler can run within another. This |
| section describes what your handler should do, and what you should |
| avoid. |
| |
| * Menu: |
| |
| * Handler Returns:: Handlers that return normally, and what |
| this means. |
| * Termination in Handler:: How handler functions terminate a program. |
| * Longjmp in Handler:: Nonlocal transfer of control out of a |
| signal handler. |
| * Signals in Handler:: What happens when signals arrive while |
| the handler is already occupied. |
| * Merged Signals:: When a second signal arrives before the |
| first is handled. |
| * Nonreentrancy:: Do not call any functions unless you know they |
| are reentrant with respect to signals. |
| * Atomic Data Access:: A single handler can run in the middle of |
| reading or writing a single object. |
| |
| |
| File: libc.info, Node: Handler Returns, Next: Termination in Handler, Up: Defining Handlers |
| |
| 24.4.1 Signal Handlers that Return |
| ---------------------------------- |
| |
| Handlers which return normally are usually used for signals such as |
| 'SIGALRM' and the I/O and interprocess communication signals. But a |
| handler for 'SIGINT' might also return normally after setting a flag |
| that tells the program to exit at a convenient time. |
| |
| It is not safe to return normally from the handler for a program |
| error signal, because the behavior of the program when the handler |
| function returns is not defined after a program error. *Note Program |
| Error Signals::. |
| |
| Handlers that return normally must modify some global variable in |
| order to have any effect. Typically, the variable is one that is |
| examined periodically by the program during normal operation. Its data |
| type should be 'sig_atomic_t' for reasons described in *note Atomic Data |
| Access::. |
| |
| Here is a simple example of such a program. It executes the body of |
| the loop until it has noticed that a 'SIGALRM' signal has arrived. This |
| technique is useful because it allows the iteration in progress when the |
| signal arrives to complete before the loop exits. |
| |
| |
| #include <signal.h> |
| #include <stdio.h> |
| #include <stdlib.h> |
| |
| /* This flag controls termination of the main loop. */ |
| volatile sig_atomic_t keep_going = 1; |
| |
| /* The signal handler just clears the flag and re-enables itself. */ |
| void |
| catch_alarm (int sig) |
| { |
| keep_going = 0; |
| signal (sig, catch_alarm); |
| } |
| |
| void |
| do_stuff (void) |
| { |
| puts ("Doing stuff while waiting for alarm...."); |
| } |
| |
| int |
| main (void) |
| { |
| /* Establish a handler for SIGALRM signals. */ |
| signal (SIGALRM, catch_alarm); |
| |
| /* Set an alarm to go off in a little while. */ |
| alarm (2); |
| |
| /* Check the flag once in a while to see when to quit. */ |
| while (keep_going) |
| do_stuff (); |
| |
| return EXIT_SUCCESS; |
| } |
| |
| |
| File: libc.info, Node: Termination in Handler, Next: Longjmp in Handler, Prev: Handler Returns, Up: Defining Handlers |
| |
| 24.4.2 Handlers That Terminate the Process |
| ------------------------------------------ |
| |
| Handler functions that terminate the program are typically used to cause |
| orderly cleanup or recovery from program error signals and interactive |
| interrupts. |
| |
| The cleanest way for a handler to terminate the process is to raise |
| the same signal that ran the handler in the first place. Here is how to |
| do this: |
| |
| volatile sig_atomic_t fatal_error_in_progress = 0; |
| |
| void |
| fatal_error_signal (int sig) |
| { |
| /* Since this handler is established for more than one kind of signal, |
| it might still get invoked recursively by delivery of some other kind |
| of signal. Use a static variable to keep track of that. */ |
| if (fatal_error_in_progress) |
| raise (sig); |
| fatal_error_in_progress = 1; |
| |
| /* Now do the clean up actions: |
| - reset terminal modes |
| - kill child processes |
| - remove lock files */ |
| ... |
| |
| /* Now reraise the signal. We reactivate the signal's |
| default handling, which is to terminate the process. |
| We could just call 'exit' or 'abort', |
| but reraising the signal sets the return status |
| from the process correctly. */ |
| signal (sig, SIG_DFL); |
| raise (sig); |
| } |
| |
| |
| File: libc.info, Node: Longjmp in Handler, Next: Signals in Handler, Prev: Termination in Handler, Up: Defining Handlers |
| |
| 24.4.3 Nonlocal Control Transfer in Handlers |
| -------------------------------------------- |
| |
| You can do a nonlocal transfer of control out of a signal handler using |
| the 'setjmp' and 'longjmp' facilities (*note Non-Local Exits::). |
| |
| When the handler does a nonlocal control transfer, the part of the |
| program that was running will not continue. If this part of the program |
| was in the middle of updating an important data structure, the data |
| structure will remain inconsistent. Since the program does not |
| terminate, the inconsistency is likely to be noticed later on. |
| |
| There are two ways to avoid this problem. One is to block the signal |
| for the parts of the program that update important data structures. |
| Blocking the signal delays its delivery until it is unblocked, once the |
| critical updating is finished. *Note Blocking Signals::. |
| |
| The other way is to re-initialize the crucial data structures in the |
| signal handler, or to make their values consistent. |
| |
| Here is a rather schematic example showing the reinitialization of |
| one global variable. |
| |
| #include <signal.h> |
| #include <setjmp.h> |
| |
| jmp_buf return_to_top_level; |
| |
| volatile sig_atomic_t waiting_for_input; |
| |
| void |
| handle_sigint (int signum) |
| { |
| /* We may have been waiting for input when the signal arrived, |
| but we are no longer waiting once we transfer control. */ |
| waiting_for_input = 0; |
| longjmp (return_to_top_level, 1); |
| } |
| |
| int |
| main (void) |
| { |
| ... |
| signal (SIGINT, sigint_handler); |
| ... |
| while (1) { |
| prepare_for_command (); |
| if (setjmp (return_to_top_level) == 0) |
| read_and_execute_command (); |
| } |
| } |
| |
| /* Imagine this is a subroutine used by various commands. */ |
| char * |
| read_data () |
| { |
| if (input_from_terminal) { |
| waiting_for_input = 1; |
| ... |
| waiting_for_input = 0; |
| } else { |
| ... |
| } |
| } |
| |
| |
| File: libc.info, Node: Signals in Handler, Next: Merged Signals, Prev: Longjmp in Handler, Up: Defining Handlers |
| |
| 24.4.4 Signals Arriving While a Handler Runs |
| -------------------------------------------- |
| |
| What happens if another signal arrives while your signal handler |
| function is running? |
| |
| When the handler for a particular signal is invoked, that signal is |
| automatically blocked until the handler returns. That means that if two |
| signals of the same kind arrive close together, the second one will be |
| held until the first has been handled. (The handler can explicitly |
| unblock the signal using 'sigprocmask', if you want to allow more |
| signals of this type to arrive; see *note Process Signal Mask::.) |
| |
| However, your handler can still be interrupted by delivery of another |
| kind of signal. To avoid this, you can use the 'sa_mask' member of the |
| action structure passed to 'sigaction' to explicitly specify which |
| signals should be blocked while the signal handler runs. These signals |
| are in addition to the signal for which the handler was invoked, and any |
| other signals that are normally blocked by the process. *Note Blocking |
| for Handler::. |
| |
| When the handler returns, the set of blocked signals is restored to |
| the value it had before the handler ran. So using 'sigprocmask' inside |
| the handler only affects what signals can arrive during the execution of |
| the handler itself, not what signals can arrive once the handler |
| returns. |
| |
| *Portability Note:* Always use 'sigaction' to establish a handler for |
| a signal that you expect to receive asynchronously, if you want your |
| program to work properly on System V Unix. On this system, the handling |
| of a signal whose handler was established with 'signal' automatically |
| sets the signal's action back to 'SIG_DFL', and the handler must |
| re-establish itself each time it runs. This practice, while |
| inconvenient, does work when signals cannot arrive in succession. |
| However, if another signal can arrive right away, it may arrive before |
| the handler can re-establish itself. Then the second signal would |
| receive the default handling, which could terminate the process. |
| |
| |
| File: libc.info, Node: Merged Signals, Next: Nonreentrancy, Prev: Signals in Handler, Up: Defining Handlers |
| |
| 24.4.5 Signals Close Together Merge into One |
| -------------------------------------------- |
| |
| If multiple signals of the same type are delivered to your process |
| before your signal handler has a chance to be invoked at all, the |
| handler may only be invoked once, as if only a single signal had |
| arrived. In effect, the signals merge into one. This situation can |
| arise when the signal is blocked, or in a multiprocessing environment |
| where the system is busy running some other processes while the signals |
| are delivered. This means, for example, that you cannot reliably use a |
| signal handler to count signals. The only distinction you can reliably |
| make is whether at least one signal has arrived since a given time in |
| the past. |
| |
| Here is an example of a handler for 'SIGCHLD' that compensates for |
| the fact that the number of signals received may not equal the number of |
| child processes that generate them. It assumes that the program keeps |
| track of all the child processes with a chain of structures as follows: |
| |
| struct process |
| { |
| struct process *next; |
| /* The process ID of this child. */ |
| int pid; |
| /* The descriptor of the pipe or pseudo terminal |
| on which output comes from this child. */ |
| int input_descriptor; |
| /* Nonzero if this process has stopped or terminated. */ |
| sig_atomic_t have_status; |
| /* The status of this child; 0 if running, |
| otherwise a status value from 'waitpid'. */ |
| int status; |
| }; |
| |
| struct process *process_list; |
| |
| This example also uses a flag to indicate whether signals have |
| arrived since some time in the past--whenever the program last cleared |
| it to zero. |
| |
| /* Nonzero means some child's status has changed |
| so look at 'process_list' for the details. */ |
| int process_status_change; |
| |
| Here is the handler itself: |
| |
| void |
| sigchld_handler (int signo) |
| { |
| int old_errno = errno; |
| |
| while (1) { |
| register int pid; |
| int w; |
| struct process *p; |
| |
| /* Keep asking for a status until we get a definitive result. */ |
| do |
| { |
| errno = 0; |
| pid = waitpid (WAIT_ANY, &w, WNOHANG | WUNTRACED); |
| } |
| while (pid <= 0 && errno == EINTR); |
| |
| if (pid <= 0) { |
| /* A real failure means there are no more |
| stopped or terminated child processes, so return. */ |
| errno = old_errno; |
| return; |
| } |
| |
| /* Find the process that signaled us, and record its status. */ |
| |
| for (p = process_list; p; p = p->next) |
| if (p->pid == pid) { |
| p->status = w; |
| /* Indicate that the 'status' field |
| has data to look at. We do this only after storing it. */ |
| p->have_status = 1; |
| |
| /* If process has terminated, stop waiting for its output. */ |
| if (WIFSIGNALED (w) || WIFEXITED (w)) |
| if (p->input_descriptor) |
| FD_CLR (p->input_descriptor, &input_wait_mask); |
| |
| /* The program should check this flag from time to time |
| to see if there is any news in 'process_list'. */ |
| ++process_status_change; |
| } |
| |
| /* Loop around to handle all the processes |
| that have something to tell us. */ |
| } |
| } |
| |
| Here is the proper way to check the flag 'process_status_change': |
| |
| if (process_status_change) { |
| struct process *p; |
| process_status_change = 0; |
| for (p = process_list; p; p = p->next) |
| if (p->have_status) { |
| ... Examine 'p->status' ... |
| } |
| } |
| |
| It is vital to clear the flag before examining the list; otherwise, if a |
| signal were delivered just before the clearing of the flag, and after |
| the appropriate element of the process list had been checked, the status |
| change would go unnoticed until the next signal arrived to set the flag |
| again. You could, of course, avoid this problem by blocking the signal |
| while scanning the list, but it is much more elegant to guarantee |
| correctness by doing things in the right order. |
| |
| The loop which checks process status avoids examining 'p->status' |
| until it sees that status has been validly stored. This is to make sure |
| that the status cannot change in the middle of accessing it. Once |
| 'p->have_status' is set, it means that the child process is stopped or |
| terminated, and in either case, it cannot stop or terminate again until |
| the program has taken notice. *Note Atomic Usage::, for more |
| information about coping with interruptions during accesses of a |
| variable. |
| |
| Here is another way you can test whether the handler has run since |
| the last time you checked. This technique uses a counter which is never |
| changed outside the handler. Instead of clearing the count, the program |
| remembers the previous value and sees whether it has changed since the |
| previous check. The advantage of this method is that different parts of |
| the program can check independently, each part checking whether there |
| has been a signal since that part last checked. |
| |
| sig_atomic_t process_status_change; |
| |
| sig_atomic_t last_process_status_change; |
| |
| ... |
| { |
| sig_atomic_t prev = last_process_status_change; |
| last_process_status_change = process_status_change; |
| if (last_process_status_change != prev) { |
| struct process *p; |
| for (p = process_list; p; p = p->next) |
| if (p->have_status) { |
| ... Examine 'p->status' ... |
| } |
| } |
| } |
| |
| |
| File: libc.info, Node: Nonreentrancy, Next: Atomic Data Access, Prev: Merged Signals, Up: Defining Handlers |
| |
| 24.4.6 Signal Handling and Nonreentrant Functions |
| ------------------------------------------------- |
| |
| Handler functions usually don't do very much. The best practice is to |
| write a handler that does nothing but set an external variable that the |
| program checks regularly, and leave all serious work to the program. |
| This is best because the handler can be called asynchronously, at |
| unpredictable times--perhaps in the middle of a primitive function, or |
| even between the beginning and the end of a C operator that requires |
| multiple instructions. The data structures being manipulated might |
| therefore be in an inconsistent state when the handler function is |
| invoked. Even copying one 'int' variable into another can take two |
| instructions on most machines. |
| |
| This means you have to be very careful about what you do in a signal |
| handler. |
| |
| * If your handler needs to access any global variables from your |
| program, declare those variables 'volatile'. This tells the |
| compiler that the value of the variable might change |
| asynchronously, and inhibits certain optimizations that would be |
| invalidated by such modifications. |
| |
| * If you call a function in the handler, make sure it is "reentrant" |
| with respect to signals, or else make sure that the signal cannot |
| interrupt a call to a related function. |
| |
| A function can be non-reentrant if it uses memory that is not on the |
| stack. |
| |
| * If a function uses a static variable or a global variable, or a |
| dynamically-allocated object that it finds for itself, then it is |
| non-reentrant and any two calls to the function can interfere. |
| |
| For example, suppose that the signal handler uses 'gethostbyname'. |
| This function returns its value in a static object, reusing the |
| same object each time. If the signal happens to arrive during a |
| call to 'gethostbyname', or even after one (while the program is |
| still using the value), it will clobber the value that the program |
| asked for. |
| |
| However, if the program does not use 'gethostbyname' or any other |
| function that returns information in the same object, or if it |
| always blocks signals around each use, then you are safe. |
| |
| There are a large number of library functions that return values in |
| a fixed object, always reusing the same object in this fashion, and |
| all of them cause the same problem. Function descriptions in this |
| manual always mention this behavior. |
| |
| * If a function uses and modifies an object that you supply, then it |
| is potentially non-reentrant; two calls can interfere if they use |
| the same object. |
| |
| This case arises when you do I/O using streams. Suppose that the |
| signal handler prints a message with 'fprintf'. Suppose that the |
| program was in the middle of an 'fprintf' call using the same |
| stream when the signal was delivered. Both the signal handler's |
| message and the program's data could be corrupted, because both |
| calls operate on the same data structure--the stream itself. |
| |
| However, if you know that the stream that the handler uses cannot |
| possibly be used by the program at a time when signals can arrive, |
| then you are safe. It is no problem if the program uses some other |
| stream. |
| |
| * On most systems, 'malloc' and 'free' are not reentrant, because |
| they use a static data structure which records what memory blocks |
| are free. As a result, no library functions that allocate or free |
| memory are reentrant. This includes functions that allocate space |
| to store a result. |
| |
| The best way to avoid the need to allocate memory in a handler is |
| to allocate in advance space for signal handlers to use. |
| |
| The best way to avoid freeing memory in a handler is to flag or |
| record the objects to be freed, and have the program check from |
| time to time whether anything is waiting to be freed. But this |
| must be done with care, because placing an object on a chain is not |
| atomic, and if it is interrupted by another signal handler that |
| does the same thing, you could "lose" one of the objects. |
| |
| * Any function that modifies 'errno' is non-reentrant, but you can |
| correct for this: in the handler, save the original value of |
| 'errno' and restore it before returning normally. This prevents |
| errors that occur within the signal handler from being confused |
| with errors from system calls at the point the program is |
| interrupted to run the handler. |
| |
| This technique is generally applicable; if you want to call in a |
| handler a function that modifies a particular object in memory, you |
| can make this safe by saving and restoring that object. |
| |
| * Merely reading from a memory object is safe provided that you can |
| deal with any of the values that might appear in the object at a |
| time when the signal can be delivered. Keep in mind that |
| assignment to some data types requires more than one instruction, |
| which means that the handler could run "in the middle of" an |
| assignment to the variable if its type is not atomic. *Note Atomic |
| Data Access::. |
| |
| * Merely writing into a memory object is safe as long as a sudden |
| change in the value, at any time when the handler might run, will |
| not disturb anything. |
| |
| |
| File: libc.info, Node: Atomic Data Access, Prev: Nonreentrancy, Up: Defining Handlers |
| |
| 24.4.7 Atomic Data Access and Signal Handling |
| --------------------------------------------- |
| |
| Whether the data in your application concerns atoms, or mere text, you |
| have to be careful about the fact that access to a single datum is not |
| necessarily "atomic". This means that it can take more than one |
| instruction to read or write a single object. In such cases, a signal |
| handler might be invoked in the middle of reading or writing the object. |
| |
| There are three ways you can cope with this problem. You can use |
| data types that are always accessed atomically; you can carefully |
| arrange that nothing untoward happens if an access is interrupted, or |
| you can block all signals around any access that had better not be |
| interrupted (*note Blocking Signals::). |
| |
| * Menu: |
| |
| * Non-atomic Example:: A program illustrating interrupted access. |
| * Types: Atomic Types. Data types that guarantee no interruption. |
| * Usage: Atomic Usage. Proving that interruption is harmless. |
| |
| |
| File: libc.info, Node: Non-atomic Example, Next: Atomic Types, Up: Atomic Data Access |
| |
| 24.4.7.1 Problems with Non-Atomic Access |
| ........................................ |
| |
| Here is an example which shows what can happen if a signal handler runs |
| in the middle of modifying a variable. (Interrupting the reading of a |
| variable can also lead to paradoxical results, but here we only show |
| writing.) |
| |
| #include <signal.h> |
| #include <stdio.h> |
| |
| volatile struct two_words { int a, b; } memory; |
| |
| void |
| handler(int signum) |
| { |
| printf ("%d,%d\n", memory.a, memory.b); |
| alarm (1); |
| } |
| |
| int |
| main (void) |
| { |
| static struct two_words zeros = { 0, 0 }, ones = { 1, 1 }; |
| signal (SIGALRM, handler); |
| memory = zeros; |
| alarm (1); |
| while (1) |
| { |
| memory = zeros; |
| memory = ones; |
| } |
| } |
| |
| This program fills 'memory' with zeros, ones, zeros, ones, |
| alternating forever; meanwhile, once per second, the alarm signal |
| handler prints the current contents. (Calling 'printf' in the handler |
| is safe in this program because it is certainly not being called outside |
| the handler when the signal happens.) |
| |
| Clearly, this program can print a pair of zeros or a pair of ones. |
| But that's not all it can do! On most machines, it takes several |
| instructions to store a new value in 'memory', and the value is stored |
| one word at a time. If the signal is delivered in between these |
| instructions, the handler might find that 'memory.a' is zero and |
| 'memory.b' is one (or vice versa). |
| |
| On some machines it may be possible to store a new value in 'memory' |
| with just one instruction that cannot be interrupted. On these |
| machines, the handler will always print two zeros or two ones. |
| |
| |
| File: libc.info, Node: Atomic Types, Next: Atomic Usage, Prev: Non-atomic Example, Up: Atomic Data Access |
| |
| 24.4.7.2 Atomic Types |
| ..................... |
| |
| To avoid uncertainty about interrupting access to a variable, you can |
| use a particular data type for which access is always atomic: |
| 'sig_atomic_t'. Reading and writing this data type is guaranteed to |
| happen in a single instruction, so there's no way for a handler to run |
| "in the middle" of an access. |
| |
| The type 'sig_atomic_t' is always an integer data type, but which one |
| it is, and how many bits it contains, may vary from machine to machine. |
| |
| -- Data Type: sig_atomic_t |
| This is an integer data type. Objects of this type are always |
| accessed atomically. |
| |
| In practice, you can assume that 'int' is atomic. You can also |
| assume that pointer types are atomic; that is very convenient. Both of |
| these assumptions are true on all of the machines that the GNU C Library |
| supports and on all POSIX systems we know of. |
| |
| |
| File: libc.info, Node: Atomic Usage, Prev: Atomic Types, Up: Atomic Data Access |
| |
| 24.4.7.3 Atomic Usage Patterns |
| .............................. |
| |
| Certain patterns of access avoid any problem even if an access is |
| interrupted. For example, a flag which is set by the handler, and |
| tested and cleared by the main program from time to time, is always safe |
| even if access actually requires two instructions. To show that this is |
| so, we must consider each access that could be interrupted, and show |
| that there is no problem if it is interrupted. |
| |
| An interrupt in the middle of testing the flag is safe because either |
| it's recognized to be nonzero, in which case the precise value doesn't |
| matter, or it will be seen to be nonzero the next time it's tested. |
| |
| An interrupt in the middle of clearing the flag is no problem because |
| either the value ends up zero, which is what happens if a signal comes |
| in just before the flag is cleared, or the value ends up nonzero, and |
| subsequent events occur as if the signal had come in just after the flag |
| was cleared. As long as the code handles both of these cases properly, |
| it can also handle a signal in the middle of clearing the flag. (This |
| is an example of the sort of reasoning you need to do to figure out |
| whether non-atomic usage is safe.) |
| |
| Sometimes you can insure uninterrupted access to one object by |
| protecting its use with another object, perhaps one whose type |
| guarantees atomicity. *Note Merged Signals::, for an example. |
| |
| |
| File: libc.info, Node: Interrupted Primitives, Next: Generating Signals, Prev: Defining Handlers, Up: Signal Handling |
| |
| 24.5 Primitives Interrupted by Signals |
| ====================================== |
| |
| A signal can arrive and be handled while an I/O primitive such as 'open' |
| or 'read' is waiting for an I/O device. If the signal handler returns, |
| the system faces the question: what should happen next? |
| |
| POSIX specifies one approach: make the primitive fail right away. |
| The error code for this kind of failure is 'EINTR'. This is flexible, |
| but usually inconvenient. Typically, POSIX applications that use signal |
| handlers must check for 'EINTR' after each library function that can |
| return it, in order to try the call again. Often programmers forget to |
| check, which is a common source of error. |
| |
| The GNU C Library provides a convenient way to retry a call after a |
| temporary failure, with the macro 'TEMP_FAILURE_RETRY': |
| |
| -- Macro: TEMP_FAILURE_RETRY (EXPRESSION) |
| This macro evaluates EXPRESSION once, and examines its value as |
| type 'long int'. If the value equals '-1', that indicates a |
| failure and 'errno' should be set to show what kind of failure. If |
| it fails and reports error code 'EINTR', 'TEMP_FAILURE_RETRY' |
| evaluates it again, and over and over until the result is not a |
| temporary failure. |
| |
| The value returned by 'TEMP_FAILURE_RETRY' is whatever value |
| EXPRESSION produced. |
| |
| BSD avoids 'EINTR' entirely and provides a more convenient approach: |
| to restart the interrupted primitive, instead of making it fail. If you |
| choose this approach, you need not be concerned with 'EINTR'. |
| |
| You can choose either approach with the GNU C Library. If you use |
| 'sigaction' to establish a signal handler, you can specify how that |
| handler should behave. If you specify the 'SA_RESTART' flag, return |
| from that handler will resume a primitive; otherwise, return from that |
| handler will cause 'EINTR'. *Note Flags for Sigaction::. |
| |
| Another way to specify the choice is with the 'siginterrupt' |
| function. *Note BSD Handler::. |
| |
| When you don't specify with 'sigaction' or 'siginterrupt' what a |
| particular handler should do, it uses a default choice. The default |
| choice in the GNU C Library depends on the feature test macros you have |
| defined. If you define '_BSD_SOURCE' or '_GNU_SOURCE' before calling |
| 'signal', the default is to resume primitives; otherwise, the default is |
| to make them fail with 'EINTR'. (The library contains alternate |
| versions of the 'signal' function, and the feature test macros determine |
| which one you really call.) *Note Feature Test Macros::. |
| |
| The description of each primitive affected by this issue lists |
| 'EINTR' among the error codes it can return. |
| |
| There is one situation where resumption never happens no matter which |
| choice you make: when a data-transfer function such as 'read' or 'write' |
| is interrupted by a signal after transferring part of the data. In this |
| case, the function returns the number of bytes already transferred, |
| indicating partial success. |
| |
| This might at first appear to cause unreliable behavior on |
| record-oriented devices (including datagram sockets; *note Datagrams::), |
| where splitting one 'read' or 'write' into two would read or write two |
| records. Actually, there is no problem, because interruption after a |
| partial transfer cannot happen on such devices; they always transfer an |
| entire record in one burst, with no waiting once data transfer has |
| started. |
| |
| |
| File: libc.info, Node: Generating Signals, Next: Blocking Signals, Prev: Interrupted Primitives, Up: Signal Handling |
| |
| 24.6 Generating Signals |
| ======================= |
| |
| Besides signals that are generated as a result of a hardware trap or |
| interrupt, your program can explicitly send signals to itself or to |
| another process. |
| |
| * Menu: |
| |
| * Signaling Yourself:: A process can send a signal to itself. |
| * Signaling Another Process:: Send a signal to another process. |
| * Permission for kill:: Permission for using 'kill'. |
| * Kill Example:: Using 'kill' for Communication. |
| |
| |
| File: libc.info, Node: Signaling Yourself, Next: Signaling Another Process, Up: Generating Signals |
| |
| 24.6.1 Signaling Yourself |
| ------------------------- |
| |
| A process can send itself a signal with the 'raise' function. This |
| function is declared in 'signal.h'. |
| |
| -- Function: int raise (int SIGNUM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'raise' function sends the signal SIGNUM to the calling |
| process. It returns zero if successful and a nonzero value if it |
| fails. About the only reason for failure would be if the value of |
| SIGNUM is invalid. |
| |
| -- Function: int gsignal (int SIGNUM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'gsignal' function does the same thing as 'raise'; it is |
| provided only for compatibility with SVID. |
| |
| One convenient use for 'raise' is to reproduce the default behavior |
| of a signal that you have trapped. For instance, suppose a user of your |
| program types the SUSP character (usually 'C-z'; *note Special |
| Characters::) to send it an interactive stop signal ('SIGTSTP'), and you |
| want to clean up some internal data buffers before stopping. You might |
| set this up like this: |
| |
| #include <signal.h> |
| |
| /* When a stop signal arrives, set the action back to the default |
| and then resend the signal after doing cleanup actions. */ |
| |
| void |
| tstp_handler (int sig) |
| { |
| signal (SIGTSTP, SIG_DFL); |
| /* Do cleanup actions here. */ |
| ... |
| raise (SIGTSTP); |
| } |
| |
| /* When the process is continued again, restore the signal handler. */ |
| |
| void |
| cont_handler (int sig) |
| { |
| signal (SIGCONT, cont_handler); |
| signal (SIGTSTP, tstp_handler); |
| } |
| |
| /* Enable both handlers during program initialization. */ |
| |
| int |
| main (void) |
| { |
| signal (SIGCONT, cont_handler); |
| signal (SIGTSTP, tstp_handler); |
| ... |
| } |
| |
| *Portability note:* 'raise' was invented by the ISO C committee. |
| Older systems may not support it, so using 'kill' may be more portable. |
| *Note Signaling Another Process::. |
| |
| |
| File: libc.info, Node: Signaling Another Process, Next: Permission for kill, Prev: Signaling Yourself, Up: Generating Signals |
| |
| 24.6.2 Signaling Another Process |
| -------------------------------- |
| |
| The 'kill' function can be used to send a signal to another process. In |
| spite of its name, it can be used for a lot of things other than causing |
| a process to terminate. Some examples of situations where you might |
| want to send signals between processes are: |
| |
| * A parent process starts a child to perform a task--perhaps having |
| the child running an infinite loop--and then terminates the child |
| when the task is no longer needed. |
| |
| * A process executes as part of a group, and needs to terminate or |
| notify the other processes in the group when an error or other |
| event occurs. |
| |
| * Two processes need to synchronize while working together. |
| |
| This section assumes that you know a little bit about how processes |
| work. For more information on this subject, see *note Processes::. |
| |
| The 'kill' function is declared in 'signal.h'. |
| |
| -- Function: int kill (pid_t PID, int SIGNUM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'kill' function sends the signal SIGNUM to the process or |
| process group specified by PID. Besides the signals listed in |
| *note Standard Signals::, SIGNUM can also have a value of zero to |
| check the validity of the PID. |
| |
| The PID specifies the process or process group to receive the |
| signal: |
| |
| 'PID > 0' |
| The process whose identifier is PID. |
| |
| 'PID == 0' |
| All processes in the same process group as the sender. |
| |
| 'PID < -1' |
| The process group whose identifier is -PID. |
| |
| 'PID == -1' |
| If the process is privileged, send the signal to all processes |
| except for some special system processes. Otherwise, send the |
| signal to all processes with the same effective user ID. |
| |
| A process can send a signal to itself with a call like |
| 'kill (getpid(), SIGNUM)'. If 'kill' is used by a process to send |
| a signal to itself, and the signal is not blocked, then 'kill' |
| delivers at least one signal (which might be some other pending |
| unblocked signal instead of the signal SIGNUM) to that process |
| before it returns. |
| |
| The return value from 'kill' is zero if the signal can be sent |
| successfully. Otherwise, no signal is sent, and a value of '-1' is |
| returned. If PID specifies sending a signal to several processes, |
| 'kill' succeeds if it can send the signal to at least one of them. |
| There's no way you can tell which of the processes got the signal |
| or whether all of them did. |
| |
| The following 'errno' error conditions are defined for this |
| function: |
| |
| 'EINVAL' |
| The SIGNUM argument is an invalid or unsupported number. |
| |
| 'EPERM' |
| You do not have the privilege to send a signal to the process |
| or any of the processes in the process group named by PID. |
| |
| 'ESRCH' |
| The PID argument does not refer to an existing process or |
| group. |
| |
| -- Function: int killpg (int PGID, int SIGNUM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This is similar to 'kill', but sends signal SIGNUM to the process |
| group PGID. This function is provided for compatibility with BSD; |
| using 'kill' to do this is more portable. |
| |
| As a simple example of 'kill', the call 'kill (getpid (), SIG)' has |
| the same effect as 'raise (SIG)'. |
| |
| |
| File: libc.info, Node: Permission for kill, Next: Kill Example, Prev: Signaling Another Process, Up: Generating Signals |
| |
| 24.6.3 Permission for using 'kill' |
| ---------------------------------- |
| |
| There are restrictions that prevent you from using 'kill' to send |
| signals to any random process. These are intended to prevent antisocial |
| behavior such as arbitrarily killing off processes belonging to another |
| user. In typical use, 'kill' is used to pass signals between parent, |
| child, and sibling processes, and in these situations you normally do |
| have permission to send signals. The only common exception is when you |
| run a setuid program in a child process; if the program changes its real |
| UID as well as its effective UID, you may not have permission to send a |
| signal. The 'su' program does this. |
| |
| Whether a process has permission to send a signal to another process |
| is determined by the user IDs of the two processes. This concept is |
| discussed in detail in *note Process Persona::. |
| |
| Generally, for a process to be able to send a signal to another |
| process, either the sending process must belong to a privileged user |
| (like 'root'), or the real or effective user ID of the sending process |
| must match the real or effective user ID of the receiving process. If |
| the receiving process has changed its effective user ID from the |
| set-user-ID mode bit on its process image file, then the owner of the |
| process image file is used in place of its current effective user ID. In |
| some implementations, a parent process might be able to send signals to |
| a child process even if the user ID's don't match, and other |
| implementations might enforce other restrictions. |
| |
| The 'SIGCONT' signal is a special case. It can be sent if the sender |
| is part of the same session as the receiver, regardless of user IDs. |
| |
| |
| File: libc.info, Node: Kill Example, Prev: Permission for kill, Up: Generating Signals |
| |
| 24.6.4 Using 'kill' for Communication |
| ------------------------------------- |
| |
| Here is a longer example showing how signals can be used for |
| interprocess communication. This is what the 'SIGUSR1' and 'SIGUSR2' |
| signals are provided for. Since these signals are fatal by default, the |
| process that is supposed to receive them must trap them through 'signal' |
| or 'sigaction'. |
| |
| In this example, a parent process forks a child process and then |
| waits for the child to complete its initialization. The child process |
| tells the parent when it is ready by sending it a 'SIGUSR1' signal, |
| using the 'kill' function. |
| |
| |
| #include <signal.h> |
| #include <stdio.h> |
| #include <sys/types.h> |
| #include <unistd.h> |
| |
| /* When a 'SIGUSR1' signal arrives, set this variable. */ |
| volatile sig_atomic_t usr_interrupt = 0; |
| |
| void |
| synch_signal (int sig) |
| { |
| usr_interrupt = 1; |
| } |
| |
| /* The child process executes this function. */ |
| void |
| child_function (void) |
| { |
| /* Perform initialization. */ |
| printf ("I'm here!!! My pid is %d.\n", (int) getpid ()); |
| |
| /* Let parent know you're done. */ |
| kill (getppid (), SIGUSR1); |
| |
| /* Continue with execution. */ |
| puts ("Bye, now...."); |
| exit (0); |
| } |
| |
| int |
| main (void) |
| { |
| struct sigaction usr_action; |
| sigset_t block_mask; |
| pid_t child_id; |
| |
| /* Establish the signal handler. */ |
| sigfillset (&block_mask); |
| usr_action.sa_handler = synch_signal; |
| usr_action.sa_mask = block_mask; |
| usr_action.sa_flags = 0; |
| sigaction (SIGUSR1, &usr_action, NULL); |
| |
| /* Create the child process. */ |
| child_id = fork (); |
| if (child_id == 0) |
| child_function (); /* Does not return. */ |
| |
| /* Busy wait for the child to send a signal. */ |
| while (!usr_interrupt) |
| ; |
| |
| /* Now continue execution. */ |
| puts ("That's all, folks!"); |
| |
| return 0; |
| } |
| |
| This example uses a busy wait, which is bad, because it wastes CPU |
| cycles that other programs could otherwise use. It is better to ask the |
| system to wait until the signal arrives. See the example in *note |
| Waiting for a Signal::. |
| |
| |
| File: libc.info, Node: Blocking Signals, Next: Waiting for a Signal, Prev: Generating Signals, Up: Signal Handling |
| |
| 24.7 Blocking Signals |
| ===================== |
| |
| Blocking a signal means telling the operating system to hold it and |
| deliver it later. Generally, a program does not block signals |
| indefinitely--it might as well ignore them by setting their actions to |
| 'SIG_IGN'. But it is useful to block signals briefly, to prevent them |
| from interrupting sensitive operations. For instance: |
| |
| * You can use the 'sigprocmask' function to block signals while you |
| modify global variables that are also modified by the handlers for |
| these signals. |
| |
| * You can set 'sa_mask' in your 'sigaction' call to block certain |
| signals while a particular signal handler runs. This way, the |
| signal handler can run without being interrupted itself by signals. |
| |
| * Menu: |
| |
| * Why Block:: The purpose of blocking signals. |
| * Signal Sets:: How to specify which signals to |
| block. |
| * Process Signal Mask:: Blocking delivery of signals to your |
| process during normal execution. |
| * Testing for Delivery:: Blocking to Test for Delivery of |
| a Signal. |
| * Blocking for Handler:: Blocking additional signals while a |
| handler is being run. |
| * Checking for Pending Signals:: Checking for Pending Signals |
| * Remembering a Signal:: How you can get almost the same |
| effect as blocking a signal, by |
| handling it and setting a flag |
| to be tested later. |
| |
| |
| File: libc.info, Node: Why Block, Next: Signal Sets, Up: Blocking Signals |
| |
| 24.7.1 Why Blocking Signals is Useful |
| ------------------------------------- |
| |
| Temporary blocking of signals with 'sigprocmask' gives you a way to |
| prevent interrupts during critical parts of your code. If signals |
| arrive in that part of the program, they are delivered later, after you |
| unblock them. |
| |
| One example where this is useful is for sharing data between a signal |
| handler and the rest of the program. If the type of the data is not |
| 'sig_atomic_t' (*note Atomic Data Access::), then the signal handler |
| could run when the rest of the program has only half finished reading or |
| writing the data. This would lead to confusing consequences. |
| |
| To make the program reliable, you can prevent the signal handler from |
| running while the rest of the program is examining or modifying that |
| data--by blocking the appropriate signal around the parts of the program |
| that touch the data. |
| |
| Blocking signals is also necessary when you want to perform a certain |
| action only if a signal has not arrived. Suppose that the handler for |
| the signal sets a flag of type 'sig_atomic_t'; you would like to test |
| the flag and perform the action if the flag is not set. This is |
| unreliable. Suppose the signal is delivered immediately after you test |
| the flag, but before the consequent action: then the program will |
| perform the action even though the signal has arrived. |
| |
| The only way to test reliably for whether a signal has yet arrived is |
| to test while the signal is blocked. |
| |
| |
| File: libc.info, Node: Signal Sets, Next: Process Signal Mask, Prev: Why Block, Up: Blocking Signals |
| |
| 24.7.2 Signal Sets |
| ------------------ |
| |
| All of the signal blocking functions use a data structure called a |
| "signal set" to specify what signals are affected. Thus, every activity |
| involves two stages: creating the signal set, and then passing it as an |
| argument to a library function. |
| |
| These facilities are declared in the header file 'signal.h'. |
| |
| -- Data Type: sigset_t |
| The 'sigset_t' data type is used to represent a signal set. |
| Internally, it may be implemented as either an integer or structure |
| type. |
| |
| For portability, use only the functions described in this section |
| to initialize, change, and retrieve information from 'sigset_t' |
| objects--don't try to manipulate them directly. |
| |
| There are two ways to initialize a signal set. You can initially |
| specify it to be empty with 'sigemptyset' and then add specified signals |
| individually. Or you can specify it to be full with 'sigfillset' and |
| then delete specified signals individually. |
| |
| You must always initialize the signal set with one of these two |
| functions before using it in any other way. Don't try to set all the |
| signals explicitly because the 'sigset_t' object might include some |
| other information (like a version field) that needs to be initialized as |
| well. (In addition, it's not wise to put into your program an |
| assumption that the system has no signals aside from the ones you know |
| about.) |
| |
| -- Function: int sigemptyset (sigset_t *SET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function initializes the signal set SET to exclude all of the |
| defined signals. It always returns '0'. |
| |
| -- Function: int sigfillset (sigset_t *SET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function initializes the signal set SET to include all of the |
| defined signals. Again, the return value is '0'. |
| |
| -- Function: int sigaddset (sigset_t *SET, int SIGNUM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function adds the signal SIGNUM to the signal set SET. All |
| 'sigaddset' does is modify SET; it does not block or unblock any |
| signals. |
| |
| The return value is '0' on success and '-1' on failure. The |
| following 'errno' error condition is defined for this function: |
| |
| 'EINVAL' |
| The SIGNUM argument doesn't specify a valid signal. |
| |
| -- Function: int sigdelset (sigset_t *SET, int SIGNUM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function removes the signal SIGNUM from the signal set SET. |
| All 'sigdelset' does is modify SET; it does not block or unblock |
| any signals. The return value and error conditions are the same as |
| for 'sigaddset'. |
| |
| Finally, there is a function to test what signals are in a signal |
| set: |
| |
| -- Function: int sigismember (const sigset_t *SET, int SIGNUM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'sigismember' function tests whether the signal SIGNUM is a |
| member of the signal set SET. It returns '1' if the signal is in |
| the set, '0' if not, and '-1' if there is an error. |
| |
| The following 'errno' error condition is defined for this function: |
| |
| 'EINVAL' |
| The SIGNUM argument doesn't specify a valid signal. |
| |
| |
| File: libc.info, Node: Process Signal Mask, Next: Testing for Delivery, Prev: Signal Sets, Up: Blocking Signals |
| |
| 24.7.3 Process Signal Mask |
| -------------------------- |
| |
| The collection of signals that are currently blocked is called the |
| "signal mask". Each process has its own signal mask. When you create a |
| new process (*note Creating a Process::), it inherits its parent's mask. |
| You can block or unblock signals with total flexibility by modifying the |
| signal mask. |
| |
| The prototype for the 'sigprocmask' function is in 'signal.h'. |
| |
| Note that you must not use 'sigprocmask' in multi-threaded processes, |
| because each thread has its own signal mask and there is no single |
| process signal mask. According to POSIX, the behavior of 'sigprocmask' |
| in a multi-threaded process is "unspecified". Instead, use |
| 'pthread_sigmask'. |
| |
| -- Function: int sigprocmask (int HOW, const sigset_t *restrict SET, |
| sigset_t *restrict OLDSET) |
| Preliminary: | MT-Unsafe race:sigprocmask/bsd(SIG_UNBLOCK) | |
| AS-Unsafe lock/hurd | AC-Unsafe lock/hurd | *Note POSIX Safety |
| Concepts::. |
| |
| The 'sigprocmask' function is used to examine or change the calling |
| process's signal mask. The HOW argument determines how the signal |
| mask is changed, and must be one of the following values: |
| |
| 'SIG_BLOCK' |
| Block the signals in 'set'--add them to the existing mask. In |
| other words, the new mask is the union of the existing mask |
| and SET. |
| |
| 'SIG_UNBLOCK' |
| Unblock the signals in SET--remove them from the existing |
| mask. |
| |
| 'SIG_SETMASK' |
| Use SET for the mask; ignore the previous value of the mask. |
| |
| The last argument, OLDSET, is used to return information about the |
| old process signal mask. If you just want to change the mask |
| without looking at it, pass a null pointer as the OLDSET argument. |
| Similarly, if you want to know what's in the mask without changing |
| it, pass a null pointer for SET (in this case the HOW argument is |
| not significant). The OLDSET argument is often used to remember |
| the previous signal mask in order to restore it later. (Since the |
| signal mask is inherited over 'fork' and 'exec' calls, you can't |
| predict what its contents are when your program starts running.) |
| |
| If invoking 'sigprocmask' causes any pending signals to be |
| unblocked, at least one of those signals is delivered to the |
| process before 'sigprocmask' returns. The order in which pending |
| signals are delivered is not specified, but you can control the |
| order explicitly by making multiple 'sigprocmask' calls to unblock |
| various signals one at a time. |
| |
| The 'sigprocmask' function returns '0' if successful, and '-1' to |
| indicate an error. The following 'errno' error conditions are |
| defined for this function: |
| |
| 'EINVAL' |
| The HOW argument is invalid. |
| |
| You can't block the 'SIGKILL' and 'SIGSTOP' signals, but if the |
| signal set includes these, 'sigprocmask' just ignores them instead |
| of returning an error status. |
| |
| Remember, too, that blocking program error signals such as 'SIGFPE' |
| leads to undesirable results for signals generated by an actual |
| program error (as opposed to signals sent with 'raise' or 'kill'). |
| This is because your program may be too broken to be able to |
| continue executing to a point where the signal is unblocked again. |
| *Note Program Error Signals::. |
| |
| |
| File: libc.info, Node: Testing for Delivery, Next: Blocking for Handler, Prev: Process Signal Mask, Up: Blocking Signals |
| |
| 24.7.4 Blocking to Test for Delivery of a Signal |
| ------------------------------------------------ |
| |
| Now for a simple example. Suppose you establish a handler for 'SIGALRM' |
| signals that sets a flag whenever a signal arrives, and your main |
| program checks this flag from time to time and then resets it. You can |
| prevent additional 'SIGALRM' signals from arriving in the meantime by |
| wrapping the critical part of the code with calls to 'sigprocmask', like |
| this: |
| |
| /* This variable is set by the SIGALRM signal handler. */ |
| volatile sig_atomic_t flag = 0; |
| |
| int |
| main (void) |
| { |
| sigset_t block_alarm; |
| |
| ... |
| |
| /* Initialize the signal mask. */ |
| sigemptyset (&block_alarm); |
| sigaddset (&block_alarm, SIGALRM); |
| |
| while (1) |
| { |
| /* Check if a signal has arrived; if so, reset the flag. */ |
| sigprocmask (SIG_BLOCK, &block_alarm, NULL); |
| if (flag) |
| { |
| ACTIONS-IF-NOT-ARRIVED |
| flag = 0; |
| } |
| sigprocmask (SIG_UNBLOCK, &block_alarm, NULL); |
| |
| ... |
| } |
| } |
| |
| |
| File: libc.info, Node: Blocking for Handler, Next: Checking for Pending Signals, Prev: Testing for Delivery, Up: Blocking Signals |
| |
| 24.7.5 Blocking Signals for a Handler |
| ------------------------------------- |
| |
| When a signal handler is invoked, you usually want it to be able to |
| finish without being interrupted by another signal. From the moment the |
| handler starts until the moment it finishes, you must block signals that |
| might confuse it or corrupt its data. |
| |
| When a handler function is invoked on a signal, that signal is |
| automatically blocked (in addition to any other signals that are already |
| in the process's signal mask) during the time the handler is running. |
| If you set up a handler for 'SIGTSTP', for instance, then the arrival of |
| that signal forces further 'SIGTSTP' signals to wait during the |
| execution of the handler. |
| |
| However, by default, other kinds of signals are not blocked; they can |
| arrive during handler execution. |
| |
| The reliable way to block other kinds of signals during the execution |
| of the handler is to use the 'sa_mask' member of the 'sigaction' |
| structure. |
| |
| Here is an example: |
| |
| #include <signal.h> |
| #include <stddef.h> |
| |
| void catch_stop (); |
| |
| void |
| install_handler (void) |
| { |
| struct sigaction setup_action; |
| sigset_t block_mask; |
| |
| sigemptyset (&block_mask); |
| /* Block other terminal-generated signals while handler runs. */ |
| sigaddset (&block_mask, SIGINT); |
| sigaddset (&block_mask, SIGQUIT); |
| setup_action.sa_handler = catch_stop; |
| setup_action.sa_mask = block_mask; |
| setup_action.sa_flags = 0; |
| sigaction (SIGTSTP, &setup_action, NULL); |
| } |
| |
| This is more reliable than blocking the other signals explicitly in |
| the code for the handler. If you block signals explicitly in the |
| handler, you can't avoid at least a short interval at the beginning of |
| the handler where they are not yet blocked. |
| |
| You cannot remove signals from the process's current mask using this |
| mechanism. However, you can make calls to 'sigprocmask' within your |
| handler to block or unblock signals as you wish. |
| |
| In any case, when the handler returns, the system restores the mask |
| that was in place before the handler was entered. If any signals that |
| become unblocked by this restoration are pending, the process will |
| receive those signals immediately, before returning to the code that was |
| interrupted. |
| |
| |
| File: libc.info, Node: Checking for Pending Signals, Next: Remembering a Signal, Prev: Blocking for Handler, Up: Blocking Signals |
| |
| 24.7.6 Checking for Pending Signals |
| ----------------------------------- |
| |
| You can find out which signals are pending at any time by calling |
| 'sigpending'. This function is declared in 'signal.h'. |
| |
| -- Function: int sigpending (sigset_t *SET) |
| Preliminary: | MT-Safe | AS-Unsafe lock/hurd | AC-Unsafe lock/hurd |
| | *Note POSIX Safety Concepts::. |
| |
| The 'sigpending' function stores information about pending signals |
| in SET. If there is a pending signal that is blocked from |
| delivery, then that signal is a member of the returned set. (You |
| can test whether a particular signal is a member of this set using |
| 'sigismember'; see *note Signal Sets::.) |
| |
| The return value is '0' if successful, and '-1' on failure. |
| |
| Testing whether a signal is pending is not often useful. Testing |
| when that signal is not blocked is almost certainly bad design. |
| |
| Here is an example. |
| |
| #include <signal.h> |
| #include <stddef.h> |
| |
| sigset_t base_mask, waiting_mask; |
| |
| sigemptyset (&base_mask); |
| sigaddset (&base_mask, SIGINT); |
| sigaddset (&base_mask, SIGTSTP); |
| |
| /* Block user interrupts while doing other processing. */ |
| sigprocmask (SIG_SETMASK, &base_mask, NULL); |
| ... |
| |
| /* After a while, check to see whether any signals are pending. */ |
| sigpending (&waiting_mask); |
| if (sigismember (&waiting_mask, SIGINT)) { |
| /* User has tried to kill the process. */ |
| } |
| else if (sigismember (&waiting_mask, SIGTSTP)) { |
| /* User has tried to stop the process. */ |
| } |
| |
| Remember that if there is a particular signal pending for your |
| process, additional signals of that same type that arrive in the |
| meantime might be discarded. For example, if a 'SIGINT' signal is |
| pending when another 'SIGINT' signal arrives, your program will probably |
| only see one of them when you unblock this signal. |
| |
| *Portability Note:* The 'sigpending' function is new in POSIX.1. |
| Older systems have no equivalent facility. |
| |
| |
| File: libc.info, Node: Remembering a Signal, Prev: Checking for Pending Signals, Up: Blocking Signals |
| |
| 24.7.7 Remembering a Signal to Act On Later |
| ------------------------------------------- |
| |
| Instead of blocking a signal using the library facilities, you can get |
| almost the same results by making the handler set a flag to be tested |
| later, when you "unblock". Here is an example: |
| |
| /* If this flag is nonzero, don't handle the signal right away. */ |
| volatile sig_atomic_t signal_pending; |
| |
| /* This is nonzero if a signal arrived and was not handled. */ |
| volatile sig_atomic_t defer_signal; |
| |
| void |
| handler (int signum) |
| { |
| if (defer_signal) |
| signal_pending = signum; |
| else |
| ... /* "Really" handle the signal. */ |
| } |
| |
| ... |
| |
| void |
| update_mumble (int frob) |
| { |
| /* Prevent signals from having immediate effect. */ |
| defer_signal++; |
| /* Now update 'mumble', without worrying about interruption. */ |
| mumble.a = 1; |
| mumble.b = hack (); |
| mumble.c = frob; |
| /* We have updated 'mumble'. Handle any signal that came in. */ |
| defer_signal--; |
| if (defer_signal == 0 && signal_pending != 0) |
| raise (signal_pending); |
| } |
| |
| Note how the particular signal that arrives is stored in |
| 'signal_pending'. That way, we can handle several types of inconvenient |
| signals with the same mechanism. |
| |
| We increment and decrement 'defer_signal' so that nested critical |
| sections will work properly; thus, if 'update_mumble' were called with |
| 'signal_pending' already nonzero, signals would be deferred not only |
| within 'update_mumble', but also within the caller. This is also why we |
| do not check 'signal_pending' if 'defer_signal' is still nonzero. |
| |
| The incrementing and decrementing of 'defer_signal' each require more |
| than one instruction; it is possible for a signal to happen in the |
| middle. But that does not cause any problem. If the signal happens |
| early enough to see the value from before the increment or decrement, |
| that is equivalent to a signal which came before the beginning of the |
| increment or decrement, which is a case that works properly. |
| |
| It is absolutely vital to decrement 'defer_signal' before testing |
| 'signal_pending', because this avoids a subtle bug. If we did these |
| things in the other order, like this, |
| |
| if (defer_signal == 1 && signal_pending != 0) |
| raise (signal_pending); |
| defer_signal--; |
| |
| then a signal arriving in between the 'if' statement and the decrement |
| would be effectively "lost" for an indefinite amount of time. The |
| handler would merely set 'defer_signal', but the program having already |
| tested this variable, it would not test the variable again. |
| |
| Bugs like these are called "timing errors". They are especially bad |
| because they happen only rarely and are nearly impossible to reproduce. |
| You can't expect to find them with a debugger as you would find a |
| reproducible bug. So it is worth being especially careful to avoid |
| them. |
| |
| (You would not be tempted to write the code in this order, given the |
| use of 'defer_signal' as a counter which must be tested along with |
| 'signal_pending'. After all, testing for zero is cleaner than testing |
| for one. But if you did not use 'defer_signal' as a counter, and gave |
| it values of zero and one only, then either order might seem equally |
| simple. This is a further advantage of using a counter for |
| 'defer_signal': it will reduce the chance you will write the code in the |
| wrong order and create a subtle bug.) |
| |
| |
| File: libc.info, Node: Waiting for a Signal, Next: Signal Stack, Prev: Blocking Signals, Up: Signal Handling |
| |
| 24.8 Waiting for a Signal |
| ========================= |
| |
| If your program is driven by external events, or uses signals for |
| synchronization, then when it has nothing to do it should probably wait |
| until a signal arrives. |
| |
| * Menu: |
| |
| * Using Pause:: The simple way, using 'pause'. |
| * Pause Problems:: Why the simple way is often not very good. |
| * Sigsuspend:: Reliably waiting for a specific signal. |
| |
| |
| File: libc.info, Node: Using Pause, Next: Pause Problems, Up: Waiting for a Signal |
| |
| 24.8.1 Using 'pause' |
| -------------------- |
| |
| The simple way to wait until a signal arrives is to call 'pause'. |
| Please read about its disadvantages, in the following section, before |
| you use it. |
| |
| -- Function: int pause (void) |
| Preliminary: | MT-Unsafe race:sigprocmask/!bsd!linux | AS-Unsafe |
| lock/hurd | AC-Unsafe lock/hurd | *Note POSIX Safety Concepts::. |
| |
| The 'pause' function suspends program execution until a signal |
| arrives whose action is either to execute a handler function, or to |
| terminate the process. |
| |
| If the signal causes a handler function to be executed, then |
| 'pause' returns. This is considered an unsuccessful return (since |
| "successful" behavior would be to suspend the program forever), so |
| the return value is '-1'. Even if you specify that other |
| primitives should resume when a system handler returns (*note |
| Interrupted Primitives::), this has no effect on 'pause'; it always |
| fails when a signal is handled. |
| |
| The following 'errno' error conditions are defined for this |
| function: |
| |
| 'EINTR' |
| The function was interrupted by delivery of a signal. |
| |
| If the signal causes program termination, 'pause' doesn't return |
| (obviously). |
| |
| This function is a cancellation point in multithreaded programs. |
| This is a problem if the thread allocates some resources (like |
| memory, file descriptors, semaphores or whatever) at the time |
| 'pause' is called. If the thread gets cancelled these resources |
| stay allocated until the program ends. To avoid this calls to |
| 'pause' should be protected using cancellation handlers. |
| |
| The 'pause' function is declared in 'unistd.h'. |
| |
| |
| File: libc.info, Node: Pause Problems, Next: Sigsuspend, Prev: Using Pause, Up: Waiting for a Signal |
| |
| 24.8.2 Problems with 'pause' |
| ---------------------------- |
| |
| The simplicity of 'pause' can conceal serious timing errors that can |
| make a program hang mysteriously. |
| |
| It is safe to use 'pause' if the real work of your program is done by |
| the signal handlers themselves, and the "main program" does nothing but |
| call 'pause'. Each time a signal is delivered, the handler will do the |
| next batch of work that is to be done, and then return, so that the main |
| loop of the program can call 'pause' again. |
| |
| You can't safely use 'pause' to wait until one more signal arrives, |
| and then resume real work. Even if you arrange for the signal handler |
| to cooperate by setting a flag, you still can't use 'pause' reliably. |
| Here is an example of this problem: |
| |
| /* 'usr_interrupt' is set by the signal handler. */ |
| if (!usr_interrupt) |
| pause (); |
| |
| /* Do work once the signal arrives. */ |
| ... |
| |
| This has a bug: the signal could arrive after the variable |
| 'usr_interrupt' is checked, but before the call to 'pause'. If no |
| further signals arrive, the process would never wake up again. |
| |
| You can put an upper limit on the excess waiting by using 'sleep' in |
| a loop, instead of using 'pause'. (*Note Sleeping::, for more about |
| 'sleep'.) Here is what this looks like: |
| |
| /* 'usr_interrupt' is set by the signal handler. |
| while (!usr_interrupt) |
| sleep (1); |
| |
| /* Do work once the signal arrives. */ |
| ... |
| |
| For some purposes, that is good enough. But with a little more |
| complexity, you can wait reliably until a particular signal handler is |
| run, using 'sigsuspend'. *Note Sigsuspend::. |
| |
| |
| File: libc.info, Node: Sigsuspend, Prev: Pause Problems, Up: Waiting for a Signal |
| |
| 24.8.3 Using 'sigsuspend' |
| ------------------------- |
| |
| The clean and reliable way to wait for a signal to arrive is to block it |
| and then use 'sigsuspend'. By using 'sigsuspend' in a loop, you can |
| wait for certain kinds of signals, while letting other kinds of signals |
| be handled by their handlers. |
| |
| -- Function: int sigsuspend (const sigset_t *SET) |
| Preliminary: | MT-Unsafe race:sigprocmask/!bsd!linux | AS-Unsafe |
| lock/hurd | AC-Unsafe lock/hurd | *Note POSIX Safety Concepts::. |
| |
| This function replaces the process's signal mask with SET and then |
| suspends the process until a signal is delivered whose action is |
| either to terminate the process or invoke a signal handling |
| function. In other words, the program is effectively suspended |
| until one of the signals that is not a member of SET arrives. |
| |
| If the process is woken up by delivery of a signal that invokes a |
| handler function, and the handler function returns, then |
| 'sigsuspend' also returns. |
| |
| The mask remains SET only as long as 'sigsuspend' is waiting. The |
| function 'sigsuspend' always restores the previous signal mask when |
| it returns. |
| |
| The return value and error conditions are the same as for 'pause'. |
| |
| With 'sigsuspend', you can replace the 'pause' or 'sleep' loop in the |
| previous section with something completely reliable: |
| |
| sigset_t mask, oldmask; |
| |
| ... |
| |
| /* Set up the mask of signals to temporarily block. */ |
| sigemptyset (&mask); |
| sigaddset (&mask, SIGUSR1); |
| |
| ... |
| |
| /* Wait for a signal to arrive. */ |
| sigprocmask (SIG_BLOCK, &mask, &oldmask); |
| while (!usr_interrupt) |
| sigsuspend (&oldmask); |
| sigprocmask (SIG_UNBLOCK, &mask, NULL); |
| |
| This last piece of code is a little tricky. The key point to |
| remember here is that when 'sigsuspend' returns, it resets the process's |
| signal mask to the original value, the value from before the call to |
| 'sigsuspend'--in this case, the 'SIGUSR1' signal is once again blocked. |
| The second call to 'sigprocmask' is necessary to explicitly unblock this |
| signal. |
| |
| One other point: you may be wondering why the 'while' loop is |
| necessary at all, since the program is apparently only waiting for one |
| 'SIGUSR1' signal. The answer is that the mask passed to 'sigsuspend' |
| permits the process to be woken up by the delivery of other kinds of |
| signals, as well--for example, job control signals. If the process is |
| woken up by a signal that doesn't set 'usr_interrupt', it just suspends |
| itself again until the "right" kind of signal eventually arrives. |
| |
| This technique takes a few more lines of preparation, but that is |
| needed just once for each kind of wait criterion you want to use. The |
| code that actually waits is just four lines. |
| |
| |
| File: libc.info, Node: Signal Stack, Next: BSD Signal Handling, Prev: Waiting for a Signal, Up: Signal Handling |
| |
| 24.9 Using a Separate Signal Stack |
| ================================== |
| |
| A signal stack is a special area of memory to be used as the execution |
| stack during signal handlers. It should be fairly large, to avoid any |
| danger that it will overflow in turn; the macro 'SIGSTKSZ' is defined to |
| a canonical size for signal stacks. You can use 'malloc' to allocate |
| the space for the stack. Then call 'sigaltstack' or 'sigstack' to tell |
| the system to use that space for the signal stack. |
| |
| You don't need to write signal handlers differently in order to use a |
| signal stack. Switching from one stack to the other happens |
| automatically. (Some non-GNU debuggers on some machines may get |
| confused if you examine a stack trace while a handler that uses the |
| signal stack is running.) |
| |
| There are two interfaces for telling the system to use a separate |
| signal stack. 'sigstack' is the older interface, which comes from 4.2 |
| BSD. 'sigaltstack' is the newer interface, and comes from 4.4 BSD. The |
| 'sigaltstack' interface has the advantage that it does not require your |
| program to know which direction the stack grows, which depends on the |
| specific machine and operating system. |
| |
| -- Data Type: stack_t |
| This structure describes a signal stack. It contains the following |
| members: |
| |
| 'void *ss_sp' |
| This points to the base of the signal stack. |
| |
| 'size_t ss_size' |
| This is the size (in bytes) of the signal stack which 'ss_sp' |
| points to. You should set this to however much space you |
| allocated for the stack. |
| |
| There are two macros defined in 'signal.h' that you should use |
| in calculating this size: |
| |
| 'SIGSTKSZ' |
| This is the canonical size for a signal stack. It is |
| judged to be sufficient for normal uses. |
| |
| 'MINSIGSTKSZ' |
| This is the amount of signal stack space the operating |
| system needs just to implement signal delivery. The size |
| of a signal stack *must* be greater than this. |
| |
| For most cases, just using 'SIGSTKSZ' for 'ss_size' is |
| sufficient. But if you know how much stack space your |
| program's signal handlers will need, you may want to use |
| a different size. In this case, you should allocate |
| 'MINSIGSTKSZ' additional bytes for the signal stack and |
| increase 'ss_size' accordingly. |
| |
| 'int ss_flags' |
| This field contains the bitwise OR of these flags: |
| |
| 'SS_DISABLE' |
| This tells the system that it should not use the signal |
| stack. |
| |
| 'SS_ONSTACK' |
| This is set by the system, and indicates that the signal |
| stack is currently in use. If this bit is not set, then |
| signals will be delivered on the normal user stack. |
| |
| -- Function: int sigaltstack (const stack_t *restrict STACK, stack_t |
| *restrict OLDSTACK) |
| Preliminary: | MT-Safe | AS-Unsafe lock/hurd | AC-Unsafe lock/hurd |
| | *Note POSIX Safety Concepts::. |
| |
| The 'sigaltstack' function specifies an alternate stack for use |
| during signal handling. When a signal is received by the process |
| and its action indicates that the signal stack is used, the system |
| arranges a switch to the currently installed signal stack while the |
| handler for that signal is executed. |
| |
| If OLDSTACK is not a null pointer, information about the currently |
| installed signal stack is returned in the location it points to. |
| If STACK is not a null pointer, then this is installed as the new |
| stack for use by signal handlers. |
| |
| The return value is '0' on success and '-1' on failure. If |
| 'sigaltstack' fails, it sets 'errno' to one of these values: |
| |
| 'EINVAL' |
| You tried to disable a stack that was in fact currently in |
| use. |
| |
| 'ENOMEM' |
| The size of the alternate stack was too small. It must be |
| greater than 'MINSIGSTKSZ'. |
| |
| Here is the older 'sigstack' interface. You should use 'sigaltstack' |
| instead on systems that have it. |
| |
| -- Data Type: struct sigstack |
| This structure describes a signal stack. It contains the following |
| members: |
| |
| 'void *ss_sp' |
| This is the stack pointer. If the stack grows downwards on |
| your machine, this should point to the top of the area you |
| allocated. If the stack grows upwards, it should point to the |
| bottom. |
| |
| 'int ss_onstack' |
| This field is true if the process is currently using this |
| stack. |
| |
| -- Function: int sigstack (struct sigstack *STACK, struct sigstack |
| *OLDSTACK) |
| Preliminary: | MT-Safe | AS-Unsafe lock/hurd | AC-Unsafe lock/hurd |
| | *Note POSIX Safety Concepts::. |
| |
| The 'sigstack' function specifies an alternate stack for use during |
| signal handling. When a signal is received by the process and its |
| action indicates that the signal stack is used, the system arranges |
| a switch to the currently installed signal stack while the handler |
| for that signal is executed. |
| |
| If OLDSTACK is not a null pointer, information about the currently |
| installed signal stack is returned in the location it points to. |
| If STACK is not a null pointer, then this is installed as the new |
| stack for use by signal handlers. |
| |
| The return value is '0' on success and '-1' on failure. |
| |
| |
| File: libc.info, Node: BSD Signal Handling, Prev: Signal Stack, Up: Signal Handling |
| |
| 24.10 BSD Signal Handling |
| ========================= |
| |
| This section describes alternative signal handling functions derived |
| from BSD Unix. These facilities were an advance, in their time; today, |
| they are mostly obsolete, and supported mainly for compatibility with |
| BSD Unix. |
| |
| There are many similarities between the BSD and POSIX signal handling |
| facilities, because the POSIX facilities were inspired by the BSD |
| facilities. Besides having different names for all the functions to |
| avoid conflicts, the main differences between the two are: |
| |
| * BSD Unix represents signal masks as an 'int' bit mask, rather than |
| as a 'sigset_t' object. |
| |
| * The BSD facilities use a different default for whether an |
| interrupted primitive should fail or resume. The POSIX facilities |
| make system calls fail unless you specify that they should resume. |
| With the BSD facility, the default is to make system calls resume |
| unless you say they should fail. *Note Interrupted Primitives::. |
| |
| The BSD facilities are declared in 'signal.h'. |
| |
| * Menu: |
| |
| * BSD Handler:: BSD Function to Establish a Handler. |
| * Blocking in BSD:: BSD Functions for Blocking Signals. |
| |
| |
| File: libc.info, Node: BSD Handler, Next: Blocking in BSD, Up: BSD Signal Handling |
| |
| 24.10.1 BSD Function to Establish a Handler |
| ------------------------------------------- |
| |
| -- Data Type: struct sigvec |
| This data type is the BSD equivalent of 'struct sigaction' (*note |
| Advanced Signal Handling::); it is used to specify signal actions |
| to the 'sigvec' function. It contains the following members: |
| |
| 'sighandler_t sv_handler' |
| This is the handler function. |
| |
| 'int sv_mask' |
| This is the mask of additional signals to be blocked while the |
| handler function is being called. |
| |
| 'int sv_flags' |
| This is a bit mask used to specify various flags which affect |
| the behavior of the signal. You can also refer to this field |
| as 'sv_onstack'. |
| |
| These symbolic constants can be used to provide values for the |
| 'sv_flags' field of a 'sigvec' structure. This field is a bit mask |
| value, so you bitwise-OR the flags of interest to you together. |
| |
| -- Macro: int SV_ONSTACK |
| If this bit is set in the 'sv_flags' field of a 'sigvec' structure, |
| it means to use the signal stack when delivering the signal. |
| |
| -- Macro: int SV_INTERRUPT |
| If this bit is set in the 'sv_flags' field of a 'sigvec' structure, |
| it means that system calls interrupted by this kind of signal |
| should not be restarted if the handler returns; instead, the system |
| calls should return with a 'EINTR' error status. *Note Interrupted |
| Primitives::. |
| |
| -- Macro: int SV_RESETHAND |
| If this bit is set in the 'sv_flags' field of a 'sigvec' structure, |
| it means to reset the action for the signal back to 'SIG_DFL' when |
| the signal is received. |
| |
| -- Function: int sigvec (int SIGNUM, const struct sigvec *ACTION, |
| struct sigvec *OLD-ACTION) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is the equivalent of 'sigaction' (*note Advanced |
| Signal Handling::); it installs the action ACTION for the signal |
| SIGNUM, returning information about the previous action in effect |
| for that signal in OLD-ACTION. |
| |
| -- Function: int siginterrupt (int SIGNUM, int FAILFLAG) |
| Preliminary: | MT-Unsafe const:sigintr | AS-Unsafe | AC-Unsafe |
| corrupt | *Note POSIX Safety Concepts::. |
| |
| This function specifies which approach to use when certain |
| primitives are interrupted by handling signal SIGNUM. If FAILFLAG |
| is false, signal SIGNUM restarts primitives. If FAILFLAG is true, |
| handling SIGNUM causes these primitives to fail with error code |
| 'EINTR'. *Note Interrupted Primitives::. |
| |
| |
| File: libc.info, Node: Blocking in BSD, Prev: BSD Handler, Up: BSD Signal Handling |
| |
| 24.10.2 BSD Functions for Blocking Signals |
| ------------------------------------------ |
| |
| -- Macro: int sigmask (int SIGNUM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro returns a signal mask that has the bit for signal SIGNUM |
| set. You can bitwise-OR the results of several calls to 'sigmask' |
| together to specify more than one signal. For example, |
| |
| (sigmask (SIGTSTP) | sigmask (SIGSTOP) |
| | sigmask (SIGTTIN) | sigmask (SIGTTOU)) |
| |
| specifies a mask that includes all the job-control stop signals. |
| |
| -- Function: int sigblock (int MASK) |
| Preliminary: | MT-Safe | AS-Unsafe lock/hurd | AC-Unsafe lock/hurd |
| | *Note POSIX Safety Concepts::. |
| |
| This function is equivalent to 'sigprocmask' (*note Process Signal |
| Mask::) with a HOW argument of 'SIG_BLOCK': it adds the signals |
| specified by MASK to the calling process's set of blocked signals. |
| The return value is the previous set of blocked signals. |
| |
| -- Function: int sigsetmask (int MASK) |
| Preliminary: | MT-Safe | AS-Unsafe lock/hurd | AC-Unsafe lock/hurd |
| | *Note POSIX Safety Concepts::. |
| |
| This function equivalent to 'sigprocmask' (*note Process Signal |
| Mask::) with a HOW argument of 'SIG_SETMASK': it sets the calling |
| process's signal mask to MASK. The return value is the previous |
| set of blocked signals. |
| |
| -- Function: int sigpause (int MASK) |
| Preliminary: | MT-Unsafe race:sigprocmask/!bsd!linux | AS-Unsafe |
| lock/hurd | AC-Unsafe lock/hurd | *Note POSIX Safety Concepts::. |
| |
| This function is the equivalent of 'sigsuspend' (*note Waiting for |
| a Signal::): it sets the calling process's signal mask to MASK, and |
| waits for a signal to arrive. On return the previous set of |
| blocked signals is restored. |
| |
| |
| File: libc.info, Node: Program Basics, Next: Processes, Prev: Signal Handling, Up: Top |
| |
| 25 The Basic Program/System Interface |
| ************************************* |
| |
| "Processes" are the primitive units for allocation of system resources. |
| Each process has its own address space and (usually) one thread of |
| control. A process executes a program; you can have multiple processes |
| executing the same program, but each process has its own copy of the |
| program within its own address space and executes it independently of |
| the other copies. Though it may have multiple threads of control within |
| the same program and a program may be composed of multiple logically |
| separate modules, a process always executes exactly one program. |
| |
| Note that we are using a specific definition of "program" for the |
| purposes of this manual, which corresponds to a common definition in the |
| context of Unix system. In popular usage, "program" enjoys a much |
| broader definition; it can refer for example to a system's kernel, an |
| editor macro, a complex package of software, or a discrete section of |
| code executing within a process. |
| |
| Writing the program is what this manual is all about. This chapter |
| explains the most basic interface between your program and the system |
| that runs, or calls, it. This includes passing of parameters (arguments |
| and environment) from the system, requesting basic services from the |
| system, and telling the system the program is done. |
| |
| A program starts another program with the 'exec' family of system |
| calls. This chapter looks at program startup from the execee's point of |
| view. To see the event from the execor's point of view, see *note |
| Executing a File::. |
| |
| * Menu: |
| |
| * Program Arguments:: Parsing your program's command-line arguments |
| * Environment Variables:: Less direct parameters affecting your program |
| * Auxiliary Vector:: Least direct parameters affecting your program |
| * System Calls:: Requesting service from the system |
| * Program Termination:: Telling the system you're done; return status |
| |
| |
| File: libc.info, Node: Program Arguments, Next: Environment Variables, Up: Program Basics |
| |
| 25.1 Program Arguments |
| ====================== |
| |
| The system starts a C program by calling the function 'main'. It is up |
| to you to write a function named 'main'--otherwise, you won't even be |
| able to link your program without errors. |
| |
| In ISO C you can define 'main' either to take no arguments, or to |
| take two arguments that represent the command line arguments to the |
| program, like this: |
| |
| int main (int ARGC, char *ARGV[]) |
| |
| The command line arguments are the whitespace-separated tokens given |
| in the shell command used to invoke the program; thus, in 'cat foo bar', |
| the arguments are 'foo' and 'bar'. The only way a program can look at |
| its command line arguments is via the arguments of 'main'. If 'main' |
| doesn't take arguments, then you cannot get at the command line. |
| |
| The value of the ARGC argument is the number of command line |
| arguments. The ARGV argument is a vector of C strings; its elements are |
| the individual command line argument strings. The file name of the |
| program being run is also included in the vector as the first element; |
| the value of ARGC counts this element. A null pointer always follows |
| the last element: 'ARGV[ARGC]' is this null pointer. |
| |
| For the command 'cat foo bar', ARGC is 3 and ARGV has three elements, |
| '"cat"', '"foo"' and '"bar"'. |
| |
| In Unix systems you can define 'main' a third way, using three |
| arguments: |
| |
| int main (int ARGC, char *ARGV[], char *ENVP[]) |
| |
| The first two arguments are just the same. The third argument ENVP |
| gives the program's environment; it is the same as the value of |
| 'environ'. *Note Environment Variables::. POSIX.1 does not allow this |
| three-argument form, so to be portable it is best to write 'main' to |
| take two arguments, and use the value of 'environ'. |
| |
| * Menu: |
| |
| * Argument Syntax:: By convention, options start with a hyphen. |
| * Parsing Program Arguments:: Ways to parse program options and arguments. |
| |
| |
| File: libc.info, Node: Argument Syntax, Next: Parsing Program Arguments, Up: Program Arguments |
| |
| 25.1.1 Program Argument Syntax Conventions |
| ------------------------------------------ |
| |
| POSIX recommends these conventions for command line arguments. 'getopt' |
| (*note Getopt::) and 'argp_parse' (*note Argp::) make it easy to |
| implement them. |
| |
| * Arguments are options if they begin with a hyphen delimiter ('-'). |
| |
| * Multiple options may follow a hyphen delimiter in a single token if |
| the options do not take arguments. Thus, '-abc' is equivalent to |
| '-a -b -c'. |
| |
| * Option names are single alphanumeric characters (as for 'isalnum'; |
| *note Classification of Characters::). |
| |
| * Certain options require an argument. For example, the '-o' command |
| of the 'ld' command requires an argument--an output file name. |
| |
| * An option and its argument may or may not appear as separate |
| tokens. (In other words, the whitespace separating them is |
| optional.) Thus, '-o foo' and '-ofoo' are equivalent. |
| |
| * Options typically precede other non-option arguments. |
| |
| The implementations of 'getopt' and 'argp_parse' in the GNU C |
| Library normally make it appear as if all the option arguments were |
| specified before all the non-option arguments for the purposes of |
| parsing, even if the user of your program intermixed option and |
| non-option arguments. They do this by reordering the elements of |
| the ARGV array. This behavior is nonstandard; if you want to |
| suppress it, define the '_POSIX_OPTION_ORDER' environment variable. |
| *Note Standard Environment::. |
| |
| * The argument '--' terminates all options; any following arguments |
| are treated as non-option arguments, even if they begin with a |
| hyphen. |
| |
| * A token consisting of a single hyphen character is interpreted as |
| an ordinary non-option argument. By convention, it is used to |
| specify input from or output to the standard input and output |
| streams. |
| |
| * Options may be supplied in any order, or appear multiple times. |
| The interpretation is left up to the particular application |
| program. |
| |
| GNU adds "long options" to these conventions. Long options consist |
| of '--' followed by a name made of alphanumeric characters and dashes. |
| Option names are typically one to three words long, with hyphens to |
| separate words. Users can abbreviate the option names as long as the |
| abbreviations are unique. |
| |
| To specify an argument for a long option, write '--NAME=VALUE'. This |
| syntax enables a long option to accept an argument that is itself |
| optional. |
| |
| Eventually, GNU systems will provide completion for long option names |
| in the shell. |
| |
| |
| File: libc.info, Node: Parsing Program Arguments, Prev: Argument Syntax, Up: Program Arguments |
| |
| 25.1.2 Parsing Program Arguments |
| -------------------------------- |
| |
| If the syntax for the command line arguments to your program is simple |
| enough, you can simply pick the arguments off from ARGV by hand. But |
| unless your program takes a fixed number of arguments, or all of the |
| arguments are interpreted in the same way (as file names, for example), |
| you are usually better off using 'getopt' (*note Getopt::) or |
| 'argp_parse' (*note Argp::) to do the parsing. |
| |
| 'getopt' is more standard (the short-option only version of it is a |
| part of the POSIX standard), but using 'argp_parse' is often easier, |
| both for very simple and very complex option structures, because it does |
| more of the dirty work for you. |
| |
| * Menu: |
| |
| * Getopt:: Parsing program options using 'getopt'. |
| * Argp:: Parsing program options using 'argp_parse'. |
| * Suboptions:: Some programs need more detailed options. |
| * Suboptions Example:: This shows how it could be done for 'mount'. |
| |
| |
| File: libc.info, Node: Getopt, Next: Argp, Up: Parsing Program Arguments |
| |
| 25.2 Parsing program options using 'getopt' |
| =========================================== |
| |
| The 'getopt' and 'getopt_long' functions automate some of the chore |
| involved in parsing typical unix command line options. |
| |
| * Menu: |
| |
| * Using Getopt:: Using the 'getopt' function. |
| * Example of Getopt:: An example of parsing options with 'getopt'. |
| * Getopt Long Options:: GNU suggests utilities accept long-named |
| options; here is one way to do. |
| * Getopt Long Option Example:: An example of using 'getopt_long'. |
| |
| |
| File: libc.info, Node: Using Getopt, Next: Example of Getopt, Up: Getopt |
| |
| 25.2.1 Using the 'getopt' function |
| ---------------------------------- |
| |
| Here are the details about how to call the 'getopt' function. To use |
| this facility, your program must include the header file 'unistd.h'. |
| |
| -- Variable: int opterr |
| If the value of this variable is nonzero, then 'getopt' prints an |
| error message to the standard error stream if it encounters an |
| unknown option character or an option with a missing required |
| argument. This is the default behavior. If you set this variable |
| to zero, 'getopt' does not print any messages, but it still returns |
| the character '?' to indicate an error. |
| |
| -- Variable: int optopt |
| When 'getopt' encounters an unknown option character or an option |
| with a missing required argument, it stores that option character |
| in this variable. You can use this for providing your own |
| diagnostic messages. |
| |
| -- Variable: int optind |
| This variable is set by 'getopt' to the index of the next element |
| of the ARGV array to be processed. Once 'getopt' has found all of |
| the option arguments, you can use this variable to determine where |
| the remaining non-option arguments begin. The initial value of |
| this variable is '1'. |
| |
| -- Variable: char * optarg |
| This variable is set by 'getopt' to point at the value of the |
| option argument, for those options that accept arguments. |
| |
| -- Function: int getopt (int ARGC, char *const *ARGV, const char |
| *OPTIONS) |
| Preliminary: | MT-Unsafe race:getopt env | AS-Unsafe heap i18n lock |
| corrupt | AC-Unsafe mem lock corrupt | *Note POSIX Safety |
| Concepts::. |
| |
| The 'getopt' function gets the next option argument from the |
| argument list specified by the ARGV and ARGC arguments. Normally |
| these values come directly from the arguments received by 'main'. |
| |
| The OPTIONS argument is a string that specifies the option |
| characters that are valid for this program. An option character in |
| this string can be followed by a colon (':') to indicate that it |
| takes a required argument. If an option character is followed by |
| two colons ('::'), its argument is optional; this is a GNU |
| extension. |
| |
| 'getopt' has three ways to deal with options that follow |
| non-options ARGV elements. The special argument '--' forces in all |
| cases the end of option scanning. |
| |
| * The default is to permute the contents of ARGV while scanning |
| it so that eventually all the non-options are at the end. |
| This allows options to be given in any order, even with |
| programs that were not written to expect this. |
| |
| * If the OPTIONS argument string begins with a hyphen ('-'), |
| this is treated specially. It permits arguments that are not |
| options to be returned as if they were associated with option |
| character '\1'. |
| |
| * POSIX demands the following behavior: The first non-option |
| stops option processing. This mode is selected by either |
| setting the environment variable 'POSIXLY_CORRECT' or |
| beginning the OPTIONS argument string with a plus sign ('+'). |
| |
| The 'getopt' function returns the option character for the next |
| command line option. When no more option arguments are available, |
| it returns '-1'. There may still be more non-option arguments; you |
| must compare the external variable 'optind' against the ARGC |
| parameter to check this. |
| |
| If the option has an argument, 'getopt' returns the argument by |
| storing it in the variable OPTARG. You don't ordinarily need to |
| copy the 'optarg' string, since it is a pointer into the original |
| ARGV array, not into a static area that might be overwritten. |
| |
| If 'getopt' finds an option character in ARGV that was not included |
| in OPTIONS, or a missing option argument, it returns '?' and sets |
| the external variable 'optopt' to the actual option character. If |
| the first character of OPTIONS is a colon (':'), then 'getopt' |
| returns ':' instead of '?' to indicate a missing option argument. |
| In addition, if the external variable 'opterr' is nonzero (which is |
| the default), 'getopt' prints an error message. |
| |
| |
| File: libc.info, Node: Example of Getopt, Next: Getopt Long Options, Prev: Using Getopt, Up: Getopt |
| |
| 25.2.2 Example of Parsing Arguments with 'getopt' |
| ------------------------------------------------- |
| |
| Here is an example showing how 'getopt' is typically used. The key |
| points to notice are: |
| |
| * Normally, 'getopt' is called in a loop. When 'getopt' returns |
| '-1', indicating no more options are present, the loop terminates. |
| |
| * A 'switch' statement is used to dispatch on the return value from |
| 'getopt'. In typical use, each case just sets a variable that is |
| used later in the program. |
| |
| * A second loop is used to process the remaining non-option |
| arguments. |
| |
| |
| #include <ctype.h> |
| #include <stdio.h> |
| #include <stdlib.h> |
| #include <unistd.h> |
| |
| int |
| main (int argc, char **argv) |
| { |
| int aflag = 0; |
| int bflag = 0; |
| char *cvalue = NULL; |
| int index; |
| int c; |
| |
| opterr = 0; |
| |
| while ((c = getopt (argc, argv, "abc:")) != -1) |
| switch (c) |
| { |
| case 'a': |
| aflag = 1; |
| break; |
| case 'b': |
| bflag = 1; |
| break; |
| case 'c': |
| cvalue = optarg; |
| break; |
| case '?': |
| if (optopt == 'c') |
| fprintf (stderr, "Option -%c requires an argument.\n", optopt); |
| else if (isprint (optopt)) |
| fprintf (stderr, "Unknown option `-%c'.\n", optopt); |
| else |
| fprintf (stderr, |
| "Unknown option character `\\x%x'.\n", |
| optopt); |
| return 1; |
| default: |
| abort (); |
| } |
| |
| printf ("aflag = %d, bflag = %d, cvalue = %s\n", |
| aflag, bflag, cvalue); |
| |
| for (index = optind; index < argc; index++) |
| printf ("Non-option argument %s\n", argv[index]); |
| return 0; |
| } |
| |
| Here are some examples showing what this program prints with |
| different combinations of arguments: |
| |
| % testopt |
| aflag = 0, bflag = 0, cvalue = (null) |
| |
| % testopt -a -b |
| aflag = 1, bflag = 1, cvalue = (null) |
| |
| % testopt -ab |
| aflag = 1, bflag = 1, cvalue = (null) |
| |
| % testopt -c foo |
| aflag = 0, bflag = 0, cvalue = foo |
| |
| % testopt -cfoo |
| aflag = 0, bflag = 0, cvalue = foo |
| |
| % testopt arg1 |
| aflag = 0, bflag = 0, cvalue = (null) |
| Non-option argument arg1 |
| |
| % testopt -a arg1 |
| aflag = 1, bflag = 0, cvalue = (null) |
| Non-option argument arg1 |
| |
| % testopt -c foo arg1 |
| aflag = 0, bflag = 0, cvalue = foo |
| Non-option argument arg1 |
| |
| % testopt -a -- -b |
| aflag = 1, bflag = 0, cvalue = (null) |
| Non-option argument -b |
| |
| % testopt -a - |
| aflag = 1, bflag = 0, cvalue = (null) |
| Non-option argument - |
| |
| |
| File: libc.info, Node: Getopt Long Options, Next: Getopt Long Option Example, Prev: Example of Getopt, Up: Getopt |
| |
| 25.2.3 Parsing Long Options with 'getopt_long' |
| ---------------------------------------------- |
| |
| To accept GNU-style long options as well as single-character options, |
| use 'getopt_long' instead of 'getopt'. This function is declared in |
| 'getopt.h', not 'unistd.h'. You should make every program accept long |
| options if it uses any options, for this takes little extra work and |
| helps beginners remember how to use the program. |
| |
| -- Data Type: struct option |
| This structure describes a single long option name for the sake of |
| 'getopt_long'. The argument LONGOPTS must be an array of these |
| structures, one for each long option. Terminate the array with an |
| element containing all zeros. |
| |
| The 'struct option' structure has these fields: |
| |
| 'const char *name' |
| This field is the name of the option. It is a string. |
| |
| 'int has_arg' |
| This field says whether the option takes an argument. It is |
| an integer, and there are three legitimate values: |
| 'no_argument', 'required_argument' and 'optional_argument'. |
| |
| 'int *flag' |
| 'int val' |
| These fields control how to report or act on the option when |
| it occurs. |
| |
| If 'flag' is a null pointer, then the 'val' is a value which |
| identifies this option. Often these values are chosen to |
| uniquely identify particular long options. |
| |
| If 'flag' is not a null pointer, it should be the address of |
| an 'int' variable which is the flag for this option. The |
| value in 'val' is the value to store in the flag to indicate |
| that the option was seen. |
| |
| -- Function: int getopt_long (int ARGC, char *const *ARGV, const char |
| *SHORTOPTS, const struct option *LONGOPTS, int *INDEXPTR) |
| Preliminary: | MT-Unsafe race:getopt env | AS-Unsafe heap i18n lock |
| corrupt | AC-Unsafe mem lock corrupt | *Note POSIX Safety |
| Concepts::. |
| |
| Decode options from the vector ARGV (whose length is ARGC). The |
| argument SHORTOPTS describes the short options to accept, just as |
| it does in 'getopt'. The argument LONGOPTS describes the long |
| options to accept (see above). |
| |
| When 'getopt_long' encounters a short option, it does the same |
| thing that 'getopt' would do: it returns the character code for the |
| option, and stores the options argument (if it has one) in |
| 'optarg'. |
| |
| When 'getopt_long' encounters a long option, it takes actions based |
| on the 'flag' and 'val' fields of the definition of that option. |
| |
| If 'flag' is a null pointer, then 'getopt_long' returns the |
| contents of 'val' to indicate which option it found. You should |
| arrange distinct values in the 'val' field for options with |
| different meanings, so you can decode these values after |
| 'getopt_long' returns. If the long option is equivalent to a short |
| option, you can use the short option's character code in 'val'. |
| |
| If 'flag' is not a null pointer, that means this option should just |
| set a flag in the program. The flag is a variable of type 'int' |
| that you define. Put the address of the flag in the 'flag' field. |
| Put in the 'val' field the value you would like this option to |
| store in the flag. In this case, 'getopt_long' returns '0'. |
| |
| For any long option, 'getopt_long' tells you the index in the array |
| LONGOPTS of the options definition, by storing it into '*INDEXPTR'. |
| You can get the name of the option with 'LONGOPTS[*INDEXPTR].name'. |
| So you can distinguish among long options either by the values in |
| their 'val' fields or by their indices. You can also distinguish |
| in this way among long options that set flags. |
| |
| When a long option has an argument, 'getopt_long' puts the argument |
| value in the variable 'optarg' before returning. When the option |
| has no argument, the value in 'optarg' is a null pointer. This is |
| how you can tell whether an optional argument was supplied. |
| |
| When 'getopt_long' has no more options to handle, it returns '-1', |
| and leaves in the variable 'optind' the index in ARGV of the next |
| remaining argument. |
| |
| Since long option names were used before the 'getopt_long' options |
| was invented there are program interfaces which require programs to |
| recognize options like '-option value' instead of '--option value'. To |
| enable these programs to use the GNU getopt functionality there is one |
| more function available. |
| |
| -- Function: int getopt_long_only (int ARGC, char *const *ARGV, const |
| char *SHORTOPTS, const struct option *LONGOPTS, int *INDEXPTR) |
| Preliminary: | MT-Unsafe race:getopt env | AS-Unsafe heap i18n lock |
| corrupt | AC-Unsafe mem lock corrupt | *Note POSIX Safety |
| Concepts::. |
| |
| The 'getopt_long_only' function is equivalent to the 'getopt_long' |
| function but it allows to specify the user of the application to |
| pass long options with only '-' instead of '--'. The '--' prefix |
| is still recognized but instead of looking through the short |
| options if a '-' is seen it is first tried whether this parameter |
| names a long option. If not, it is parsed as a short option. |
| |
| Assuming 'getopt_long_only' is used starting an application with |
| |
| app -foo |
| |
| the 'getopt_long_only' will first look for a long option named |
| 'foo'. If this is not found, the short options 'f', 'o', and again |
| 'o' are recognized. |
| |
| |
| File: libc.info, Node: Getopt Long Option Example, Prev: Getopt Long Options, Up: Getopt |
| |
| 25.2.4 Example of Parsing Long Options with 'getopt_long' |
| --------------------------------------------------------- |
| |
| |
| #include <stdio.h> |
| #include <stdlib.h> |
| #include <getopt.h> |
| |
| /* Flag set by '--verbose'. */ |
| static int verbose_flag; |
| |
| int |
| main (int argc, char **argv) |
| { |
| int c; |
| |
| while (1) |
| { |
| static struct option long_options[] = |
| { |
| /* These options set a flag. */ |
| {"verbose", no_argument, &verbose_flag, 1}, |
| {"brief", no_argument, &verbose_flag, 0}, |
| /* These options don't set a flag. |
| We distinguish them by their indices. */ |
| {"add", no_argument, 0, 'a'}, |
| {"append", no_argument, 0, 'b'}, |
| {"delete", required_argument, 0, 'd'}, |
| {"create", required_argument, 0, 'c'}, |
| {"file", required_argument, 0, 'f'}, |
| {0, 0, 0, 0} |
| }; |
| /* 'getopt_long' stores the option index here. */ |
| int option_index = 0; |
| |
| c = getopt_long (argc, argv, "abc:d:f:", |
| long_options, &option_index); |
| |
| /* Detect the end of the options. */ |
| if (c == -1) |
| break; |
| |
| switch (c) |
| { |
| case 0: |
| /* If this option set a flag, do nothing else now. */ |
| if (long_options[option_index].flag != 0) |
| break; |
| printf ("option %s", long_options[option_index].name); |
| if (optarg) |
| printf (" with arg %s", optarg); |
| printf ("\n"); |
| break; |
| |
| case 'a': |
| puts ("option -a\n"); |
| break; |
| |
| case 'b': |
| puts ("option -b\n"); |
| break; |
| |
| case 'c': |
| printf ("option -c with value `%s'\n", optarg); |
| break; |
| |
| case 'd': |
| printf ("option -d with value `%s'\n", optarg); |
| break; |
| |
| case 'f': |
| printf ("option -f with value `%s'\n", optarg); |
| break; |
| |
| case '?': |
| /* 'getopt_long' already printed an error message. */ |
| break; |
| |
| default: |
| abort (); |
| } |
| } |
| |
| /* Instead of reporting '--verbose' |
| and '--brief' as they are encountered, |
| we report the final status resulting from them. */ |
| if (verbose_flag) |
| puts ("verbose flag is set"); |
| |
| /* Print any remaining command line arguments (not options). */ |
| if (optind < argc) |
| { |
| printf ("non-option ARGV-elements: "); |
| while (optind < argc) |
| printf ("%s ", argv[optind++]); |
| putchar ('\n'); |
| } |
| |
| exit (0); |
| } |
| |
| |
| File: libc.info, Node: Argp, Next: Suboptions, Prev: Getopt, Up: Parsing Program Arguments |
| |
| 25.3 Parsing Program Options with Argp |
| ====================================== |
| |
| "Argp" is an interface for parsing unix-style argument vectors. *Note |
| Program Arguments::. |
| |
| Argp provides features unavailable in the more commonly used 'getopt' |
| interface. These features include automatically producing output in |
| response to the '--help' and '--version' options, as described in the |
| GNU coding standards. Using argp makes it less likely that programmers |
| will neglect to implement these additional options or keep them up to |
| date. |
| |
| Argp also provides the ability to merge several independently defined |
| option parsers into one, mediating conflicts between them and making the |
| result appear seamless. A library can export an argp option parser that |
| user programs might employ in conjunction with their own option parsers, |
| resulting in less work for the user programs. Some programs may use |
| only argument parsers exported by libraries, thereby achieving |
| consistent and efficient option-parsing for abstractions implemented by |
| the libraries. |
| |
| The header file '<argp.h>' should be included to use argp. |
| |
| 25.3.1 The 'argp_parse' Function |
| -------------------------------- |
| |
| The main interface to argp is the 'argp_parse' function. In many cases, |
| calling 'argp_parse' is the only argument-parsing code needed in 'main'. |
| *Note Program Arguments::. |
| |
| -- Function: error_t argp_parse (const struct argp *ARGP, int ARGC, |
| char **ARGV, unsigned FLAGS, int *ARG_INDEX, void *INPUT) |
| Preliminary: | MT-Unsafe race:argpbuf locale env | AS-Unsafe heap |
| i18n lock corrupt | AC-Unsafe mem lock corrupt | *Note POSIX Safety |
| Concepts::. |
| |
| The 'argp_parse' function parses the arguments in ARGV, of length |
| ARGC, using the argp parser ARGP. *Note Argp Parsers::. Passing a |
| null pointer for ARGP is the same as using a 'struct argp' |
| containing all zeros. |
| |
| FLAGS is a set of flag bits that modify the parsing behavior. |
| *Note Argp Flags::. INPUT is passed through to the argp parser |
| ARGP, and has meaning defined by ARGP. A typical usage is to pass |
| a pointer to a structure which is used for specifying parameters to |
| the parser and passing back the results. |
| |
| Unless the 'ARGP_NO_EXIT' or 'ARGP_NO_HELP' flags are included in |
| FLAGS, calling 'argp_parse' may result in the program exiting. |
| This behavior is true if an error is detected, or when an unknown |
| option is encountered. *Note Program Termination::. |
| |
| If ARG_INDEX is non-null, the index of the first unparsed option in |
| ARGV is returned as a value. |
| |
| The return value is zero for successful parsing, or an error code |
| (*note Error Codes::) if an error is detected. Different argp |
| parsers may return arbitrary error codes, but the standard error |
| codes are: 'ENOMEM' if a memory allocation error occurred, or |
| 'EINVAL' if an unknown option or option argument is encountered. |
| |
| * Menu: |
| |
| * Globals: Argp Global Variables. Global argp parameters. |
| * Parsers: Argp Parsers. Defining parsers for use with 'argp_parse'. |
| * Flags: Argp Flags. Flags that modify the behavior of 'argp_parse'. |
| * Help: Argp Help. Printing help messages when not parsing. |
| * Examples: Argp Examples. Simple examples of programs using argp. |
| * Customization: Argp User Customization. |
| Users may control the '--help' output format. |
| |
| |
| File: libc.info, Node: Argp Global Variables, Next: Argp Parsers, Up: Argp |
| |
| 25.3.2 Argp Global Variables |
| ---------------------------- |
| |
| These variables make it easy for user programs to implement the |
| '--version' option and provide a bug-reporting address in the '--help' |
| output. These are implemented in argp by default. |
| |
| -- Variable: const char * argp_program_version |
| If defined or set by the user program to a non-zero value, then a |
| '--version' option is added when parsing with 'argp_parse', which |
| will print the '--version' string followed by a newline and exit. |
| The exception to this is if the 'ARGP_NO_EXIT' flag is used. |
| |
| -- Variable: const char * argp_program_bug_address |
| If defined or set by the user program to a non-zero value, |
| 'argp_program_bug_address' should point to a string that will be |
| printed at the end of the standard output for the '--help' option, |
| embedded in a sentence that says 'Report bugs to ADDRESS.'. |
| |
| -- Variable: argp_program_version_hook |
| If defined or set by the user program to a non-zero value, a |
| '--version' option is added when parsing with 'arg_parse', which |
| prints the program version and exits with a status of zero. This |
| is not the case if the 'ARGP_NO_HELP' flag is used. If the |
| 'ARGP_NO_EXIT' flag is set, the exit behavior of the program is |
| suppressed or modified, as when the argp parser is going to be used |
| by other programs. |
| |
| It should point to a function with this type of signature: |
| |
| void PRINT-VERSION (FILE *STREAM, struct argp_state *STATE) |
| |
| *Note Argp Parsing State::, for an explanation of STATE. |
| |
| This variable takes precedence over 'argp_program_version', and is |
| useful if a program has version information not easily expressed in |
| a simple string. |
| |
| -- Variable: error_t argp_err_exit_status |
| This is the exit status used when argp exits due to a parsing |
| error. If not defined or set by the user program, this defaults |
| to: 'EX_USAGE' from '<sysexits.h>'. |
| |
| |
| File: libc.info, Node: Argp Parsers, Next: Argp Flags, Prev: Argp Global Variables, Up: Argp |
| |
| 25.3.3 Specifying Argp Parsers |
| ------------------------------ |
| |
| The first argument to the 'argp_parse' function is a pointer to a |
| 'struct argp', which is known as an "argp parser": |
| |
| -- Data Type: struct argp |
| This structure specifies how to parse a given set of options and |
| arguments, perhaps in conjunction with other argp parsers. It has |
| the following fields: |
| |
| 'const struct argp_option *options' |
| A pointer to a vector of 'argp_option' structures specifying |
| which options this argp parser understands; it may be zero if |
| there are no options at all. *Note Argp Option Vectors::. |
| |
| 'argp_parser_t parser' |
| A pointer to a function that defines actions for this parser; |
| it is called for each option parsed, and at other well-defined |
| points in the parsing process. A value of zero is the same as |
| a pointer to a function that always returns |
| 'ARGP_ERR_UNKNOWN'. *Note Argp Parser Functions::. |
| |
| 'const char *args_doc' |
| If non-zero, a string describing what non-option arguments are |
| called by this parser. This is only used to print the |
| 'Usage:' message. If it contains newlines, the strings |
| separated by them are considered alternative usage patterns |
| and printed on separate lines. Lines after the first are |
| prefixed by ' or: ' instead of 'Usage:'. |
| |
| 'const char *doc' |
| If non-zero, a string containing extra text to be printed |
| before and after the options in a long help message, with the |
| two sections separated by a vertical tab (''\v'', ''\013'') |
| character. By convention, the documentation before the |
| options is just a short string explaining what the program |
| does. Documentation printed after the options describe |
| behavior in more detail. |
| |
| 'const struct argp_child *children' |
| A pointer to a vector of 'argp_children' structures. This |
| pointer specifies which additional argp parsers should be |
| combined with this one. *Note Argp Children::. |
| |
| 'char *(*help_filter)(int KEY, const char *TEXT, void *INPUT)' |
| If non-zero, a pointer to a function that filters the output |
| of help messages. *Note Argp Help Filtering::. |
| |
| 'const char *argp_domain' |
| If non-zero, the strings used in the argp library are |
| translated using the domain described by this string. If |
| zero, the current default domain is used. |
| |
| Of the above group, 'options', 'parser', 'args_doc', and the 'doc' |
| fields are usually all that are needed. If an argp parser is defined as |
| an initialized C variable, only the fields used need be specified in the |
| initializer. The rest will default to zero due to the way C structure |
| initialization works. This design is exploited in most argp structures; |
| the most-used fields are grouped near the beginning, the unused fields |
| left unspecified. |
| |
| * Menu: |
| |
| * Options: Argp Option Vectors. Specifying options in an argp parser. |
| * Argp Parser Functions:: Defining actions for an argp parser. |
| * Children: Argp Children. Combining multiple argp parsers. |
| * Help Filtering: Argp Help Filtering. Customizing help output for an argp parser. |
| |
| |
| File: libc.info, Node: Argp Option Vectors, Next: Argp Parser Functions, Prev: Argp Parsers, Up: Argp Parsers |
| |
| 25.3.4 Specifying Options in an Argp Parser |
| ------------------------------------------- |
| |
| The 'options' field in a 'struct argp' points to a vector of 'struct |
| argp_option' structures, each of which specifies an option that the argp |
| parser supports. Multiple entries may be used for a single option |
| provided it has multiple names. This should be terminated by an entry |
| with zero in all fields. Note that when using an initialized C array |
| for options, writing '{ 0 }' is enough to achieve this. |
| |
| -- Data Type: struct argp_option |
| This structure specifies a single option that an argp parser |
| understands, as well as how to parse and document that option. It |
| has the following fields: |
| |
| 'const char *name' |
| The long name for this option, corresponding to the long |
| option '--NAME'; this field may be zero if this option _only_ |
| has a short name. To specify multiple names for an option, |
| additional entries may follow this one, with the |
| 'OPTION_ALIAS' flag set. *Note Argp Option Flags::. |
| |
| 'int key' |
| The integer key provided by the current option to the option |
| parser. If KEY has a value that is a printable ASCII |
| character (i.e., 'isascii (KEY)' is true), it _also_ specifies |
| a short option '-CHAR', where CHAR is the ASCII character with |
| the code KEY. |
| |
| 'const char *arg' |
| If non-zero, this is the name of an argument associated with |
| this option, which must be provided (e.g., with the |
| '--NAME=VALUE' or '-CHAR VALUE' syntaxes), unless the |
| 'OPTION_ARG_OPTIONAL' flag (*note Argp Option Flags::) is set, |
| in which case it _may_ be provided. |
| |
| 'int flags' |
| Flags associated with this option, some of which are referred |
| to above. *Note Argp Option Flags::. |
| |
| 'const char *doc' |
| A documentation string for this option, for printing in help |
| messages. |
| |
| If both the 'name' and 'key' fields are zero, this string will |
| be printed tabbed left from the normal option column, making |
| it useful as a group header. This will be the first thing |
| printed in its group. In this usage, it's conventional to end |
| the string with a ':' character. |
| |
| 'int group' |
| Group identity for this option. |
| |
| In a long help message, options are sorted alphabetically |
| within each group, and the groups presented in the order 0, 1, |
| 2, ..., N, -M, ..., -2, -1. |
| |
| Every entry in an options array with this field 0 will inherit |
| the group number of the previous entry, or zero if it's the |
| first one. If it's a group header with 'name' and 'key' |
| fields both zero, the previous entry + 1 is the default. |
| Automagic options such as '--help' are put into group -1. |
| |
| Note that because of C structure initialization rules, this |
| field often need not be specified, because 0 is the correct |
| value. |
| |
| * Menu: |
| |
| * Flags: Argp Option Flags. Flags for options. |
| |
| |
| File: libc.info, Node: Argp Option Flags, Up: Argp Option Vectors |
| |
| 25.3.4.1 Flags for Argp Options |
| ............................... |
| |
| The following flags may be or'd together in the 'flags' field of a |
| 'struct argp_option'. These flags control various aspects of how that |
| option is parsed or displayed in help messages: |
| |
| 'OPTION_ARG_OPTIONAL' |
| The argument associated with this option is optional. |
| |
| 'OPTION_HIDDEN' |
| This option isn't displayed in any help messages. |
| |
| 'OPTION_ALIAS' |
| This option is an alias for the closest previous non-alias option. |
| This means that it will be displayed in the same help entry, and |
| will inherit fields other than 'name' and 'key' from the option |
| being aliased. |
| |
| 'OPTION_DOC' |
| This option isn't actually an option and should be ignored by the |
| actual option parser. It is an arbitrary section of documentation |
| that should be displayed in much the same manner as the options. |
| This is known as a "documentation option". |
| |
| If this flag is set, then the option 'name' field is displayed |
| unmodified (e.g., no '--' prefix is added) at the left-margin where |
| a _short_ option would normally be displayed, and this |
| documentation string is left in it's usual place. For purposes of |
| sorting, any leading whitespace and punctuation is ignored, unless |
| the first non-whitespace character is '-'. This entry is displayed |
| after all options, after 'OPTION_DOC' entries with a leading '-', |
| in the same group. |
| |
| 'OPTION_NO_USAGE' |
| This option shouldn't be included in 'long' usage messages, but |
| should still be included in other help messages. This is intended |
| for options that are completely documented in an argp's 'args_doc' |
| field. *Note Argp Parsers::. Including this option in the generic |
| usage list would be redundant, and should be avoided. |
| |
| For instance, if 'args_doc' is '"FOO BAR\n-x BLAH"', and the '-x' |
| option's purpose is to distinguish these two cases, '-x' should |
| probably be marked 'OPTION_NO_USAGE'. |
| |
| |
| File: libc.info, Node: Argp Parser Functions, Next: Argp Children, Prev: Argp Option Vectors, Up: Argp Parsers |
| |
| 25.3.5 Argp Parser Functions |
| ---------------------------- |
| |
| The function pointed to by the 'parser' field in a 'struct argp' (*note |
| Argp Parsers::) defines what actions take place in response to each |
| option or argument parsed. It is also used as a hook, allowing a parser |
| to perform tasks at certain other points during parsing. |
| |
| Argp parser functions have the following type signature: |
| |
| error_t PARSER (int KEY, char *ARG, struct argp_state *STATE) |
| |
| where the arguments are as follows: |
| |
| KEY |
| For each option that is parsed, PARSER is called with a value of |
| KEY from that option's 'key' field in the option vector. *Note |
| Argp Option Vectors::. PARSER is also called at other times with |
| special reserved keys, such as 'ARGP_KEY_ARG' for non-option |
| arguments. *Note Argp Special Keys::. |
| |
| ARG |
| If KEY is an option, ARG is its given value. This defaults to zero |
| if no value is specified. Only options that have a non-zero 'arg' |
| field can ever have a value. These must _always_ have a value |
| unless the 'OPTION_ARG_OPTIONAL' flag is specified. If the input |
| being parsed specifies a value for an option that doesn't allow |
| one, an error results before PARSER ever gets called. |
| |
| If KEY is 'ARGP_KEY_ARG', ARG is a non-option argument. Other |
| special keys always have a zero ARG. |
| |
| STATE |
| STATE points to a 'struct argp_state', containing useful |
| information about the current parsing state for use by PARSER. |
| *Note Argp Parsing State::. |
| |
| When PARSER is called, it should perform whatever action is |
| appropriate for KEY, and return '0' for success, 'ARGP_ERR_UNKNOWN' if |
| the value of KEY is not handled by this parser function, or a unix error |
| code if a real error occurred. *Note Error Codes::. |
| |
| -- Macro: int ARGP_ERR_UNKNOWN |
| Argp parser functions should return 'ARGP_ERR_UNKNOWN' for any KEY |
| value they do not recognize, or for non-option arguments ('KEY == |
| ARGP_KEY_ARG') that they are not equipped to handle. |
| |
| A typical parser function uses a switch statement on KEY: |
| |
| error_t |
| parse_opt (int key, char *arg, struct argp_state *state) |
| { |
| switch (key) |
| { |
| case OPTION_KEY: |
| ACTION |
| break; |
| ... |
| default: |
| return ARGP_ERR_UNKNOWN; |
| } |
| return 0; |
| } |
| |
| * Menu: |
| |
| * Keys: Argp Special Keys. Special values for the KEY argument. |
| * State: Argp Parsing State. What the STATE argument refers to. |
| * Functions: Argp Helper Functions. Functions to help during argp parsing. |
| |
| |
| File: libc.info, Node: Argp Special Keys, Next: Argp Parsing State, Up: Argp Parser Functions |
| |
| 25.3.5.1 Special Keys for Argp Parser Functions |
| ............................................... |
| |
| In addition to key values corresponding to user options, the KEY |
| argument to argp parser functions may have a number of other special |
| values. In the following example ARG and STATE refer to parser function |
| arguments. *Note Argp Parser Functions::. |
| |
| 'ARGP_KEY_ARG' |
| This is not an option at all, but rather a command line argument, |
| whose value is pointed to by ARG. |
| |
| When there are multiple parser functions in play due to argp |
| parsers being combined, it's impossible to know which one will |
| handle a specific argument. Each is called until one returns 0 or |
| an error other than 'ARGP_ERR_UNKNOWN'; if an argument is not |
| handled, 'argp_parse' immediately returns success, without parsing |
| any more arguments. |
| |
| Once a parser function returns success for this key, that fact is |
| recorded, and the 'ARGP_KEY_NO_ARGS' case won't be used. |
| _However_, if while processing the argument a parser function |
| decrements the 'next' field of its STATE argument, the option won't |
| be considered processed; this is to allow you to actually modify |
| the argument, perhaps into an option, and have it processed again. |
| |
| 'ARGP_KEY_ARGS' |
| If a parser function returns 'ARGP_ERR_UNKNOWN' for 'ARGP_KEY_ARG', |
| it is immediately called again with the key 'ARGP_KEY_ARGS', which |
| has a similar meaning, but is slightly more convenient for |
| consuming all remaining arguments. ARG is 0, and the tail of the |
| argument vector may be found at 'STATE->argv + STATE->next'. If |
| success is returned for this key, and 'STATE->next' is unchanged, |
| all remaining arguments are considered to have been consumed. |
| Otherwise, the amount by which 'STATE->next' has been adjusted |
| indicates how many were used. Here's an example that uses both, |
| for different args: |
| |
| ... |
| case ARGP_KEY_ARG: |
| if (STATE->arg_num == 0) |
| /* First argument */ |
| first_arg = ARG; |
| else |
| /* Let the next case parse it. */ |
| return ARGP_KEY_UNKNOWN; |
| break; |
| case ARGP_KEY_ARGS: |
| remaining_args = STATE->argv + STATE->next; |
| num_remaining_args = STATE->argc - STATE->next; |
| break; |
| |
| 'ARGP_KEY_END' |
| This indicates that there are no more command line arguments. |
| Parser functions are called in a different order, children first. |
| This allows each parser to clean up its state for the parent. |
| |
| 'ARGP_KEY_NO_ARGS' |
| Because it's common to do some special processing if there aren't |
| any non-option args, parser functions are called with this key if |
| they didn't successfully process any non-option arguments. This is |
| called just before 'ARGP_KEY_END', where more general validity |
| checks on previously parsed arguments take place. |
| |
| 'ARGP_KEY_INIT' |
| This is passed in before any parsing is done. Afterwards, the |
| values of each element of the 'child_input' field of STATE, if any, |
| are copied to each child's state to be the initial value of the |
| 'input' when _their_ parsers are called. |
| |
| 'ARGP_KEY_SUCCESS' |
| Passed in when parsing has successfully been completed, even if |
| arguments remain. |
| |
| 'ARGP_KEY_ERROR' |
| Passed in if an error has occurred and parsing is terminated. In |
| this case a call with a key of 'ARGP_KEY_SUCCESS' is never made. |
| |
| 'ARGP_KEY_FINI' |
| The final key ever seen by any parser, even after |
| 'ARGP_KEY_SUCCESS' and 'ARGP_KEY_ERROR'. Any resources allocated |
| by 'ARGP_KEY_INIT' may be freed here. At times, certain resources |
| allocated are to be returned to the caller after a successful |
| parse. In that case, those particular resources can be freed in |
| the 'ARGP_KEY_ERROR' case. |
| |
| In all cases, 'ARGP_KEY_INIT' is the first key seen by parser |
| functions, and 'ARGP_KEY_FINI' the last, unless an error was returned by |
| the parser for 'ARGP_KEY_INIT'. Other keys can occur in one the |
| following orders. OPT refers to an arbitrary option key: |
| |
| OPT... 'ARGP_KEY_NO_ARGS' 'ARGP_KEY_END' 'ARGP_KEY_SUCCESS' |
| The arguments being parsed did not contain any non-option |
| arguments. |
| |
| ( OPT | 'ARGP_KEY_ARG' )... 'ARGP_KEY_END' 'ARGP_KEY_SUCCESS' |
| All non-option arguments were successfully handled by a parser |
| function. There may be multiple parser functions if multiple argp |
| parsers were combined. |
| |
| ( OPT | 'ARGP_KEY_ARG' )... 'ARGP_KEY_SUCCESS' |
| Some non-option argument went unrecognized. |
| |
| This occurs when every parser function returns 'ARGP_KEY_UNKNOWN' |
| for an argument, in which case parsing stops at that argument if |
| ARG_INDEX is a null pointer. Otherwise an error occurs. |
| |
| In all cases, if a non-null value for ARG_INDEX gets passed to |
| 'argp_parse', the index of the first unparsed command-line argument is |
| passed back in that value. |
| |
| If an error occurs and is either detected by argp or because a parser |
| function returned an error value, each parser is called with |
| 'ARGP_KEY_ERROR'. No further calls are made, except the final call with |
| 'ARGP_KEY_FINI'. |
| |
| |
| File: libc.info, Node: Argp Parsing State, Next: Argp Helper Functions, Prev: Argp Special Keys, Up: Argp Parser Functions |
| |
| 25.3.5.2 Argp Parsing State |
| ........................... |
| |
| The third argument to argp parser functions (*note Argp Parser |
| Functions::) is a pointer to a 'struct argp_state', which contains |
| information about the state of the option parsing. |
| |
| -- Data Type: struct argp_state |
| This structure has the following fields, which may be modified as |
| noted: |
| |
| 'const struct argp *const root_argp' |
| The top level argp parser being parsed. Note that this is |
| often _not_ the same 'struct argp' passed into 'argp_parse' by |
| the invoking program. *Note Argp::. It is an internal argp |
| parser that contains options implemented by 'argp_parse' |
| itself, such as '--help'. |
| |
| 'int argc' |
| 'char **argv' |
| The argument vector being parsed. This may be modified. |
| |
| 'int next' |
| The index in 'argv' of the next argument to be parsed. This |
| may be modified. |
| |
| One way to consume all remaining arguments in the input is to |
| set 'STATE->next = STATE->argc', perhaps after recording the |
| value of the 'next' field to find the consumed arguments. The |
| current option can be re-parsed immediately by decrementing |
| this field, then modifying 'STATE->argv[STATE->next]' to |
| reflect the option that should be reexamined. |
| |
| 'unsigned flags' |
| The flags supplied to 'argp_parse'. These may be modified, |
| although some flags may only take effect when 'argp_parse' is |
| first invoked. *Note Argp Flags::. |
| |
| 'unsigned arg_num' |
| While calling a parsing function with the KEY argument |
| 'ARGP_KEY_ARG', this represents the number of the current arg, |
| starting at 0. It is incremented after each 'ARGP_KEY_ARG' |
| call returns. At all other times, this is the number of |
| 'ARGP_KEY_ARG' arguments that have been processed. |
| |
| 'int quoted' |
| If non-zero, the index in 'argv' of the first argument |
| following a special '--' argument. This prevents anything |
| that follows from being interpreted as an option. It is only |
| set after argument parsing has proceeded past this point. |
| |
| 'void *input' |
| An arbitrary pointer passed in from the caller of |
| 'argp_parse', in the INPUT argument. |
| |
| 'void **child_inputs' |
| These are values that will be passed to child parsers. This |
| vector will be the same length as the number of children in |
| the current parser. Each child parser will be given the value |
| of 'STATE->child_inputs[I]' as _its_ 'STATE->input' field, |
| where I is the index of the child in the this parser's |
| 'children' field. *Note Argp Children::. |
| |
| 'void *hook' |
| For the parser function's use. Initialized to 0, but |
| otherwise ignored by argp. |
| |
| 'char *name' |
| The name used when printing messages. This is initialized to |
| 'argv[0]', or 'program_invocation_name' if 'argv[0]' is |
| unavailable. |
| |
| 'FILE *err_stream' |
| 'FILE *out_stream' |
| The stdio streams used when argp prints. Error messages are |
| printed to 'err_stream', all other output, such as '--help' |
| output) to 'out_stream'. These are initialized to 'stderr' |
| and 'stdout' respectively. *Note Standard Streams::. |
| |
| 'void *pstate' |
| Private, for use by the argp implementation. |
| |
| |
| File: libc.info, Node: Argp Helper Functions, Prev: Argp Parsing State, Up: Argp Parser Functions |
| |
| 25.3.5.3 Functions For Use in Argp Parsers |
| .......................................... |
| |
| Argp provides a number of functions available to the user of argp (*note |
| Argp Parser Functions::), mostly for producing error messages. These |
| take as their first argument the STATE argument to the parser function. |
| *Note Argp Parsing State::. |
| |
| -- Function: void argp_usage (const struct argp_state *STATE) |
| Preliminary: | MT-Unsafe race:argpbuf env locale | AS-Unsafe heap |
| i18n corrupt | AC-Unsafe mem corrupt lock | *Note POSIX Safety |
| Concepts::. |
| |
| Outputs the standard usage message for the argp parser referred to |
| by STATE to 'STATE->err_stream' and terminate the program with |
| 'exit (argp_err_exit_status)'. *Note Argp Global Variables::. |
| |
| -- Function: void argp_error (const struct argp_state *STATE, const |
| char *FMT, ...) |
| Preliminary: | MT-Unsafe race:argpbuf env locale | AS-Unsafe heap |
| i18n corrupt | AC-Unsafe mem corrupt lock | *Note POSIX Safety |
| Concepts::. |
| |
| Prints the printf format string FMT and following args, preceded by |
| the program name and ':', and followed by a 'Try ... --help' |
| message, and terminates the program with an exit status of |
| 'argp_err_exit_status'. *Note Argp Global Variables::. |
| |
| -- Function: void argp_failure (const struct argp_state *STATE, int |
| STATUS, int ERRNUM, const char *FMT, ...) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt heap | AC-Unsafe lock |
| corrupt mem | *Note POSIX Safety Concepts::. |
| |
| Similar to the standard gnu error-reporting function 'error', this |
| prints the program name and ':', the printf format string FMT, and |
| the appropriate following args. If it is non-zero, the standard |
| unix error text for ERRNUM is printed. If STATUS is non-zero, it |
| terminates the program with that value as its exit status. |
| |
| The difference between 'argp_failure' and 'argp_error' is that |
| 'argp_error' is for _parsing errors_, whereas 'argp_failure' is for |
| other problems that occur during parsing but don't reflect a |
| syntactic problem with the input, such as illegal values for |
| options, bad phase of the moon, etc. |
| |
| -- Function: void argp_state_help (const struct argp_state *STATE, FILE |
| *STREAM, unsigned FLAGS) |
| Preliminary: | MT-Unsafe race:argpbuf env locale | AS-Unsafe heap |
| i18n corrupt | AC-Unsafe mem corrupt lock | *Note POSIX Safety |
| Concepts::. |
| |
| Outputs a help message for the argp parser referred to by STATE, to |
| STREAM. The FLAGS argument determines what sort of help message is |
| produced. *Note Argp Help Flags::. |
| |
| Error output is sent to 'STATE->err_stream', and the program name |
| printed is 'STATE->name'. |
| |
| The output or program termination behavior of these functions may be |
| suppressed if the 'ARGP_NO_EXIT' or 'ARGP_NO_ERRS' flags are passed to |
| 'argp_parse'. *Note Argp Flags::. |
| |
| This behavior is useful if an argp parser is exported for use by |
| other programs (e.g., by a library), and may be used in a context where |
| it is not desirable to terminate the program in response to parsing |
| errors. In argp parsers intended for such general use, and for the case |
| where the program _doesn't_ terminate, calls to any of these functions |
| should be followed by code that returns the appropriate error code: |
| |
| if (BAD ARGUMENT SYNTAX) |
| { |
| argp_usage (STATE); |
| return EINVAL; |
| } |
| |
| If a parser function will _only_ be used when 'ARGP_NO_EXIT' is not set, |
| the return may be omitted. |
| |
| |
| File: libc.info, Node: Argp Children, Next: Argp Help Filtering, Prev: Argp Parser Functions, Up: Argp Parsers |
| |
| 25.3.6 Combining Multiple Argp Parsers |
| -------------------------------------- |
| |
| The 'children' field in a 'struct argp' enables other argp parsers to be |
| combined with the referencing one for the parsing of a single set of |
| arguments. This field should point to a vector of 'struct argp_child', |
| which is terminated by an entry having a value of zero in the 'argp' |
| field. |
| |
| Where conflicts between combined parsers arise, as when two specify |
| an option with the same name, the parser conflicts are resolved in favor |
| of the parent argp parser(s), or the earlier of the argp parsers in the |
| list of children. |
| |
| -- Data Type: struct argp_child |
| An entry in the list of subsidiary argp parsers pointed to by the |
| 'children' field in a 'struct argp'. The fields are as follows: |
| |
| 'const struct argp *argp' |
| The child argp parser, or zero to end of the list. |
| |
| 'int flags' |
| Flags for this child. |
| |
| 'const char *header' |
| If non-zero, this is an optional header to be printed within |
| help output before the child options. As a side-effect, a |
| non-zero value forces the child options to be grouped |
| together. To achieve this effect without actually printing a |
| header string, use a value of '""'. As with header strings |
| specified in an option entry, the conventional value of the |
| last character is ':'. *Note Argp Option Vectors::. |
| |
| 'int group' |
| This is where the child options are grouped relative to the |
| other 'consolidated' options in the parent argp parser. The |
| values are the same as the 'group' field in 'struct |
| argp_option'. *Note Argp Option Vectors::. All |
| child-groupings follow parent options at a particular group |
| level. If both this field and 'header' are zero, then the |
| child's options aren't grouped together, they are merged with |
| parent options at the parent option group level. |
| |
| |
| File: libc.info, Node: Argp Flags, Next: Argp Help, Prev: Argp Parsers, Up: Argp |
| |
| 25.3.7 Flags for 'argp_parse' |
| ----------------------------- |
| |
| The default behavior of 'argp_parse' is designed to be convenient for |
| the most common case of parsing program command line argument. To |
| modify these defaults, the following flags may be or'd together in the |
| FLAGS argument to 'argp_parse': |
| |
| 'ARGP_PARSE_ARGV0' |
| Don't ignore the first element of the ARGV argument to |
| 'argp_parse'. Unless 'ARGP_NO_ERRS' is set, the first element of |
| the argument vector is skipped for option parsing purposes, as it |
| corresponds to the program name in a command line. |
| |
| 'ARGP_NO_ERRS' |
| Don't print error messages for unknown options to 'stderr'; unless |
| this flag is set, 'ARGP_PARSE_ARGV0' is ignored, as 'argv[0]' is |
| used as the program name in the error messages. This flag implies |
| 'ARGP_NO_EXIT'. This is based on the assumption that silent |
| exiting upon errors is bad behavior. |
| |
| 'ARGP_NO_ARGS' |
| Don't parse any non-option args. Normally these are parsed by |
| calling the parse functions with a key of 'ARGP_KEY_ARG', the |
| actual argument being the value. This flag needn't normally be |
| set, as the default behavior is to stop parsing as soon as an |
| argument fails to be parsed. *Note Argp Parser Functions::. |
| |
| 'ARGP_IN_ORDER' |
| Parse options and arguments in the same order they occur on the |
| command line. Normally they're rearranged so that all options come |
| first. |
| |
| 'ARGP_NO_HELP' |
| Don't provide the standard long option '--help', which ordinarily |
| causes usage and option help information to be output to 'stdout' |
| and 'exit (0)'. |
| |
| 'ARGP_NO_EXIT' |
| Don't exit on errors, although they may still result in error |
| messages. |
| |
| 'ARGP_LONG_ONLY' |
| Use the gnu getopt 'long-only' rules for parsing arguments. This |
| allows long-options to be recognized with only a single '-' (i.e., |
| '-help'). This results in a less useful interface, and its use is |
| discouraged as it conflicts with the way most GNU programs work as |
| well as the GNU coding standards. |
| |
| 'ARGP_SILENT' |
| Turns off any message-printing/exiting options, specifically |
| 'ARGP_NO_EXIT', 'ARGP_NO_ERRS', and 'ARGP_NO_HELP'. |
| |
| |
| File: libc.info, Node: Argp Help Filtering, Prev: Argp Children, Up: Argp Parsers |
| |
| 25.3.8 Customizing Argp Help Output |
| ----------------------------------- |
| |
| The 'help_filter' field in a 'struct argp' is a pointer to a function |
| that filters the text of help messages before displaying them. They |
| have a function signature like: |
| |
| char *HELP-FILTER (int KEY, const char *TEXT, void *INPUT) |
| |
| Where KEY is either a key from an option, in which case TEXT is that |
| option's help text. *Note Argp Option Vectors::. Alternately, one of |
| the special keys with names beginning with 'ARGP_KEY_HELP_' might be |
| used, describing which other help text TEXT will contain. *Note Argp |
| Help Filter Keys::. |
| |
| The function should return either TEXT if it remains as-is, or a |
| replacement string allocated using 'malloc'. This will be either be |
| freed by argp or zero, which prints nothing. The value of TEXT is |
| supplied _after_ any translation has been done, so if any of the |
| replacement text needs translation, it will be done by the filter |
| function. INPUT is either the input supplied to 'argp_parse' or it is |
| zero, if 'argp_help' was called directly by the user. |
| |
| * Menu: |
| |
| * Keys: Argp Help Filter Keys. Special KEY values for help filter functions. |
| |
| |
| File: libc.info, Node: Argp Help Filter Keys, Up: Argp Help Filtering |
| |
| 25.3.8.1 Special Keys for Argp Help Filter Functions |
| .................................................... |
| |
| The following special values may be passed to an argp help filter |
| function as the first argument in addition to key values for user |
| options. They specify which help text the TEXT argument contains: |
| |
| 'ARGP_KEY_HELP_PRE_DOC' |
| The help text preceding options. |
| |
| 'ARGP_KEY_HELP_POST_DOC' |
| The help text following options. |
| |
| 'ARGP_KEY_HELP_HEADER' |
| The option header string. |
| |
| 'ARGP_KEY_HELP_EXTRA' |
| This is used after all other documentation; TEXT is zero for this |
| key. |
| |
| 'ARGP_KEY_HELP_DUP_ARGS_NOTE' |
| The explanatory note printed when duplicate option arguments have |
| been suppressed. |
| |
| 'ARGP_KEY_HELP_ARGS_DOC' |
| The argument doc string; formally the 'args_doc' field from the |
| argp parser. *Note Argp Parsers::. |
| |
| |
| File: libc.info, Node: Argp Help, Next: Argp Examples, Prev: Argp Flags, Up: Argp |
| |
| 25.3.9 The 'argp_help' Function |
| ------------------------------- |
| |
| Normally programs using argp need not be written with particular |
| printing argument-usage-type help messages in mind as the standard |
| '--help' option is handled automatically by argp. Typical error cases |
| can be handled using 'argp_usage' and 'argp_error'. *Note Argp Helper |
| Functions::. However, if it's desirable to print a help message in some |
| context other than parsing the program options, argp offers the |
| 'argp_help' interface. |
| |
| -- Function: void argp_help (const struct argp *ARGP, FILE *STREAM, |
| unsigned FLAGS, char *NAME) |
| Preliminary: | MT-Unsafe race:argpbuf env locale | AS-Unsafe heap |
| i18n corrupt | AC-Unsafe mem corrupt lock | *Note POSIX Safety |
| Concepts::. |
| |
| This outputs a help message for the argp parser ARGP to STREAM. |
| The type of messages printed will be determined by FLAGS. |
| |
| Any options such as '--help' that are implemented automatically by |
| argp itself will _not_ be present in the help output; for this |
| reason it is best to use 'argp_state_help' if calling from within |
| an argp parser function. *Note Argp Helper Functions::. |
| |
| * Menu: |
| |
| * Flags: Argp Help Flags. Specifying what sort of help message to print. |
| |
| |
| File: libc.info, Node: Argp Help Flags, Up: Argp Help |
| |
| 25.3.10 Flags for the 'argp_help' Function |
| ------------------------------------------ |
| |
| When calling 'argp_help' (*note Argp Help::) or 'argp_state_help' (*note |
| Argp Helper Functions::) the exact output is determined by the FLAGS |
| argument. This should consist of any of the following flags, or'd |
| together: |
| |
| 'ARGP_HELP_USAGE' |
| A unix 'Usage:' message that explicitly lists all options. |
| |
| 'ARGP_HELP_SHORT_USAGE' |
| A unix 'Usage:' message that displays an appropriate placeholder to |
| indicate where the options go; useful for showing the non-option |
| argument syntax. |
| |
| 'ARGP_HELP_SEE' |
| A 'Try ... for more help' message; '...' contains the program name |
| and '--help'. |
| |
| 'ARGP_HELP_LONG' |
| A verbose option help message that gives each option available |
| along with its documentation string. |
| |
| 'ARGP_HELP_PRE_DOC' |
| The part of the argp parser doc string preceding the verbose option |
| help. |
| |
| 'ARGP_HELP_POST_DOC' |
| The part of the argp parser doc string that following the verbose |
| option help. |
| |
| 'ARGP_HELP_DOC' |
| '(ARGP_HELP_PRE_DOC | ARGP_HELP_POST_DOC)' |
| |
| 'ARGP_HELP_BUG_ADDR' |
| A message that prints where to report bugs for this program, if the |
| 'argp_program_bug_address' variable contains this information. |
| |
| 'ARGP_HELP_LONG_ONLY' |
| This will modify any output to reflect the 'ARGP_LONG_ONLY' mode. |
| |
| The following flags are only understood when used with |
| 'argp_state_help'. They control whether the function returns after |
| printing its output, or terminates the program: |
| |
| 'ARGP_HELP_EXIT_ERR' |
| This will terminate the program with 'exit (argp_err_exit_status)'. |
| |
| 'ARGP_HELP_EXIT_OK' |
| This will terminate the program with 'exit (0)'. |
| |
| The following flags are combinations of the basic flags for printing |
| standard messages: |
| |
| 'ARGP_HELP_STD_ERR' |
| Assuming that an error message for a parsing error has printed, |
| this prints a message on how to get help, and terminates the |
| program with an error. |
| |
| 'ARGP_HELP_STD_USAGE' |
| This prints a standard usage message and terminates the program |
| with an error. This is used when no other specific error messages |
| are appropriate or available. |
| |
| 'ARGP_HELP_STD_HELP' |
| This prints the standard response for a '--help' option, and |
| terminates the program successfully. |
| |
