| This is /home/vagrant/rpmbuild/BUILD/build-eglibc/manual/libc.info, |
| produced by makeinfo version 4.13 from libc.texinfo. |
| |
| 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. |
| * 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. |
| * 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_getattr_default_np: (libc)Default Thread Attributes. |
| * 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. |
| * 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 |
| |
| This file documents the GNU C Library. |
| |
| This is `The GNU C Library Reference Manual', for version |
| 2.18-2013.10 (EGLIBC). |
| |
| Copyright (C) 1993-2013 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." |
| |
| |
| File: libc.info, Node: Limits on Resources, Next: Priority, Prev: Resource Usage, Up: Resource Usage And Limitation |
| |
| 22.2 Limiting Resource Usage |
| ============================ |
| |
| You can specify limits for the resource usage of a process. When the |
| process tries to exceed a limit, it may get a signal, or the system call |
| by which it tried to do so may fail, depending on the resource. Each |
| process initially inherits its limit values from its parent, but it can |
| subsequently change them. |
| |
| There are two per-process limits associated with a resource: |
| |
| "current limit" |
| The current limit is the value the system will not allow usage to |
| exceed. It is also called the "soft limit" because the process |
| being limited can generally raise the current limit at will. |
| |
| "maximum limit" |
| The maximum limit is the maximum value to which a process is |
| allowed to set its current limit. It is also called the "hard |
| limit" because there is no way for a process to get around it. A |
| process may lower its own maximum limit, but only the superuser |
| may increase a maximum limit. |
| |
| The symbols for use with `getrlimit', `setrlimit', `getrlimit64', |
| and `setrlimit64' are defined in `sys/resource.h'. |
| |
| -- Function: int getrlimit (int RESOURCE, struct rlimit *RLP) |
| Read the current and maximum limits for the resource RESOURCE and |
| store them in `*RLP'. |
| |
| The return value is `0' on success and `-1' on failure. The only |
| possible `errno' error condition is `EFAULT'. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' on a |
| 32-bit system this function is in fact `getrlimit64'. Thus, the |
| LFS interface transparently replaces the old interface. |
| |
| -- Function: int getrlimit64 (int RESOURCE, struct rlimit64 *RLP) |
| This function is similar to `getrlimit' but its second parameter is |
| a pointer to a variable of type `struct rlimit64', which allows it |
| to read values which wouldn't fit in the member of a `struct |
| rlimit'. |
| |
| If the sources are compiled with `_FILE_OFFSET_BITS == 64' on a |
| 32-bit machine, this function is available under the name |
| `getrlimit' and so transparently replaces the old interface. |
| |
| -- Function: int setrlimit (int RESOURCE, const struct rlimit *RLP) |
| Store the current and maximum limits for the resource RESOURCE in |
| `*RLP'. |
| |
| The return value is `0' on success and `-1' on failure. The |
| following `errno' error condition is possible: |
| |
| `EPERM' |
| * The process tried to raise a current limit beyond the |
| maximum limit. |
| |
| * The process tried to raise a maximum limit, but is not |
| superuser. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' on a |
| 32-bit system this function is in fact `setrlimit64'. Thus, the |
| LFS interface transparently replaces the old interface. |
| |
| -- Function: int setrlimit64 (int RESOURCE, const struct rlimit64 *RLP) |
| This function is similar to `setrlimit' but its second parameter is |
| a pointer to a variable of type `struct rlimit64' which allows it |
| to set values which wouldn't fit in the member of a `struct |
| rlimit'. |
| |
| If the sources are compiled with `_FILE_OFFSET_BITS == 64' on a |
| 32-bit machine this function is available under the name |
| `setrlimit' and so transparently replaces the old interface. |
| |
| -- Data Type: struct rlimit |
| This structure is used with `getrlimit' to receive limit values, |
| and with `setrlimit' to specify limit values for a particular |
| process and resource. It has two fields: |
| |
| `rlim_t rlim_cur' |
| The current limit |
| |
| `rlim_t rlim_max' |
| The maximum limit. |
| |
| For `getrlimit', the structure is an output; it receives the |
| current values. For `setrlimit', it specifies the new values. |
| |
| For the LFS functions a similar type is defined in `sys/resource.h'. |
| |
| -- Data Type: struct rlimit64 |
| This structure is analogous to the `rlimit' structure above, but |
| its components have wider ranges. It has two fields: |
| |
| `rlim64_t rlim_cur' |
| This is analogous to `rlimit.rlim_cur', but with a different |
| type. |
| |
| `rlim64_t rlim_max' |
| This is analogous to `rlimit.rlim_max', but with a different |
| type. |
| |
| |
| Here is a list of resources for which you can specify a limit. |
| Memory and file sizes are measured in bytes. |
| |
| `RLIMIT_CPU' |
| The maximum amount of CPU time the process can use. If it runs for |
| longer than this, it gets a signal: `SIGXCPU'. The value is |
| measured in seconds. *Note Operation Error Signals::. |
| |
| `RLIMIT_FSIZE' |
| The maximum size of file the process can create. Trying to write a |
| larger file causes a signal: `SIGXFSZ'. *Note Operation Error |
| Signals::. |
| |
| `RLIMIT_DATA' |
| The maximum size of data memory for the process. If the process |
| tries to allocate data memory beyond this amount, the allocation |
| function fails. |
| |
| `RLIMIT_STACK' |
| The maximum stack size for the process. If the process tries to |
| extend its stack past this size, it gets a `SIGSEGV' signal. |
| *Note Program Error Signals::. |
| |
| `RLIMIT_CORE' |
| The maximum size core file that this process can create. If the |
| process terminates and would dump a core file larger than this, |
| then no core file is created. So setting this limit to zero |
| prevents core files from ever being created. |
| |
| `RLIMIT_RSS' |
| The maximum amount of physical memory that this process should get. |
| This parameter is a guide for the system's scheduler and memory |
| allocator; the system may give the process more memory when there |
| is a surplus. |
| |
| `RLIMIT_MEMLOCK' |
| The maximum amount of memory that can be locked into physical |
| memory (so it will never be paged out). |
| |
| `RLIMIT_NPROC' |
| The maximum number of processes that can be created with the same |
| user ID. If you have reached the limit for your user ID, `fork' |
| will fail with `EAGAIN'. *Note Creating a Process::. |
| |
| `RLIMIT_NOFILE' |
| `RLIMIT_OFILE' |
| The maximum number of files that the process can open. If it |
| tries to open more files than this, its open attempt fails with |
| `errno' `EMFILE'. *Note Error Codes::. Not all systems support |
| this limit; GNU does, and 4.4 BSD does. |
| |
| `RLIMIT_AS' |
| The maximum size of total memory that this process should get. If |
| the process tries to allocate more memory beyond this amount with, |
| for example, `brk', `malloc', `mmap' or `sbrk', the allocation |
| function fails. |
| |
| `RLIM_NLIMITS' |
| The number of different resource limits. Any valid RESOURCE |
| operand must be less than `RLIM_NLIMITS'. |
| |
| -- Constant: rlim_t RLIM_INFINITY |
| This constant stands for a value of "infinity" when supplied as |
| the limit value in `setrlimit'. |
| |
| The following are historical functions to do some of what the |
| functions above do. The functions above are better choices. |
| |
| `ulimit' and the command symbols are declared in `ulimit.h'. |
| |
| -- Function: long int ulimit (int CMD, ...) |
| `ulimit' gets the current limit or sets the current and maximum |
| limit for a particular resource for the calling process according |
| to the command CMD.a |
| |
| If you are getting a limit, the command argument is the only |
| argument. If you are setting a limit, there is a second argument: |
| `long int' LIMIT which is the value to which you are setting the |
| limit. |
| |
| The CMD values and the operations they specify are: |
| `GETFSIZE' |
| Get the current limit on the size of a file, in units of 512 |
| bytes. |
| |
| `SETFSIZE' |
| Set the current and maximum limit on the size of a file to |
| LIMIT * 512 bytes. |
| |
| |
| There are also some other CMD values that may do things on some |
| systems, but they are not supported. |
| |
| Only the superuser may increase a maximum limit. |
| |
| When you successfully get a limit, the return value of `ulimit' is |
| that limit, which is never negative. When you successfully set a |
| limit, the return value is zero. When the function fails, the |
| return value is `-1' and `errno' is set according to the reason: |
| |
| `EPERM' |
| A process tried to increase a maximum limit, but is not |
| superuser. |
| |
| |
| `vlimit' and its resource symbols are declared in `sys/vlimit.h'. |
| |
| -- Function: int vlimit (int RESOURCE, int LIMIT) |
| `vlimit' sets the current limit for a resource for a process. |
| |
| RESOURCE identifies the resource: |
| |
| `LIM_CPU' |
| Maximum CPU time. Same as `RLIMIT_CPU' for `setrlimit'. |
| |
| `LIM_FSIZE' |
| Maximum file size. Same as `RLIMIT_FSIZE' for `setrlimit'. |
| |
| `LIM_DATA' |
| Maximum data memory. Same as `RLIMIT_DATA' for `setrlimit'. |
| |
| `LIM_STACK' |
| Maximum stack size. Same as `RLIMIT_STACK' for `setrlimit'. |
| |
| `LIM_CORE' |
| Maximum core file size. Same as `RLIMIT_COR' for `setrlimit'. |
| |
| `LIM_MAXRSS' |
| Maximum physical memory. Same as `RLIMIT_RSS' for |
| `setrlimit'. |
| |
| The return value is zero for success, and `-1' with `errno' set |
| accordingly for failure: |
| |
| `EPERM' |
| The process tried to set its current limit beyond its maximum |
| limit. |
| |
| |
| |
| File: libc.info, Node: Priority, Next: Memory Resources, Prev: Limits on Resources, Up: Resource Usage And Limitation |
| |
| 22.3 Process CPU Priority And Scheduling |
| ======================================== |
| |
| When multiple processes simultaneously require CPU time, the system's |
| scheduling policy and process CPU priorities determine which processes |
| get it. This section describes how that determination is made and GNU |
| C Library functions to control it. |
| |
| It is common to refer to CPU scheduling simply as scheduling and a |
| process' CPU priority simply as the process' priority, with the CPU |
| resource being implied. Bear in mind, though, that CPU time is not the |
| only resource a process uses or that processes contend for. In some |
| cases, it is not even particularly important. Giving a process a high |
| "priority" may have very little effect on how fast a process runs with |
| respect to other processes. The priorities discussed in this section |
| apply only to CPU time. |
| |
| CPU scheduling is a complex issue and different systems do it in |
| wildly different ways. New ideas continually develop and find their |
| way into the intricacies of the various systems' scheduling algorithms. |
| This section discusses the general concepts, some specifics of systems |
| that commonly use the GNU C Library, and some standards. |
| |
| For simplicity, we talk about CPU contention as if there is only one |
| CPU in the system. But all the same principles apply when a processor |
| has multiple CPUs, and knowing that the number of processes that can |
| run at any one time is equal to the number of CPUs, you can easily |
| extrapolate the information. |
| |
| The functions described in this section are all defined by the |
| POSIX.1 and POSIX.1b standards (the `sched...' functions are POSIX.1b). |
| However, POSIX does not define any semantics for the values that these |
| functions get and set. In this chapter, the semantics are based on the |
| Linux kernel's implementation of the POSIX standard. As you will see, |
| the Linux implementation is quite the inverse of what the authors of the |
| POSIX syntax had in mind. |
| |
| * Menu: |
| |
| * Absolute Priority:: The first tier of priority. Posix |
| * Realtime Scheduling:: Scheduling among the process nobility |
| * Basic Scheduling Functions:: Get/set scheduling policy, priority |
| * Traditional Scheduling:: Scheduling among the vulgar masses |
| * CPU Affinity:: Limiting execution to certain CPUs |
| |
| |
| File: libc.info, Node: Absolute Priority, Next: Realtime Scheduling, Up: Priority |
| |
| 22.3.1 Absolute Priority |
| ------------------------ |
| |
| Every process has an absolute priority, and it is represented by a |
| number. The higher the number, the higher the absolute priority. |
| |
| On systems of the past, and most systems today, all processes have |
| absolute priority 0 and this section is irrelevant. In that case, |
| *Note Traditional Scheduling::. Absolute priorities were invented to |
| accommodate realtime systems, in which it is vital that certain |
| processes be able to respond to external events happening in real time, |
| which means they cannot wait around while some other process that _wants |
| to_, but doesn't _need to_ run occupies the CPU. |
| |
| When two processes are in contention to use the CPU at any instant, |
| the one with the higher absolute priority always gets it. This is true |
| even if the process with the lower priority is already using the CPU |
| (i.e., the scheduling is preemptive). Of course, we're only talking |
| about processes that are running or "ready to run," which means they are |
| ready to execute instructions right now. When a process blocks to wait |
| for something like I/O, its absolute priority is irrelevant. |
| |
| *NB:* The term "runnable" is a synonym for "ready to run." |
| |
| When two processes are running or ready to run and both have the same |
| absolute priority, it's more interesting. In that case, who gets the |
| CPU is determined by the scheduling policy. If the processes have |
| absolute priority 0, the traditional scheduling policy described in |
| *note Traditional Scheduling:: applies. Otherwise, the policies |
| described in *note Realtime Scheduling:: apply. |
| |
| You normally give an absolute priority above 0 only to a process that |
| can be trusted not to hog the CPU. Such processes are designed to block |
| (or terminate) after relatively short CPU runs. |
| |
| A process begins life with the same absolute priority as its parent |
| process. Functions described in *note Basic Scheduling Functions:: can |
| change it. |
| |
| Only a privileged process can change a process' absolute priority to |
| something other than `0'. Only a privileged process or the target |
| process' owner can change its absolute priority at all. |
| |
| POSIX requires absolute priority values used with the realtime |
| scheduling policies to be consecutive with a range of at least 32. On |
| Linux, they are 1 through 99. The functions `sched_get_priority_max' |
| and `sched_set_priority_min' portably tell you what the range is on a |
| particular system. |
| |
| 22.3.1.1 Using Absolute Priority |
| ................................ |
| |
| One thing you must keep in mind when designing real time applications is |
| that having higher absolute priority than any other process doesn't |
| guarantee the process can run continuously. Two things that can wreck a |
| good CPU run are interrupts and page faults. |
| |
| Interrupt handlers live in that limbo between processes. The CPU is |
| executing instructions, but they aren't part of any process. An |
| interrupt will stop even the highest priority process. So you must |
| allow for slight delays and make sure that no device in the system has |
| an interrupt handler that could cause too long a delay between |
| instructions for your process. |
| |
| Similarly, a page fault causes what looks like a straightforward |
| sequence of instructions to take a long time. The fact that other |
| processes get to run while the page faults in is of no consequence, |
| because as soon as the I/O is complete, the high priority process will |
| kick them out and run again, but the wait for the I/O itself could be a |
| problem. To neutralize this threat, use `mlock' or `mlockall'. |
| |
| There are a few ramifications of the absoluteness of this priority |
| on a single-CPU system that you need to keep in mind when you choose to |
| set a priority and also when you're working on a program that runs with |
| high absolute priority. Consider a process that has higher absolute |
| priority than any other process in the system and due to a bug in its |
| program, it gets into an infinite loop. It will never cede the CPU. |
| You can't run a command to kill it because your command would need to |
| get the CPU in order to run. The errant program is in complete |
| control. It controls the vertical, it controls the horizontal. |
| |
| There are two ways to avoid this: 1) keep a shell running somewhere |
| with a higher absolute priority. 2) keep a controlling terminal |
| attached to the high priority process group. All the priority in the |
| world won't stop an interrupt handler from running and delivering a |
| signal to the process if you hit Control-C. |
| |
| Some systems use absolute priority as a means of allocating a fixed |
| percentage of CPU time to a process. To do this, a super high priority |
| privileged process constantly monitors the process' CPU usage and raises |
| its absolute priority when the process isn't getting its entitled share |
| and lowers it when the process is exceeding it. |
| |
| *NB:* The absolute priority is sometimes called the "static |
| priority." We don't use that term in this manual because it misses the |
| most important feature of the absolute priority: its absoluteness. |
| |
| |
| File: libc.info, Node: Realtime Scheduling, Next: Basic Scheduling Functions, Prev: Absolute Priority, Up: Priority |
| |
| 22.3.2 Realtime Scheduling |
| -------------------------- |
| |
| Whenever two processes with the same absolute priority are ready to run, |
| the kernel has a decision to make, because only one can run at a time. |
| If the processes have absolute priority 0, the kernel makes this |
| decision as described in *note Traditional Scheduling::. Otherwise, |
| the decision is as described in this section. |
| |
| If two processes are ready to run but have different absolute |
| priorities, the decision is much simpler, and is described in *note |
| Absolute Priority::. |
| |
| Each process has a scheduling policy. For processes with absolute |
| priority other than zero, there are two available: |
| |
| 1. First Come First Served |
| |
| 2. Round Robin |
| |
| The most sensible case is where all the processes with a certain |
| absolute priority have the same scheduling policy. We'll discuss that |
| first. |
| |
| In Round Robin, processes share the CPU, each one running for a small |
| quantum of time ("time slice") and then yielding to another in a |
| circular fashion. Of course, only processes that are ready to run and |
| have the same absolute priority are in this circle. |
| |
| In First Come First Served, the process that has been waiting the |
| longest to run gets the CPU, and it keeps it until it voluntarily |
| relinquishes the CPU, runs out of things to do (blocks), or gets |
| preempted by a higher priority process. |
| |
| First Come First Served, along with maximal absolute priority and |
| careful control of interrupts and page faults, is the one to use when a |
| process absolutely, positively has to run at full CPU speed or not at |
| all. |
| |
| Judicious use of `sched_yield' function invocations by processes |
| with First Come First Served scheduling policy forms a good compromise |
| between Round Robin and First Come First Served. |
| |
| To understand how scheduling works when processes of different |
| scheduling policies occupy the same absolute priority, you have to know |
| the nitty gritty details of how processes enter and exit the ready to |
| run list: |
| |
| In both cases, the ready to run list is organized as a true queue, |
| where a process gets pushed onto the tail when it becomes ready to run |
| and is popped off the head when the scheduler decides to run it. Note |
| that ready to run and running are two mutually exclusive states. When |
| the scheduler runs a process, that process is no longer ready to run |
| and no longer in the ready to run list. When the process stops |
| running, it may go back to being ready to run again. |
| |
| The only difference between a process that is assigned the Round |
| Robin scheduling policy and a process that is assigned First Come First |
| Serve is that in the former case, the process is automatically booted |
| off the CPU after a certain amount of time. When that happens, the |
| process goes back to being ready to run, which means it enters the |
| queue at the tail. The time quantum we're talking about is small. |
| Really small. This is not your father's timesharing. For example, |
| with the Linux kernel, the round robin time slice is a thousand times |
| shorter than its typical time slice for traditional scheduling. |
| |
| A process begins life with the same scheduling policy as its parent |
| process. Functions described in *note Basic Scheduling Functions:: can |
| change it. |
| |
| Only a privileged process can set the scheduling policy of a process |
| that has absolute priority higher than 0. |
| |
| |
| File: libc.info, Node: Basic Scheduling Functions, Next: Traditional Scheduling, Prev: Realtime Scheduling, Up: Priority |
| |
| 22.3.3 Basic Scheduling Functions |
| --------------------------------- |
| |
| This section describes functions in the GNU C Library for setting the |
| absolute priority and scheduling policy of a process. |
| |
| *Portability Note:* On systems that have the functions in this |
| section, the macro _POSIX_PRIORITY_SCHEDULING is defined in |
| `<unistd.h>'. |
| |
| For the case that the scheduling policy is traditional scheduling, |
| more functions to fine tune the scheduling are in *note Traditional |
| Scheduling::. |
| |
| Don't try to make too much out of the naming and structure of these |
| functions. They don't match the concepts described in this manual |
| because the functions are as defined by POSIX.1b, but the implementation |
| on systems that use the GNU C Library is the inverse of what the POSIX |
| structure contemplates. The POSIX scheme assumes that the primary |
| scheduling parameter is the scheduling policy and that the priority |
| value, if any, is a parameter of the scheduling policy. In the |
| implementation, though, the priority value is king and the scheduling |
| policy, if anything, only fine tunes the effect of that priority. |
| |
| The symbols in this section are declared by including file `sched.h'. |
| |
| -- Data Type: struct sched_param |
| This structure describes an absolute priority. |
| `int sched_priority' |
| absolute priority value |
| |
| -- Function: int sched_setscheduler (pid_t PID, int POLICY, const |
| struct sched_param *PARAM) |
| This function sets both the absolute priority and the scheduling |
| policy for a process. |
| |
| It assigns the absolute priority value given by PARAM and the |
| scheduling policy POLICY to the process with Process ID PID, or |
| the calling process if PID is zero. If POLICY is negative, |
| `sched_setscheduler' keeps the existing scheduling policy. |
| |
| The following macros represent the valid values for POLICY: |
| |
| `SCHED_OTHER' |
| Traditional Scheduling |
| |
| `SCHED_FIFO' |
| First In First Out |
| |
| `SCHED_RR' |
| Round Robin |
| |
| On success, the return value is `0'. Otherwise, it is `-1' and |
| `ERRNO' is set accordingly. The `errno' values specific to this |
| function are: |
| |
| `EPERM' |
| * The calling process does not have `CAP_SYS_NICE' |
| permission and POLICY is not `SCHED_OTHER' (or it's |
| negative and the existing policy is not `SCHED_OTHER'. |
| |
| * The calling process does not have `CAP_SYS_NICE' |
| permission and its owner is not the target process' |
| owner. I.e., the effective uid of the calling process |
| is neither the effective nor the real uid of process PID. |
| |
| `ESRCH' |
| There is no process with pid PID and PID is not zero. |
| |
| `EINVAL' |
| * POLICY does not identify an existing scheduling policy. |
| |
| * The absolute priority value identified by *PARAM is |
| outside the valid range for the scheduling policy POLICY |
| (or the existing scheduling policy if POLICY is |
| negative) or PARAM is null. `sched_get_priority_max' |
| and `sched_get_priority_min' tell you what the valid |
| range is. |
| |
| * PID is negative. |
| |
| |
| -- Function: int sched_getscheduler (pid_t PID) |
| This function returns the scheduling policy assigned to the |
| process with Process ID (pid) PID, or the calling process if PID |
| is zero. |
| |
| The return value is the scheduling policy. See |
| `sched_setscheduler' for the possible values. |
| |
| If the function fails, the return value is instead `-1' and |
| `errno' is set accordingly. |
| |
| The `errno' values specific to this function are: |
| |
| `ESRCH' |
| There is no process with pid PID and it is not zero. |
| |
| `EINVAL' |
| PID is negative. |
| |
| |
| Note that this function is not an exact mate to |
| `sched_setscheduler' because while that function sets the |
| scheduling policy and the absolute priority, this function gets |
| only the scheduling policy. To get the absolute priority, use |
| `sched_getparam'. |
| |
| |
| -- Function: int sched_setparam (pid_t PID, const struct sched_param |
| *PARAM) |
| This function sets a process' absolute priority. |
| |
| It is functionally identical to `sched_setscheduler' with POLICY = |
| `-1'. |
| |
| |
| -- Function: int sched_getparam (pid_t PID, struct sched_param *PARAM) |
| This function returns a process' absolute priority. |
| |
| PID is the Process ID (pid) of the process whose absolute priority |
| you want to know. |
| |
| PARAM is a pointer to a structure in which the function stores the |
| absolute priority of the process. |
| |
| On success, the return value is `0'. Otherwise, it is `-1' and |
| `ERRNO' is set accordingly. The `errno' values specific to this |
| function are: |
| |
| `ESRCH' |
| There is no process with pid PID and it is not zero. |
| |
| `EINVAL' |
| PID is negative. |
| |
| |
| |
| -- Function: int sched_get_priority_min (int POLICY) |
| This function returns the lowest absolute priority value that is |
| allowable for a process with scheduling policy POLICY. |
| |
| On Linux, it is 0 for SCHED_OTHER and 1 for everything else. |
| |
| On success, the return value is `0'. Otherwise, it is `-1' and |
| `ERRNO' is set accordingly. The `errno' values specific to this |
| function are: |
| |
| `EINVAL' |
| POLICY does not identify an existing scheduling policy. |
| |
| |
| -- Function: int sched_get_priority_max (int POLICY) |
| This function returns the highest absolute priority value that is |
| allowable for a process that with scheduling policy POLICY. |
| |
| On Linux, it is 0 for SCHED_OTHER and 99 for everything else. |
| |
| On success, the return value is `0'. Otherwise, it is `-1' and |
| `ERRNO' is set accordingly. The `errno' values specific to this |
| function are: |
| |
| `EINVAL' |
| POLICY does not identify an existing scheduling policy. |
| |
| |
| -- Function: int sched_rr_get_interval (pid_t PID, struct timespec |
| *INTERVAL) |
| This function returns the length of the quantum (time slice) used |
| with the Round Robin scheduling policy, if it is used, for the |
| process with Process ID PID. |
| |
| It returns the length of time as INTERVAL. |
| |
| With a Linux kernel, the round robin time slice is always 150 |
| microseconds, and PID need not even be a real pid. |
| |
| The return value is `0' on success and in the pathological case |
| that it fails, the return value is `-1' and `errno' is set |
| accordingly. There is nothing specific that can go wrong with this |
| function, so there are no specific `errno' values. |
| |
| |
| -- Function: int sched_yield (void) |
| This function voluntarily gives up the process' claim on the CPU. |
| |
| Technically, `sched_yield' causes the calling process to be made |
| immediately ready to run (as opposed to running, which is what it |
| was before). This means that if it has absolute priority higher |
| than 0, it gets pushed onto the tail of the queue of processes |
| that share its absolute priority and are ready to run, and it will |
| run again when its turn next arrives. If its absolute priority is |
| 0, it is more complicated, but still has the effect of yielding |
| the CPU to other processes. |
| |
| If there are no other processes that share the calling process' |
| absolute priority, this function doesn't have any effect. |
| |
| To the extent that the containing program is oblivious to what |
| other processes in the system are doing and how fast it executes, |
| this function appears as a no-op. |
| |
| The return value is `0' on success and in the pathological case |
| that it fails, the return value is `-1' and `errno' is set |
| accordingly. There is nothing specific that can go wrong with this |
| function, so there are no specific `errno' values. |
| |
| |
| |
| File: libc.info, Node: Traditional Scheduling, Next: CPU Affinity, Prev: Basic Scheduling Functions, Up: Priority |
| |
| 22.3.4 Traditional Scheduling |
| ----------------------------- |
| |
| This section is about the scheduling among processes whose absolute |
| priority is 0. When the system hands out the scraps of CPU time that |
| are left over after the processes with higher absolute priority have |
| taken all they want, the scheduling described herein determines who |
| among the great unwashed processes gets them. |
| |
| * Menu: |
| |
| * Traditional Scheduling Intro:: |
| * Traditional Scheduling Functions:: |
| |
| |
| File: libc.info, Node: Traditional Scheduling Intro, Next: Traditional Scheduling Functions, Up: Traditional Scheduling |
| |
| 22.3.4.1 Introduction To Traditional Scheduling |
| ............................................... |
| |
| Long before there was absolute priority (See *note Absolute Priority::), |
| Unix systems were scheduling the CPU using this system. When Posix came |
| in like the Romans and imposed absolute priorities to accommodate the |
| needs of realtime processing, it left the indigenous Absolute Priority |
| Zero processes to govern themselves by their own familiar scheduling |
| policy. |
| |
| Indeed, absolute priorities higher than zero are not available on |
| many systems today and are not typically used when they are, being |
| intended mainly for computers that do realtime processing. So this |
| section describes the only scheduling many programmers need to be |
| concerned about. |
| |
| But just to be clear about the scope of this scheduling: Any time a |
| process with a absolute priority of 0 and a process with an absolute |
| priority higher than 0 are ready to run at the same time, the one with |
| absolute priority 0 does not run. If it's already running when the |
| higher priority ready-to-run process comes into existence, it stops |
| immediately. |
| |
| In addition to its absolute priority of zero, every process has |
| another priority, which we will refer to as "dynamic priority" because |
| it changes over time. The dynamic priority is meaningless for |
| processes with an absolute priority higher than zero. |
| |
| The dynamic priority sometimes determines who gets the next turn on |
| the CPU. Sometimes it determines how long turns last. Sometimes it |
| determines whether a process can kick another off the CPU. |
| |
| In Linux, the value is a combination of these things, but mostly it |
| is just determines the length of the time slice. The higher a process' |
| dynamic priority, the longer a shot it gets on the CPU when it gets one. |
| If it doesn't use up its time slice before giving up the CPU to do |
| something like wait for I/O, it is favored for getting the CPU back when |
| it's ready for it, to finish out its time slice. Other than that, |
| selection of processes for new time slices is basically round robin. |
| But the scheduler does throw a bone to the low priority processes: A |
| process' dynamic priority rises every time it is snubbed in the |
| scheduling process. In Linux, even the fat kid gets to play. |
| |
| The fluctuation of a process' dynamic priority is regulated by |
| another value: The "nice" value. The nice value is an integer, usually |
| in the range -20 to 20, and represents an upper limit on a process' |
| dynamic priority. The higher the nice number, the lower that limit. |
| |
| On a typical Linux system, for example, a process with a nice value |
| of 20 can get only 10 milliseconds on the CPU at a time, whereas a |
| process with a nice value of -20 can achieve a high enough priority to |
| get 400 milliseconds. |
| |
| The idea of the nice value is deferential courtesy. In the |
| beginning, in the Unix garden of Eden, all processes shared equally in |
| the bounty of the computer system. But not all processes really need |
| the same share of CPU time, so the nice value gave a courteous process |
| the ability to refuse its equal share of CPU time that others might |
| prosper. Hence, the higher a process' nice value, the nicer the |
| process is. (Then a snake came along and offered some process a |
| negative nice value and the system became the crass resource allocation |
| system we know today). |
| |
| Dynamic priorities tend upward and downward with an objective of |
| smoothing out allocation of CPU time and giving quick response time to |
| infrequent requests. But they never exceed their nice limits, so on a |
| heavily loaded CPU, the nice value effectively determines how fast a |
| process runs. |
| |
| In keeping with the socialistic heritage of Unix process priority, a |
| process begins life with the same nice value as its parent process and |
| can raise it at will. A process can also raise the nice value of any |
| other process owned by the same user (or effective user). But only a |
| privileged process can lower its nice value. A privileged process can |
| also raise or lower another process' nice value. |
| |
| GNU C Library functions for getting and setting nice values are |
| described in *Note Traditional Scheduling Functions::. |
| |
| |
| File: libc.info, Node: Traditional Scheduling Functions, Prev: Traditional Scheduling Intro, Up: Traditional Scheduling |
| |
| 22.3.4.2 Functions For Traditional Scheduling |
| ............................................. |
| |
| This section describes how you can read and set the nice value of a |
| process. All these symbols are declared in `sys/resource.h'. |
| |
| The function and macro names are defined by POSIX, and refer to |
| "priority," but the functions actually have to do with nice values, as |
| the terms are used both in the manual and POSIX. |
| |
| The range of valid nice values depends on the kernel, but typically |
| it runs from `-20' to `20'. A lower nice value corresponds to higher |
| priority for the process. These constants describe the range of |
| priority values: |
| |
| `PRIO_MIN' |
| The lowest valid nice value. |
| |
| `PRIO_MAX' |
| The highest valid nice value. |
| |
| -- Function: int getpriority (int CLASS, int ID) |
| Return the nice value of a set of processes; CLASS and ID specify |
| which ones (see below). If the processes specified do not all |
| have the same nice value, this returns the lowest value that any |
| of them has. |
| |
| On success, the return value is `0'. Otherwise, it is `-1' and |
| `ERRNO' is set accordingly. The `errno' values specific to this |
| function are: |
| |
| `ESRCH' |
| The combination of CLASS and ID does not match any existing |
| process. |
| |
| `EINVAL' |
| The value of CLASS is not valid. |
| |
| If the return value is `-1', it could indicate failure, or it could |
| be the nice value. The only way to make certain is to set `errno = |
| 0' before calling `getpriority', then use `errno != 0' afterward |
| as the criterion for failure. |
| |
| -- Function: int setpriority (int CLASS, int ID, int NICEVAL) |
| Set the nice value of a set of processes to NICEVAL; CLASS and ID |
| specify which ones (see below). |
| |
| The return value is `0' on success, and `-1' on failure. The |
| following `errno' error condition are possible for this function: |
| |
| `ESRCH' |
| The combination of CLASS and ID does not match any existing |
| process. |
| |
| `EINVAL' |
| The value of CLASS is not valid. |
| |
| `EPERM' |
| The call would set the nice value of a process which is owned |
| by a different user than the calling process (i.e., the |
| target process' real or effective uid does not match the |
| calling process' effective uid) and the calling process does |
| not have `CAP_SYS_NICE' permission. |
| |
| `EACCES' |
| The call would lower the process' nice value and the process |
| does not have `CAP_SYS_NICE' permission. |
| |
| |
| The arguments CLASS and ID together specify a set of processes in |
| which you are interested. These are the possible values of CLASS: |
| |
| `PRIO_PROCESS' |
| One particular process. The argument ID is a process ID (pid). |
| |
| `PRIO_PGRP' |
| All the processes in a particular process group. The argument ID |
| is a process group ID (pgid). |
| |
| `PRIO_USER' |
| All the processes owned by a particular user (i.e., whose real uid |
| indicates the user). The argument ID is a user ID (uid). |
| |
| If the argument ID is 0, it stands for the calling process, its |
| process group, or its owner (real uid), according to CLASS. |
| |
| -- Function: int nice (int INCREMENT) |
| Increment the nice value of the calling process by INCREMENT. The |
| return value is the new nice value on success, and `-1' on |
| failure. In the case of failure, `errno' will be set to the same |
| values as for `setpriority'. |
| |
| Here is an equivalent definition of `nice': |
| |
| int |
| nice (int increment) |
| { |
| int result, old = getpriority (PRIO_PROCESS, 0); |
| result = setpriority (PRIO_PROCESS, 0, old + increment); |
| if (result != -1) |
| return old + increment; |
| else |
| return -1; |
| } |
| |
| |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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 a 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) |
| 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) |
| 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) |
| 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, ...) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| This function initializes the signal set SET to exclude all of the |
| defined signals. It always returns `0'. |
| |
| -- Function: int sigfillset (sigset_t *SET) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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, ...) |
| 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, ...) |
| 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) |
| 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) |
| 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. |
| |
| |
| File: libc.info, Node: Argp Examples, Next: Argp User Customization, Prev: Argp Help, Up: Argp |
| |
| 25.3.11 Argp Examples |
| --------------------- |
| |
| These example programs demonstrate the basic usage of argp. |
| |
| * Menu: |
| |
| * 1: Argp Example 1. A minimal program using argp. |
| * 2: Argp Example 2. A program using only default options. |
| * 3: Argp Example 3. A simple program with user options. |
| * 4: Argp Example 4. Combining multiple argp parsers. |
| |
| |
| File: libc.info, Node: Argp Example 1, Next: Argp Example 2, Up: Argp Examples |
| |
| 25.3.11.1 A Minimal Program Using Argp |
| ...................................... |
| |
| This is perhaps the smallest program possible that uses argp. It won't |
| do much except give an error messages and exit when there are any |
| arguments, and prints a rather pointless message for `--help'. |
| |
| |
| /* This is (probably) the smallest possible program that |
| uses argp. It won't do much except give an error |
| messages and exit when there are any arguments, and print |
| a (rather pointless) messages for -help. */ |
| |
| #include <stdlib.h> |
| #include <argp.h> |
| |
| int |
| main (int argc, char **argv) |
| { |
| argp_parse (0, argc, argv, 0, 0, 0); |
| exit (0); |
| } |
| |
| |
| File: libc.info, Node: Argp Example 2, Next: Argp Example 3, Prev: Argp Example 1, Up: Argp Examples |
| |
| 25.3.11.2 A Program Using Argp with Only Default Options |
| ........................................................ |
| |
| This program doesn't use any options or arguments, it uses argp to be |
| compliant with the GNU standard command line format. |
| |
| In addition to giving no arguments and implementing a `--help' |
| option, this example has a `--version' option, which will put the given |
| documentation string and bug address in the `--help' output, as per GNU |
| standards. |
| |
| The variable `argp' contains the argument parser specification. |
| Adding fields to this structure is the way most parameters are passed |
| to `argp_parse'. The first three fields are normally used, but they |
| are not in this small program. There are also two global variables |
| that argp can use defined here, `argp_program_version' and |
| `argp_program_bug_address'. They are considered global variables |
| because they will almost always be constant for a given program, even |
| if they use different argument parsers for various tasks. |
| |
| |
| /* This program doesn't use any options or arguments, but uses |
| argp to be compliant with the GNU standard command line |
| format. |
| |
| In addition to making sure no arguments are given, and |
| implementing a -help option, this example will have a |
| -version option, and will put the given documentation string |
| and bug address in the -help output, as per GNU standards. |
| |
| The variable ARGP contains the argument parser specification; |
| adding fields to this structure is the way most parameters are |
| passed to argp_parse (the first three fields are usually used, |
| but not in this small program). There are also two global |
| variables that argp knows about defined here, |
| ARGP_PROGRAM_VERSION and ARGP_PROGRAM_BUG_ADDRESS (they are |
| global variables because they will almost always be constant |
| for a given program, even if it uses different argument |
| parsers for various tasks). */ |
| |
| #include <stdlib.h> |
| #include <argp.h> |
| |
| const char *argp_program_version = |
| "argp-ex2 1.0"; |
| const char *argp_program_bug_address = |
| "<bug-gnu-utils@gnu.org>"; |
| |
| /* Program documentation. */ |
| static char doc[] = |
| "Argp example #2 -- a pretty minimal program using argp"; |
| |
| /* Our argument parser. The `options', `parser', and |
| `args_doc' fields are zero because we have neither options or |
| arguments; `doc' and `argp_program_bug_address' will be |
| used in the output for `--help', and the `--version' |
| option will print out `argp_program_version'. */ |
| static struct argp argp = { 0, 0, 0, doc }; |
| |
| int |
| main (int argc, char **argv) |
| { |
| argp_parse (&argp, argc, argv, 0, 0, 0); |
| exit (0); |
| } |
| |
| |
| File: libc.info, Node: Argp Example 3, Next: Argp Example 4, Prev: Argp Example 2, Up: Argp Examples |
| |
| 25.3.11.3 A Program Using Argp with User Options |
| ................................................ |
| |
| This program uses the same features as example 2, adding user options |
| and arguments. |
| |
| We now use the first four fields in `argp' (*note Argp Parsers::) |
| and specify `parse_opt' as the parser function. *Note Argp Parser |
| Functions::. |
| |
| Note that in this example, `main' uses a structure to communicate |
| with the `parse_opt' function, a pointer to which it passes in the |
| `input' argument to `argp_parse'. *Note Argp::. It is retrieved by |
| `parse_opt' through the `input' field in its `state' argument. *Note |
| Argp Parsing State::. Of course, it's also possible to use global |
| variables instead, but using a structure like this is somewhat more |
| flexible and clean. |
| |
| |
| /* This program uses the same features as example 2, and uses options and |
| arguments. |
| |
| We now use the first four fields in ARGP, so here's a description of them: |
| OPTIONS - A pointer to a vector of struct argp_option (see below) |
| PARSER - A function to parse a single option, called by argp |
| ARGS_DOC - A string describing how the non-option arguments should look |
| DOC - A descriptive string about this program; if it contains a |
| vertical tab character (\v), the part after it will be |
| printed *following* the options |
| |
| The function PARSER takes the following arguments: |
| KEY - An integer specifying which option this is (taken |
| from the KEY field in each struct argp_option), or |
| a special key specifying something else; the only |
| special keys we use here are ARGP_KEY_ARG, meaning |
| a non-option argument, and ARGP_KEY_END, meaning |
| that all arguments have been parsed |
| ARG - For an option KEY, the string value of its |
| argument, or NULL if it has none |
| STATE- A pointer to a struct argp_state, containing |
| various useful information about the parsing state; used here |
| are the INPUT field, which reflects the INPUT argument to |
| argp_parse, and the ARG_NUM field, which is the number of the |
| current non-option argument being parsed |
| It should return either 0, meaning success, ARGP_ERR_UNKNOWN, meaning the |
| given KEY wasn't recognized, or an errno value indicating some other |
| error. |
| |
| Note that in this example, main uses a structure to communicate with the |
| parse_opt function, a pointer to which it passes in the INPUT argument to |
| argp_parse. Of course, it's also possible to use global variables |
| instead, but this is somewhat more flexible. |
| |
| The OPTIONS field contains a pointer to a vector of struct argp_option's; |
| that structure has the following fields (if you assign your option |
| structures using array initialization like this example, unspecified |
| fields will be defaulted to 0, and need not be specified): |
| NAME - The name of this option's long option (may be zero) |
| KEY - The KEY to pass to the PARSER function when parsing this option, |
| *and* the name of this option's short option, if it is a |
| printable ascii character |
| ARG - The name of this option's argument, if any |
| FLAGS - Flags describing this option; some of them are: |
| OPTION_ARG_OPTIONAL - The argument to this option is optional |
| OPTION_ALIAS - This option is an alias for the |
| previous option |
| OPTION_HIDDEN - Don't show this option in -help output |
| DOC - A documentation string for this option, shown in -help output |
| |
| An options vector should be terminated by an option with all fields zero. */ |
| |
| #include <stdlib.h> |
| #include <argp.h> |
| |
| const char *argp_program_version = |
| "argp-ex3 1.0"; |
| const char *argp_program_bug_address = |
| "<bug-gnu-utils@gnu.org>"; |
| |
| /* Program documentation. */ |
| static char doc[] = |
| "Argp example #3 -- a program with options and arguments using argp"; |
| |
| /* A description of the arguments we accept. */ |
| static char args_doc[] = "ARG1 ARG2"; |
| |
| /* The options we understand. */ |
| static struct argp_option options[] = { |
| {"verbose", 'v', 0, 0, "Produce verbose output" }, |
| {"quiet", 'q', 0, 0, "Don't produce any output" }, |
| {"silent", 's', 0, OPTION_ALIAS }, |
| {"output", 'o', "FILE", 0, |
| "Output to FILE instead of standard output" }, |
| { 0 } |
| }; |
| |
| /* Used by `main' to communicate with `parse_opt'. */ |
| struct arguments |
| { |
| char *args[2]; /* ARG1 & ARG2 */ |
| int silent, verbose; |
| char *output_file; |
| }; |
| |
| /* Parse a single option. */ |
| static error_t |
| parse_opt (int key, char *arg, struct argp_state *state) |
| { |
| /* Get the INPUT argument from `argp_parse', which we |
| know is a pointer to our arguments structure. */ |
| struct arguments *arguments = state->input; |
| |
| switch (key) |
| { |
| case 'q': case 's': |
| arguments->silent = 1; |
| break; |
| case 'v': |
| arguments->verbose = 1; |
| break; |
| case 'o': |
| arguments->output_file = arg; |
| break; |
| |
| case ARGP_KEY_ARG: |
| if (state->arg_num >= 2) |
| /* Too many arguments. */ |
| argp_usage (state); |
| |
| arguments->args[state->arg_num] = arg; |
| |
| break; |
| |
| case ARGP_KEY_END: |
| if (state->arg_num < 2) |
| /* Not enough arguments. */ |
| argp_usage (state); |
| break; |
| |
| default: |
| return ARGP_ERR_UNKNOWN; |
| } |
| return 0; |
| } |
| |
| /* Our argp parser. */ |
| static struct argp argp = { options, parse_opt, args_doc, doc }; |
| |
| int |
| main (int argc, char **argv) |
| { |
| struct arguments arguments; |
| |
| /* Default values. */ |
| arguments.silent = 0; |
| arguments.verbose = 0; |
| arguments.output_file = "-"; |
| |
| /* Parse our arguments; every option seen by `parse_opt' will |
| be reflected in `arguments'. */ |
| argp_parse (&argp, argc, argv, 0, 0, &arguments); |
| |
| printf ("ARG1 = %s\nARG2 = %s\nOUTPUT_FILE = %s\n" |
| "VERBOSE = %s\nSILENT = %s\n", |
| arguments.args[0], arguments.args[1], |
| arguments.output_file, |
| arguments.verbose ? "yes" : "no", |
| arguments.silent ? "yes" : "no"); |
| |
| exit (0); |
| } |
| |
| |
| File: libc.info, Node: Argp Example 4, Prev: Argp Example 3, Up: Argp Examples |
| |
| 25.3.11.4 A Program Using Multiple Combined Argp Parsers |
| ........................................................ |
| |
| This program uses the same features as example 3, but has more options, |
| and presents more structure in the `--help' output. It also |
| illustrates how you can `steal' the remainder of the input arguments |
| past a certain point for programs that accept a list of items. It also |
| illustrates the KEY value `ARGP_KEY_NO_ARGS', which is only given if no |
| non-option arguments were supplied to the program. *Note Argp Special |
| Keys::. |
| |
| For structuring help output, two features are used: _headers_ and a |
| two part option string. The _headers_ are entries in the options |
| vector. *Note Argp Option Vectors::. The first four fields are zero. |
| The two part documentation string are in the variable `doc', which |
| allows documentation both before and after the options. *Note Argp |
| Parsers::, the two parts of `doc' are separated by a vertical-tab |
| character (`'\v'', or `'\013''). By convention, the documentation |
| before the options is a short string stating what the program does, and |
| after any options it is longer, describing the behavior in more detail. |
| All documentation strings are automatically filled for output, although |
| newlines may be included to force a line break at a particular point. |
| In addition, documentation strings are passed to the `gettext' |
| function, for possible translation into the current locale. |
| |
| |
| /* This program uses the same features as example 3, but has more |
| options, and somewhat more structure in the -help output. It |
| also shows how you can `steal' the remainder of the input |
| arguments past a certain point, for programs that accept a |
| list of items. It also shows the special argp KEY value |
| ARGP_KEY_NO_ARGS, which is only given if no non-option |
| arguments were supplied to the program. |
| |
| For structuring the help output, two features are used, |
| *headers* which are entries in the options vector with the |
| first four fields being zero, and a two part documentation |
| string (in the variable DOC), which allows documentation both |
| before and after the options; the two parts of DOC are |
| separated by a vertical-tab character ('\v', or '\013'). By |
| convention, the documentation before the options is just a |
| short string saying what the program does, and that afterwards |
| is longer, describing the behavior in more detail. All |
| documentation strings are automatically filled for output, |
| although newlines may be included to force a line break at a |
| particular point. All documentation strings are also passed to |
| the `gettext' function, for possible translation into the |
| current locale. */ |
| |
| #include <stdlib.h> |
| #include <error.h> |
| #include <argp.h> |
| |
| const char *argp_program_version = |
| "argp-ex4 1.0"; |
| const char *argp_program_bug_address = |
| "<bug-gnu-utils@prep.ai.mit.edu>"; |
| |
| /* Program documentation. */ |
| static char doc[] = |
| "Argp example #4 -- a program with somewhat more complicated\ |
| options\ |
| \vThis part of the documentation comes *after* the options;\ |
| note that the text is automatically filled, but it's possible\ |
| to force a line-break, e.g.\n<-- here."; |
| |
| /* A description of the arguments we accept. */ |
| static char args_doc[] = "ARG1 [STRING...]"; |
| |
| /* Keys for options without short-options. */ |
| #define OPT_ABORT 1 /* -abort */ |
| |
| /* The options we understand. */ |
| static struct argp_option options[] = { |
| {"verbose", 'v', 0, 0, "Produce verbose output" }, |
| {"quiet", 'q', 0, 0, "Don't produce any output" }, |
| {"silent", 's', 0, OPTION_ALIAS }, |
| {"output", 'o', "FILE", 0, |
| "Output to FILE instead of standard output" }, |
| |
| {0,0,0,0, "The following options should be grouped together:" }, |
| {"repeat", 'r', "COUNT", OPTION_ARG_OPTIONAL, |
| "Repeat the output COUNT (default 10) times"}, |
| {"abort", OPT_ABORT, 0, 0, "Abort before showing any output"}, |
| |
| { 0 } |
| }; |
| |
| /* Used by `main' to communicate with `parse_opt'. */ |
| struct arguments |
| { |
| char *arg1; /* ARG1 */ |
| char **strings; /* [STRING...] */ |
| int silent, verbose, abort; /* `-s', `-v', `--abort' */ |
| char *output_file; /* FILE arg to `--output' */ |
| int repeat_count; /* COUNT arg to `--repeat' */ |
| }; |
| |
| /* Parse a single option. */ |
| static error_t |
| parse_opt (int key, char *arg, struct argp_state *state) |
| { |
| /* Get the `input' argument from `argp_parse', which we |
| know is a pointer to our arguments structure. */ |
| struct arguments *arguments = state->input; |
| |
| switch (key) |
| { |
| case 'q': case 's': |
| arguments->silent = 1; |
| break; |
| case 'v': |
| arguments->verbose = 1; |
| break; |
| case 'o': |
| arguments->output_file = arg; |
| break; |
| case 'r': |
| arguments->repeat_count = arg ? atoi (arg) : 10; |
| break; |
| case OPT_ABORT: |
| arguments->abort = 1; |
| break; |
| |
| case ARGP_KEY_NO_ARGS: |
| argp_usage (state); |
| |
| case ARGP_KEY_ARG: |
| /* Here we know that `state->arg_num == 0', since we |
| force argument parsing to end before any more arguments can |
| get here. */ |
| arguments->arg1 = arg; |
| |
| /* Now we consume all the rest of the arguments. |
| `state->next' is the index in `state->argv' of the |
| next argument to be parsed, which is the first STRING |
| we're interested in, so we can just use |
| `&state->argv[state->next]' as the value for |
| arguments->strings. |
| |
| _In addition_, by setting `state->next' to the end |
| of the arguments, we can force argp to stop parsing here and |
| return. */ |
| arguments->strings = &state->argv[state->next]; |
| state->next = state->argc; |
| |
| break; |
| |
| default: |
| return ARGP_ERR_UNKNOWN; |
| } |
| return 0; |
| } |
| |
| /* Our argp parser. */ |
| static struct argp argp = { options, parse_opt, args_doc, doc }; |
| |
| int |
| main (int argc, char **argv) |
| { |
| int i, j; |
| struct arguments arguments; |
| |
| /* Default values. */ |
| arguments.silent = 0; |
| arguments.verbose = 0; |
| arguments.output_file = "-"; |
| arguments.repeat_count = 1; |
| arguments.abort = 0; |
| |
| /* Parse our arguments; every option seen by `parse_opt' will be |
| reflected in `arguments'. */ |
| argp_parse (&argp, argc, argv, 0, 0, &arguments); |
| |
| if (arguments.abort) |
| error (10, 0, "ABORTED"); |
| |
| for (i = 0; i < arguments.repeat_count; i++) |
| { |
| printf ("ARG1 = %s\n", arguments.arg1); |
| printf ("STRINGS = "); |
| for (j = 0; arguments.strings[j]; j++) |
| printf (j == 0 ? "%s" : ", %s", arguments.strings[j]); |
| printf ("\n"); |
| printf ("OUTPUT_FILE = %s\nVERBOSE = %s\nSILENT = %s\n", |
| arguments.output_file, |
| arguments.verbose ? "yes" : "no", |
| arguments.silent ? "yes" : "no"); |
| } |
| |
| exit (0); |
| } |
| |
| |
| File: libc.info, Node: Argp User Customization, Prev: Argp Examples, Up: Argp |
| |
| 25.3.12 Argp User Customization |
| ------------------------------- |
| |
| The formatting of argp `--help' output may be controlled to some extent |
| by a program's users, by setting the `ARGP_HELP_FMT' environment |
| variable to a comma-separated list of tokens. Whitespace is ignored: |
| |
| `dup-args' |
| `no-dup-args' |
| These turn "duplicate-argument-mode" on or off. In duplicate |
| argument mode, if an option that accepts an argument has multiple |
| names, the argument is shown for each name. Otherwise, it is only |
| shown for the first long option. A note is subsequently printed |
| so the user knows that it applies to other names as well. The |
| default is `no-dup-args', which is less consistent, but prettier. |
| |
| `dup-args-note' |
| |
| `no-dup-args-note' |
| These will enable or disable the note informing the user of |
| suppressed option argument duplication. The default is |
| `dup-args-note'. |
| |
| `short-opt-col=N' |
| This prints the first short option in column N. The default is 2. |
| |
| `long-opt-col=N' |
| This prints the first long option in column N. The default is 6. |
| |
| `doc-opt-col=N' |
| This prints `documentation options' (*note Argp Option Flags::) in |
| column N. The default is 2. |
| |
| `opt-doc-col=N' |
| This prints the documentation for options starting in column N. |
| The default is 29. |
| |
| `header-col=N' |
| This will indent the group headers that document groups of options |
| to column N. The default is 1. |
| |
| `usage-indent=N' |
| This will indent continuation lines in `Usage:' messages to column |
| N. The default is 12. |
| |
| `rmargin=N' |
| This will word wrap help output at or before column N. The default |
| is 79. |
| |
| |
| File: libc.info, Node: Suboptions, Next: Suboptions Example, Prev: Argp, Up: Parsing Program Arguments |
| |
| 25.3.12.1 Parsing of Suboptions |
| ............................... |
| |
| Having a single level of options is sometimes not enough. There might |
| be too many options which have to be available or a set of options is |
| closely related. |
| |
| For this case some programs use suboptions. One of the most |
| prominent programs is certainly `mount'(8). The `-o' option take one |
| argument which itself is a comma separated list of options. To ease the |
| programming of code like this the function `getsubopt' is available. |
| |
| -- Function: int getsubopt (char **OPTIONP, char *const *TOKENS, char |
| **VALUEP) |
| The OPTIONP parameter must be a pointer to a variable containing |
| the address of the string to process. When the function returns |
| the reference is updated to point to the next suboption or to the |
| terminating `\0' character if there is no more suboption available. |
| |
| The TOKENS parameter references an array of strings containing the |
| known suboptions. All strings must be `\0' terminated and to mark |
| the end a null pointer must be stored. When `getsubopt' finds a |
| possible legal suboption it compares it with all strings available |
| in the TOKENS array and returns the index in the string as the |
| indicator. |
| |
| In case the suboption has an associated value introduced by a `=' |
| character, a pointer to the value is returned in VALUEP. The |
| string is `\0' terminated. If no argument is available VALUEP is |
| set to the null pointer. By doing this the caller can check |
| whether a necessary value is given or whether no unexpected value |
| is present. |
| |
| In case the next suboption in the string is not mentioned in the |
| TOKENS array the starting address of the suboption including a |
| possible value is returned in VALUEP and the return value of the |
| function is `-1'. |
| |
| |
| File: libc.info, Node: Suboptions Example, Prev: Suboptions, Up: Parsing Program Arguments |
| |
| 25.3.13 Parsing of Suboptions Example |
| ------------------------------------- |
| |
| The code which might appear in the `mount'(8) program is a perfect |
| example of the use of `getsubopt': |
| |
| |
| #include <stdio.h> |
| #include <stdlib.h> |
| #include <unistd.h> |
| |
| int do_all; |
| const char *type; |
| int read_size; |
| int write_size; |
| int read_only; |
| |
| enum |
| { |
| RO_OPTION = 0, |
| RW_OPTION, |
| READ_SIZE_OPTION, |
| WRITE_SIZE_OPTION, |
| THE_END |
| }; |
| |
| const char *mount_opts[] = |
| { |
| [RO_OPTION] = "ro", |
| [RW_OPTION] = "rw", |
| [READ_SIZE_OPTION] = "rsize", |
| [WRITE_SIZE_OPTION] = "wsize", |
| [THE_END] = NULL |
| }; |
| |
| int |
| main (int argc, char **argv) |
| { |
| char *subopts, *value; |
| int opt; |
| |
| while ((opt = getopt (argc, argv, "at:o:")) != -1) |
| switch (opt) |
| { |
| case 'a': |
| do_all = 1; |
| break; |
| case 't': |
| type = optarg; |
| break; |
| case 'o': |
| subopts = optarg; |
| while (*subopts != '\0') |
| switch (getsubopt (&subopts, mount_opts, &value)) |
| { |
| case RO_OPTION: |
| read_only = 1; |
| break; |
| case RW_OPTION: |
| read_only = 0; |
| break; |
| case READ_SIZE_OPTION: |
| if (value == NULL) |
| abort (); |
| read_size = atoi (value); |
| break; |
| case WRITE_SIZE_OPTION: |
| if (value == NULL) |
| abort (); |
| write_size = atoi (value); |
| break; |
| default: |
| /* Unknown suboption. */ |
| printf ("Unknown suboption `%s'\n", value); |
| break; |
| } |
| break; |
| default: |
| abort (); |
| } |
| |
| /* Do the real work. */ |
| |
| return 0; |
| } |
| |
| |
| File: libc.info, Node: Environment Variables, Next: Auxiliary Vector, Prev: Program Arguments, Up: Program Basics |
| |
| 25.4 Environment Variables |
| ========================== |
| |
| When a program is executed, it receives information about the context in |
| which it was invoked in two ways. The first mechanism uses the ARGV |
| and ARGC arguments to its `main' function, and is discussed in *note |
| Program Arguments::. The second mechanism uses "environment variables" |
| and is discussed in this section. |
| |
| The ARGV mechanism is typically used to pass command-line arguments |
| specific to the particular program being invoked. The environment, on |
| the other hand, keeps track of information that is shared by many |
| programs, changes infrequently, and that is less frequently used. |
| |
| The environment variables discussed in this section are the same |
| environment variables that you set using assignments and the `export' |
| command in the shell. Programs executed from the shell inherit all of |
| the environment variables from the shell. |
| |
| Standard environment variables are used for information about the |
| user's home directory, terminal type, current locale, and so on; you |
| can define additional variables for other purposes. The set of all |
| environment variables that have values is collectively known as the |
| "environment". |
| |
| Names of environment variables are case-sensitive and must not |
| contain the character `='. System-defined environment variables are |
| invariably uppercase. |
| |
| The values of environment variables can be anything that can be |
| represented as a string. A value must not contain an embedded null |
| character, since this is assumed to terminate the string. |
| |
| * Menu: |
| |
| * Environment Access:: How to get and set the values of |
| environment variables. |
| * Standard Environment:: These environment variables have |
| standard interpretations. |
| |
| |
| File: libc.info, Node: Environment Access, Next: Standard Environment, Up: Environment Variables |
| |
| 25.4.1 Environment Access |
| ------------------------- |
| |
| The value of an environment variable can be accessed with the `getenv' |
| function. This is declared in the header file `stdlib.h'. |
| |
| Libraries should use `secure_getenv' instead of `getenv', so that |
| they do not accidentally use untrusted environment variables. |
| Modifications of environment variables are not allowed in |
| multi-threaded programs. The `getenv' and `secure_getenv' functions |
| can be safely used in multi-threaded programs. |
| |
| -- Function: char * getenv (const char *NAME) |
| This function returns a string that is the value of the environment |
| variable NAME. You must not modify this string. In some non-Unix |
| systems not using the GNU C Library, it might be overwritten by |
| subsequent calls to `getenv' (but not by any other library |
| function). If the environment variable NAME is not defined, the |
| value is a null pointer. |
| |
| -- Function: char * secure_getenv (const char *NAME) |
| This function is similar to `getenv', but it returns a null |
| pointer if the environment is untrusted. This happens when the |
| program file has SUID or SGID bits set. General-purpose libraries |
| should always prefer this function over `getenv' to avoid |
| vulnerabilities if the library is referenced from a SUID/SGID |
| program. |
| |
| This function is a GNU extension. |
| |
| -- Function: int putenv (char *STRING) |
| The `putenv' function adds or removes definitions from the |
| environment. If the STRING is of the form `NAME=VALUE', the |
| definition is added to the environment. Otherwise, the STRING is |
| interpreted as the name of an environment variable, and any |
| definition for this variable in the environment is removed. |
| |
| If the function is successful it returns `0'. Otherwise the return |
| value is nonzero and `errno' is set to indicate the error. |
| |
| The difference to the `setenv' function is that the exact string |
| given as the parameter STRING is put into the environment. If the |
| user should change the string after the `putenv' call this will |
| reflect in automatically in the environment. This also requires |
| that STRING is no automatic variable which scope is left before the |
| variable is removed from the environment. The same applies of |
| course to dynamically allocated variables which are freed later. |
| |
| This function is part of the extended Unix interface. Since it |
| was also available in old SVID libraries you should define either |
| _XOPEN_SOURCE or _SVID_SOURCE before including any header. |
| |
| -- Function: int setenv (const char *NAME, const char *VALUE, int |
| REPLACE) |
| The `setenv' function can be used to add a new definition to the |
| environment. The entry with the name NAME is replaced by the |
| value `NAME=VALUE'. Please note that this is also true if VALUE |
| is the empty string. To do this a new string is created and the |
| strings NAME and VALUE are copied. A null pointer for the VALUE |
| parameter is illegal. If the environment already contains an |
| entry with key NAME the REPLACE parameter controls the action. If |
| replace is zero, nothing happens. Otherwise the old entry is |
| replaced by the new one. |
| |
| Please note that you cannot remove an entry completely using this |
| function. |
| |
| If the function is successful it returns `0'. Otherwise the |
| environment is unchanged and the return value is `-1' and `errno' |
| is set. |
| |
| This function was originally part of the BSD library but is now |
| part of the Unix standard. |
| |
| -- Function: int unsetenv (const char *NAME) |
| Using this function one can remove an entry completely from the |
| environment. If the environment contains an entry with the key |
| NAME this whole entry is removed. A call to this function is |
| equivalent to a call to `putenv' when the VALUE part of the string |
| is empty. |
| |
| The function return `-1' if NAME is a null pointer, points to an |
| empty string, or points to a string containing a `=' character. |
| It returns `0' if the call succeeded. |
| |
| This function was originally part of the BSD library but is now |
| part of the Unix standard. The BSD version had no return value, |
| though. |
| |
| There is one more function to modify the whole environment. This |
| function is said to be used in the POSIX.9 (POSIX bindings for Fortran |
| 77) and so one should expect it did made it into POSIX.1. But this |
| never happened. But we still provide this function as a GNU extension |
| to enable writing standard compliant Fortran environments. |
| |
| -- Function: int clearenv (void) |
| The `clearenv' function removes all entries from the environment. |
| Using `putenv' and `setenv' new entries can be added again later. |
| |
| If the function is successful it returns `0'. Otherwise the return |
| value is nonzero. |
| |
| You can deal directly with the underlying representation of |
| environment objects to add more variables to the environment (for |
| example, to communicate with another program you are about to execute; |
| *note Executing a File::). |
| |
| -- Variable: char ** environ |
| The environment is represented as an array of strings. Each |
| string is of the format `NAME=VALUE'. The order in which strings |
| appear in the environment is not significant, but the same NAME |
| must not appear more than once. The last element of the array is |
| a null pointer. |
| |
| This variable is declared in the header file `unistd.h'. |
| |
| If you just want to get the value of an environment variable, use |
| `getenv'. |
| |
| Unix systems, and GNU systems, pass the initial value of `environ' |
| as the third argument to `main'. *Note Program Arguments::. |
| |