| This is |
| /tmp/dgboter/bbs/rhev-vm2--rhe6x86_64/buildbot/rhe6x86_64--aarch64-none-linux-gnu/build/build-aarch64-none-linux-gnu/obj/glibc/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. |
| * CHAR_BIT: (libc)Width of Type. |
| * 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. |
| * 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. |
| * FE_SNANS_ALWAYS_SIGNAL: (libc)Infinity and NaN. |
| * 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. |
| * FP_LLOGB0: (libc)Exponents and Logarithms. |
| * FP_LLOGBNAN: (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_OFD_GETLK: (libc)Open File Description Locks. |
| * F_OFD_SETLK: (libc)Open File Description Locks. |
| * F_OFD_SETLKW: (libc)Open File Description Locks. |
| * 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. |
| * HUGE_VAL_FN: (libc)Math Error Reporting. |
| * HUGE_VAL_FNx: (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_DIRECTORY: (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_TMPFILE: (libc)Open-time Flags. |
| * 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. |
| * SNAN: (libc)Infinity and NaN. |
| * SNANF: (libc)Infinity and NaN. |
| * SNANFN: (libc)Infinity and NaN. |
| * SNANFNx: (libc)Infinity and NaN. |
| * SNANL: (libc)Infinity and NaN. |
| * 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. |
| * 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_high: (libc)PowerPC. |
| * __ppc_set_ppr_med_low: (libc)PowerPC. |
| * __ppc_set_ppr_very_low: (libc)PowerPC. |
| * __ppc_yield: (libc)PowerPC. |
| * __riscv_flush_icache: (libc)RISC-V. |
| * __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. |
| * acosfN: (libc)Inverse Trig Functions. |
| * acosfNx: (libc)Inverse Trig Functions. |
| * acosh: (libc)Hyperbolic Functions. |
| * acoshf: (libc)Hyperbolic Functions. |
| * acoshfN: (libc)Hyperbolic Functions. |
| * acoshfNx: (libc)Hyperbolic Functions. |
| * acoshl: (libc)Hyperbolic Functions. |
| * acosl: (libc)Inverse Trig Functions. |
| * addmntent: (libc)mtab. |
| * addseverity: (libc)Adding Severity Classes. |
| * adjtime: (libc)High-Resolution Calendar. |
| * adjtimex: (libc)High-Resolution Calendar. |
| * aio_cancel64: (libc)Cancel AIO Operations. |
| * aio_cancel: (libc)Cancel AIO Operations. |
| * aio_error64: (libc)Status of AIO Operations. |
| * aio_error: (libc)Status of AIO Operations. |
| * aio_fsync64: (libc)Synchronizing AIO Operations. |
| * aio_fsync: (libc)Synchronizing AIO Operations. |
| * aio_init: (libc)Configuration of AIO. |
| * aio_read64: (libc)Asynchronous Reads/Writes. |
| * aio_read: (libc)Asynchronous Reads/Writes. |
| * aio_return64: (libc)Status of AIO Operations. |
| * aio_return: (libc)Status of AIO Operations. |
| * aio_suspend64: (libc)Synchronizing AIO Operations. |
| * aio_suspend: (libc)Synchronizing AIO Operations. |
| * aio_write64: (libc)Asynchronous Reads/Writes. |
| * aio_write: (libc)Asynchronous Reads/Writes. |
| * alarm: (libc)Setting an Alarm. |
| * aligned_alloc: (libc)Aligned Memory Blocks. |
| * alloca: (libc)Variable Size Automatic. |
| * alphasort64: (libc)Scanning Directory Content. |
| * alphasort: (libc)Scanning Directory Content. |
| * argp_error: (libc)Argp Helper Functions. |
| * argp_failure: (libc)Argp Helper Functions. |
| * argp_help: (libc)Argp Help. |
| * argp_parse: (libc)Argp. |
| * argp_state_help: (libc)Argp Helper Functions. |
| * argp_usage: (libc)Argp Helper Functions. |
| * argz_add: (libc)Argz Functions. |
| * argz_add_sep: (libc)Argz Functions. |
| * argz_append: (libc)Argz Functions. |
| * argz_count: (libc)Argz Functions. |
| * argz_create: (libc)Argz Functions. |
| * argz_create_sep: (libc)Argz Functions. |
| * argz_delete: (libc)Argz Functions. |
| * argz_extract: (libc)Argz Functions. |
| * argz_insert: (libc)Argz Functions. |
| * argz_next: (libc)Argz Functions. |
| * argz_replace: (libc)Argz Functions. |
| * argz_stringify: (libc)Argz Functions. |
| * asctime: (libc)Formatting Calendar Time. |
| * asctime_r: (libc)Formatting Calendar Time. |
| * asin: (libc)Inverse Trig Functions. |
| * asinf: (libc)Inverse Trig Functions. |
| * asinfN: (libc)Inverse Trig Functions. |
| * asinfNx: (libc)Inverse Trig Functions. |
| * asinh: (libc)Hyperbolic Functions. |
| * asinhf: (libc)Hyperbolic Functions. |
| * asinhfN: (libc)Hyperbolic Functions. |
| * asinhfNx: (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. |
| * atan2fN: (libc)Inverse Trig Functions. |
| * atan2fNx: (libc)Inverse Trig Functions. |
| * atan2l: (libc)Inverse Trig Functions. |
| * atan: (libc)Inverse Trig Functions. |
| * atanf: (libc)Inverse Trig Functions. |
| * atanfN: (libc)Inverse Trig Functions. |
| * atanfNx: (libc)Inverse Trig Functions. |
| * atanh: (libc)Hyperbolic Functions. |
| * atanhf: (libc)Hyperbolic Functions. |
| * atanhfN: (libc)Hyperbolic Functions. |
| * atanhfNx: (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 Strings and Arrays. |
| * 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 Strings and Arrays. |
| * cabs: (libc)Absolute Value. |
| * cabsf: (libc)Absolute Value. |
| * cabsfN: (libc)Absolute Value. |
| * cabsfNx: (libc)Absolute Value. |
| * cabsl: (libc)Absolute Value. |
| * cacos: (libc)Inverse Trig Functions. |
| * cacosf: (libc)Inverse Trig Functions. |
| * cacosfN: (libc)Inverse Trig Functions. |
| * cacosfNx: (libc)Inverse Trig Functions. |
| * cacosh: (libc)Hyperbolic Functions. |
| * cacoshf: (libc)Hyperbolic Functions. |
| * cacoshfN: (libc)Hyperbolic Functions. |
| * cacoshfNx: (libc)Hyperbolic Functions. |
| * cacoshl: (libc)Hyperbolic Functions. |
| * cacosl: (libc)Inverse Trig Functions. |
| * call_once: (libc)Call Once. |
| * calloc: (libc)Allocating Cleared Space. |
| * canonicalize: (libc)FP Bit Twiddling. |
| * canonicalize_file_name: (libc)Symbolic Links. |
| * canonicalizef: (libc)FP Bit Twiddling. |
| * canonicalizefN: (libc)FP Bit Twiddling. |
| * canonicalizefNx: (libc)FP Bit Twiddling. |
| * canonicalizel: (libc)FP Bit Twiddling. |
| * carg: (libc)Operations on Complex. |
| * cargf: (libc)Operations on Complex. |
| * cargfN: (libc)Operations on Complex. |
| * cargfNx: (libc)Operations on Complex. |
| * cargl: (libc)Operations on Complex. |
| * casin: (libc)Inverse Trig Functions. |
| * casinf: (libc)Inverse Trig Functions. |
| * casinfN: (libc)Inverse Trig Functions. |
| * casinfNx: (libc)Inverse Trig Functions. |
| * casinh: (libc)Hyperbolic Functions. |
| * casinhf: (libc)Hyperbolic Functions. |
| * casinhfN: (libc)Hyperbolic Functions. |
| * casinhfNx: (libc)Hyperbolic Functions. |
| * casinhl: (libc)Hyperbolic Functions. |
| * casinl: (libc)Inverse Trig Functions. |
| * catan: (libc)Inverse Trig Functions. |
| * catanf: (libc)Inverse Trig Functions. |
| * catanfN: (libc)Inverse Trig Functions. |
| * catanfNx: (libc)Inverse Trig Functions. |
| * catanh: (libc)Hyperbolic Functions. |
| * catanhf: (libc)Hyperbolic Functions. |
| * catanhfN: (libc)Hyperbolic Functions. |
| * catanhfNx: (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. |
| * cbrt: (libc)Exponents and Logarithms. |
| * cbrtf: (libc)Exponents and Logarithms. |
| * cbrtfN: (libc)Exponents and Logarithms. |
| * cbrtfNx: (libc)Exponents and Logarithms. |
| * cbrtl: (libc)Exponents and Logarithms. |
| * ccos: (libc)Trig Functions. |
| * ccosf: (libc)Trig Functions. |
| * ccosfN: (libc)Trig Functions. |
| * ccosfNx: (libc)Trig Functions. |
| * ccosh: (libc)Hyperbolic Functions. |
| * ccoshf: (libc)Hyperbolic Functions. |
| * ccoshfN: (libc)Hyperbolic Functions. |
| * ccoshfNx: (libc)Hyperbolic Functions. |
| * ccoshl: (libc)Hyperbolic Functions. |
| * ccosl: (libc)Trig Functions. |
| * ceil: (libc)Rounding Functions. |
| * ceilf: (libc)Rounding Functions. |
| * ceilfN: (libc)Rounding Functions. |
| * ceilfNx: (libc)Rounding Functions. |
| * ceill: (libc)Rounding Functions. |
| * cexp: (libc)Exponents and Logarithms. |
| * cexpf: (libc)Exponents and Logarithms. |
| * cexpfN: (libc)Exponents and Logarithms. |
| * cexpfNx: (libc)Exponents and Logarithms. |
| * cexpl: (libc)Exponents and Logarithms. |
| * cfgetispeed: (libc)Line Speed. |
| * cfgetospeed: (libc)Line Speed. |
| * cfmakeraw: (libc)Noncanonical Input. |
| * 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. |
| * cimagfN: (libc)Operations on Complex. |
| * cimagfNx: (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. |
| * clog10fN: (libc)Exponents and Logarithms. |
| * clog10fNx: (libc)Exponents and Logarithms. |
| * clog10l: (libc)Exponents and Logarithms. |
| * clog: (libc)Exponents and Logarithms. |
| * clogf: (libc)Exponents and Logarithms. |
| * clogfN: (libc)Exponents and Logarithms. |
| * clogfNx: (libc)Exponents and Logarithms. |
| * clogl: (libc)Exponents and Logarithms. |
| * close: (libc)Opening and Closing Files. |
| * closedir: (libc)Reading/Closing Directory. |
| * closelog: (libc)closelog. |
| * cnd_broadcast: (libc)ISO C Condition Variables. |
| * cnd_destroy: (libc)ISO C Condition Variables. |
| * cnd_init: (libc)ISO C Condition Variables. |
| * cnd_signal: (libc)ISO C Condition Variables. |
| * cnd_timedwait: (libc)ISO C Condition Variables. |
| * cnd_wait: (libc)ISO C Condition Variables. |
| * confstr: (libc)String Parameters. |
| * conj: (libc)Operations on Complex. |
| * conjf: (libc)Operations on Complex. |
| * conjfN: (libc)Operations on Complex. |
| * conjfNx: (libc)Operations on Complex. |
| * conjl: (libc)Operations on Complex. |
| * connect: (libc)Connecting. |
| * copy_file_range: (libc)Copying File Data. |
| * copysign: (libc)FP Bit Twiddling. |
| * copysignf: (libc)FP Bit Twiddling. |
| * copysignfN: (libc)FP Bit Twiddling. |
| * copysignfNx: (libc)FP Bit Twiddling. |
| * copysignl: (libc)FP Bit Twiddling. |
| * cos: (libc)Trig Functions. |
| * cosf: (libc)Trig Functions. |
| * cosfN: (libc)Trig Functions. |
| * cosfNx: (libc)Trig Functions. |
| * cosh: (libc)Hyperbolic Functions. |
| * coshf: (libc)Hyperbolic Functions. |
| * coshfN: (libc)Hyperbolic Functions. |
| * coshfNx: (libc)Hyperbolic Functions. |
| * coshl: (libc)Hyperbolic Functions. |
| * cosl: (libc)Trig Functions. |
| * cpow: (libc)Exponents and Logarithms. |
| * cpowf: (libc)Exponents and Logarithms. |
| * cpowfN: (libc)Exponents and Logarithms. |
| * cpowfNx: (libc)Exponents and Logarithms. |
| * cpowl: (libc)Exponents and Logarithms. |
| * cproj: (libc)Operations on Complex. |
| * cprojf: (libc)Operations on Complex. |
| * cprojfN: (libc)Operations on Complex. |
| * cprojfNx: (libc)Operations on Complex. |
| * cprojl: (libc)Operations on Complex. |
| * creal: (libc)Operations on Complex. |
| * crealf: (libc)Operations on Complex. |
| * crealfN: (libc)Operations on Complex. |
| * crealfNx: (libc)Operations on Complex. |
| * creall: (libc)Operations on Complex. |
| * creat64: (libc)Opening and Closing Files. |
| * creat: (libc)Opening and Closing Files. |
| * crypt: (libc)Passphrase Storage. |
| * crypt_r: (libc)Passphrase Storage. |
| * csin: (libc)Trig Functions. |
| * csinf: (libc)Trig Functions. |
| * csinfN: (libc)Trig Functions. |
| * csinfNx: (libc)Trig Functions. |
| * csinh: (libc)Hyperbolic Functions. |
| * csinhf: (libc)Hyperbolic Functions. |
| * csinhfN: (libc)Hyperbolic Functions. |
| * csinhfNx: (libc)Hyperbolic Functions. |
| * csinhl: (libc)Hyperbolic Functions. |
| * csinl: (libc)Trig Functions. |
| * csqrt: (libc)Exponents and Logarithms. |
| * csqrtf: (libc)Exponents and Logarithms. |
| * csqrtfN: (libc)Exponents and Logarithms. |
| * csqrtfNx: (libc)Exponents and Logarithms. |
| * csqrtl: (libc)Exponents and Logarithms. |
| * ctan: (libc)Trig Functions. |
| * ctanf: (libc)Trig Functions. |
| * ctanfN: (libc)Trig Functions. |
| * ctanfNx: (libc)Trig Functions. |
| * ctanh: (libc)Hyperbolic Functions. |
| * ctanhf: (libc)Hyperbolic Functions. |
| * ctanhfN: (libc)Hyperbolic Functions. |
| * ctanhfNx: (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. |
| * daddl: (libc)Misc FP Arithmetic. |
| * dcgettext: (libc)Translation with gettext. |
| * dcngettext: (libc)Advanced gettext functions. |
| * ddivl: (libc)Misc FP Arithmetic. |
| * 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. |
| * dmull: (libc)Misc FP Arithmetic. |
| * 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. |
| * dsubl: (libc)Misc FP Arithmetic. |
| * dup2: (libc)Duplicating Descriptors. |
| * dup: (libc)Duplicating Descriptors. |
| * ecvt: (libc)System V Number Conversion. |
| * ecvt_r: (libc)System V Number Conversion. |
| * 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_remove: (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. |
| * erfcfN: (libc)Special Functions. |
| * erfcfNx: (libc)Special Functions. |
| * erfcl: (libc)Special Functions. |
| * erff: (libc)Special Functions. |
| * erffN: (libc)Special Functions. |
| * erffNx: (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. |
| * exp10fN: (libc)Exponents and Logarithms. |
| * exp10fNx: (libc)Exponents and Logarithms. |
| * exp10l: (libc)Exponents and Logarithms. |
| * exp2: (libc)Exponents and Logarithms. |
| * exp2f: (libc)Exponents and Logarithms. |
| * exp2fN: (libc)Exponents and Logarithms. |
| * exp2fNx: (libc)Exponents and Logarithms. |
| * exp2l: (libc)Exponents and Logarithms. |
| * exp: (libc)Exponents and Logarithms. |
| * expf: (libc)Exponents and Logarithms. |
| * expfN: (libc)Exponents and Logarithms. |
| * expfNx: (libc)Exponents and Logarithms. |
| * expl: (libc)Exponents and Logarithms. |
| * explicit_bzero: (libc)Erasing Sensitive Data. |
| * expm1: (libc)Exponents and Logarithms. |
| * expm1f: (libc)Exponents and Logarithms. |
| * expm1fN: (libc)Exponents and Logarithms. |
| * expm1fNx: (libc)Exponents and Logarithms. |
| * expm1l: (libc)Exponents and Logarithms. |
| * fMaddfN: (libc)Misc FP Arithmetic. |
| * fMaddfNx: (libc)Misc FP Arithmetic. |
| * fMdivfN: (libc)Misc FP Arithmetic. |
| * fMdivfNx: (libc)Misc FP Arithmetic. |
| * fMmulfN: (libc)Misc FP Arithmetic. |
| * fMmulfNx: (libc)Misc FP Arithmetic. |
| * fMsubfN: (libc)Misc FP Arithmetic. |
| * fMsubfNx: (libc)Misc FP Arithmetic. |
| * fMxaddfN: (libc)Misc FP Arithmetic. |
| * fMxaddfNx: (libc)Misc FP Arithmetic. |
| * fMxdivfN: (libc)Misc FP Arithmetic. |
| * fMxdivfNx: (libc)Misc FP Arithmetic. |
| * fMxmulfN: (libc)Misc FP Arithmetic. |
| * fMxmulfNx: (libc)Misc FP Arithmetic. |
| * fMxsubfN: (libc)Misc FP Arithmetic. |
| * fMxsubfNx: (libc)Misc FP Arithmetic. |
| * fabs: (libc)Absolute Value. |
| * fabsf: (libc)Absolute Value. |
| * fabsfN: (libc)Absolute Value. |
| * fabsfNx: (libc)Absolute Value. |
| * fabsl: (libc)Absolute Value. |
| * fadd: (libc)Misc FP Arithmetic. |
| * faddl: (libc)Misc FP Arithmetic. |
| * 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. |
| * fdimfN: (libc)Misc FP Arithmetic. |
| * fdimfNx: (libc)Misc FP Arithmetic. |
| * fdiml: (libc)Misc FP Arithmetic. |
| * fdiv: (libc)Misc FP Arithmetic. |
| * fdivl: (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. |
| * fegetmode: (libc)Control Functions. |
| * 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. |
| * fesetexcept: (libc)Status bit operations. |
| * fesetexceptflag: (libc)Status bit operations. |
| * fesetmode: (libc)Control Functions. |
| * fesetround: (libc)Rounding. |
| * fetestexcept: (libc)Status bit operations. |
| * fetestexceptflag: (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. |
| * floorfN: (libc)Rounding Functions. |
| * floorfNx: (libc)Rounding Functions. |
| * floorl: (libc)Rounding Functions. |
| * fma: (libc)Misc FP Arithmetic. |
| * fmaf: (libc)Misc FP Arithmetic. |
| * fmafN: (libc)Misc FP Arithmetic. |
| * fmafNx: (libc)Misc FP Arithmetic. |
| * fmal: (libc)Misc FP Arithmetic. |
| * fmax: (libc)Misc FP Arithmetic. |
| * fmaxf: (libc)Misc FP Arithmetic. |
| * fmaxfN: (libc)Misc FP Arithmetic. |
| * fmaxfNx: (libc)Misc FP Arithmetic. |
| * fmaxl: (libc)Misc FP Arithmetic. |
| * fmaxmag: (libc)Misc FP Arithmetic. |
| * fmaxmagf: (libc)Misc FP Arithmetic. |
| * fmaxmagfN: (libc)Misc FP Arithmetic. |
| * fmaxmagfNx: (libc)Misc FP Arithmetic. |
| * fmaxmagl: (libc)Misc FP Arithmetic. |
| * fmemopen: (libc)String Streams. |
| * fmin: (libc)Misc FP Arithmetic. |
| * fminf: (libc)Misc FP Arithmetic. |
| * fminfN: (libc)Misc FP Arithmetic. |
| * fminfNx: (libc)Misc FP Arithmetic. |
| * fminl: (libc)Misc FP Arithmetic. |
| * fminmag: (libc)Misc FP Arithmetic. |
| * fminmagf: (libc)Misc FP Arithmetic. |
| * fminmagfN: (libc)Misc FP Arithmetic. |
| * fminmagfNx: (libc)Misc FP Arithmetic. |
| * fminmagl: (libc)Misc FP Arithmetic. |
| * fmod: (libc)Remainder Functions. |
| * fmodf: (libc)Remainder Functions. |
| * fmodfN: (libc)Remainder Functions. |
| * fmodfNx: (libc)Remainder Functions. |
| * fmodl: (libc)Remainder Functions. |
| * fmtmsg: (libc)Printing Formatted Messages. |
| * fmul: (libc)Misc FP Arithmetic. |
| * fmull: (libc)Misc FP Arithmetic. |
| * 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. |
| * frexpfN: (libc)Normalization Functions. |
| * frexpfNx: (libc)Normalization Functions. |
| * frexpl: (libc)Normalization Functions. |
| * fromfp: (libc)Rounding Functions. |
| * fromfpf: (libc)Rounding Functions. |
| * fromfpfN: (libc)Rounding Functions. |
| * fromfpfNx: (libc)Rounding Functions. |
| * fromfpl: (libc)Rounding Functions. |
| * fromfpx: (libc)Rounding Functions. |
| * fromfpxf: (libc)Rounding Functions. |
| * fromfpxfN: (libc)Rounding Functions. |
| * fromfpxfNx: (libc)Rounding Functions. |
| * fromfpxl: (libc)Rounding 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. |
| * fsub: (libc)Misc FP Arithmetic. |
| * fsubl: (libc)Misc FP Arithmetic. |
| * 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. |
| * getcpu: (libc)CPU Affinity. |
| * getcwd: (libc)Working Directory. |
| * getdate: (libc)General Time String Parsing. |
| * getdate_r: (libc)General Time String Parsing. |
| * getdelim: (libc)Line Input. |
| * getdents64: (libc)Low-level Directory Access. |
| * getdomainnname: (libc)Host Identification. |
| * getegid: (libc)Reading Persona. |
| * getentropy: (libc)Unpredictable Bytes. |
| * 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. |
| * getpayload: (libc)FP Bit Twiddling. |
| * getpayloadf: (libc)FP Bit Twiddling. |
| * getpayloadfN: (libc)FP Bit Twiddling. |
| * getpayloadfNx: (libc)FP Bit Twiddling. |
| * getpayloadl: (libc)FP Bit Twiddling. |
| * getpeername: (libc)Who is Connected. |
| * getpgid: (libc)Process Group Functions. |
| * getpgrp: (libc)Process Group Functions. |
| * getpid: (libc)Process Identification. |
| * getppid: (libc)Process Identification. |
| * getpriority: (libc)Traditional Scheduling Functions. |
| * getprotobyname: (libc)Protocols Database. |
| * getprotobynumber: (libc)Protocols Database. |
| * getprotoent: (libc)Protocols Database. |
| * getpt: (libc)Allocation. |
| * getpwent: (libc)Scanning All Users. |
| * getpwent_r: (libc)Scanning All Users. |
| * getpwnam: (libc)Lookup User. |
| * getpwnam_r: (libc)Lookup User. |
| * getpwuid: (libc)Lookup User. |
| * getpwuid_r: (libc)Lookup User. |
| * getrandom: (libc)Unpredictable Bytes. |
| * 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. |
| * gettid: (libc)Process Identification. |
| * 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. |
| * hypotfN: (libc)Exponents and Logarithms. |
| * hypotfNx: (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. |
| * ilogbfN: (libc)Exponents and Logarithms. |
| * ilogbfNx: (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. |
| * iscanonical: (libc)Floating Point Classes. |
| * iscntrl: (libc)Classification of Characters. |
| * isdigit: (libc)Classification of Characters. |
| * iseqsig: (libc)FP Comparison Functions. |
| * 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. |
| * issubnormal: (libc)Floating Point Classes. |
| * 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. |
| * iszero: (libc)Floating Point Classes. |
| * j0: (libc)Special Functions. |
| * j0f: (libc)Special Functions. |
| * j0fN: (libc)Special Functions. |
| * j0fNx: (libc)Special Functions. |
| * j0l: (libc)Special Functions. |
| * j1: (libc)Special Functions. |
| * j1f: (libc)Special Functions. |
| * j1fN: (libc)Special Functions. |
| * j1fNx: (libc)Special Functions. |
| * j1l: (libc)Special Functions. |
| * jn: (libc)Special Functions. |
| * jnf: (libc)Special Functions. |
| * jnfN: (libc)Special Functions. |
| * jnfNx: (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. |
| * ldexpfN: (libc)Normalization Functions. |
| * ldexpfNx: (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. |
| * lgammafN: (libc)Special Functions. |
| * lgammafN_r: (libc)Special Functions. |
| * lgammafNx: (libc)Special Functions. |
| * lgammafNx_r: (libc)Special Functions. |
| * lgammaf_r: (libc)Special Functions. |
| * lgammal: (libc)Special Functions. |
| * lgammal_r: (libc)Special Functions. |
| * link: (libc)Hard Links. |
| * linkat: (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. |
| * llogb: (libc)Exponents and Logarithms. |
| * llogbf: (libc)Exponents and Logarithms. |
| * llogbfN: (libc)Exponents and Logarithms. |
| * llogbfNx: (libc)Exponents and Logarithms. |
| * llogbl: (libc)Exponents and Logarithms. |
| * llrint: (libc)Rounding Functions. |
| * llrintf: (libc)Rounding Functions. |
| * llrintfN: (libc)Rounding Functions. |
| * llrintfNx: (libc)Rounding Functions. |
| * llrintl: (libc)Rounding Functions. |
| * llround: (libc)Rounding Functions. |
| * llroundf: (libc)Rounding Functions. |
| * llroundfN: (libc)Rounding Functions. |
| * llroundfNx: (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. |
| * log10fN: (libc)Exponents and Logarithms. |
| * log10fNx: (libc)Exponents and Logarithms. |
| * log10l: (libc)Exponents and Logarithms. |
| * log1p: (libc)Exponents and Logarithms. |
| * log1pf: (libc)Exponents and Logarithms. |
| * log1pfN: (libc)Exponents and Logarithms. |
| * log1pfNx: (libc)Exponents and Logarithms. |
| * log1pl: (libc)Exponents and Logarithms. |
| * log2: (libc)Exponents and Logarithms. |
| * log2f: (libc)Exponents and Logarithms. |
| * log2fN: (libc)Exponents and Logarithms. |
| * log2fNx: (libc)Exponents and Logarithms. |
| * log2l: (libc)Exponents and Logarithms. |
| * log: (libc)Exponents and Logarithms. |
| * logb: (libc)Exponents and Logarithms. |
| * logbf: (libc)Exponents and Logarithms. |
| * logbfN: (libc)Exponents and Logarithms. |
| * logbfNx: (libc)Exponents and Logarithms. |
| * logbl: (libc)Exponents and Logarithms. |
| * logf: (libc)Exponents and Logarithms. |
| * logfN: (libc)Exponents and Logarithms. |
| * logfNx: (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. |
| * lrintfN: (libc)Rounding Functions. |
| * lrintfNx: (libc)Rounding Functions. |
| * lrintl: (libc)Rounding Functions. |
| * lround: (libc)Rounding Functions. |
| * lroundf: (libc)Rounding Functions. |
| * lroundfN: (libc)Rounding Functions. |
| * lroundfNx: (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 Strings and Arrays. |
| * memchr: (libc)Search Functions. |
| * memcmp: (libc)String/Array Comparison. |
| * memcpy: (libc)Copying Strings and Arrays. |
| * memfd_create: (libc)Memory-mapped I/O. |
| * memfrob: (libc)Obfuscating Data. |
| * memmem: (libc)Search Functions. |
| * memmove: (libc)Copying Strings and Arrays. |
| * mempcpy: (libc)Copying Strings and Arrays. |
| * memrchr: (libc)Search Functions. |
| * memset: (libc)Copying Strings and Arrays. |
| * 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. |
| * mlock2: (libc)Page Lock Functions. |
| * 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. |
| * modffN: (libc)Rounding Functions. |
| * modffNx: (libc)Rounding Functions. |
| * modfl: (libc)Rounding Functions. |
| * mount: (libc)Mount-Unmount-Remount. |
| * mprobe: (libc)Heap Consistency Checking. |
| * mprotect: (libc)Memory Protection. |
| * 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. |
| * mtx_destroy: (libc)ISO C Mutexes. |
| * mtx_init: (libc)ISO C Mutexes. |
| * mtx_lock: (libc)ISO C Mutexes. |
| * mtx_timedlock: (libc)ISO C Mutexes. |
| * mtx_trylock: (libc)ISO C Mutexes. |
| * mtx_unlock: (libc)ISO C Mutexes. |
| * 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. |
| * nanfN: (libc)FP Bit Twiddling. |
| * nanfNx: (libc)FP Bit Twiddling. |
| * nanl: (libc)FP Bit Twiddling. |
| * nanosleep: (libc)Sleeping. |
| * nearbyint: (libc)Rounding Functions. |
| * nearbyintf: (libc)Rounding Functions. |
| * nearbyintfN: (libc)Rounding Functions. |
| * nearbyintfNx: (libc)Rounding Functions. |
| * nearbyintl: (libc)Rounding Functions. |
| * nextafter: (libc)FP Bit Twiddling. |
| * nextafterf: (libc)FP Bit Twiddling. |
| * nextafterfN: (libc)FP Bit Twiddling. |
| * nextafterfNx: (libc)FP Bit Twiddling. |
| * nextafterl: (libc)FP Bit Twiddling. |
| * nextdown: (libc)FP Bit Twiddling. |
| * nextdownf: (libc)FP Bit Twiddling. |
| * nextdownfN: (libc)FP Bit Twiddling. |
| * nextdownfNx: (libc)FP Bit Twiddling. |
| * nextdownl: (libc)FP Bit Twiddling. |
| * nexttoward: (libc)FP Bit Twiddling. |
| * nexttowardf: (libc)FP Bit Twiddling. |
| * nexttowardl: (libc)FP Bit Twiddling. |
| * nextup: (libc)FP Bit Twiddling. |
| * nextupf: (libc)FP Bit Twiddling. |
| * nextupfN: (libc)FP Bit Twiddling. |
| * nextupfNx: (libc)FP Bit Twiddling. |
| * nextupl: (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. |
| * pkey_alloc: (libc)Memory Protection. |
| * pkey_free: (libc)Memory Protection. |
| * pkey_get: (libc)Memory Protection. |
| * pkey_mprotect: (libc)Memory Protection. |
| * pkey_set: (libc)Memory Protection. |
| * popen: (libc)Pipe to a Subprocess. |
| * posix_fallocate64: (libc)Storage Allocation. |
| * posix_fallocate: (libc)Storage Allocation. |
| * posix_memalign: (libc)Aligned Memory Blocks. |
| * pow: (libc)Exponents and Logarithms. |
| * powf: (libc)Exponents and Logarithms. |
| * powfN: (libc)Exponents and Logarithms. |
| * powfNx: (libc)Exponents and Logarithms. |
| * powl: (libc)Exponents and Logarithms. |
| * pread64: (libc)I/O Primitives. |
| * pread: (libc)I/O Primitives. |
| * preadv2: (libc)Scatter-Gather. |
| * preadv64: (libc)Scatter-Gather. |
| * preadv64v2: (libc)Scatter-Gather. |
| * preadv: (libc)Scatter-Gather. |
| * printf: (libc)Formatted Output Functions. |
| * printf_size: (libc)Predefined Printf Handlers. |
| * printf_size_info: (libc)Predefined Printf Handlers. |
| * psignal: (libc)Signal Messages. |
| * pthread_cond_clockwait: (libc)Default Thread Attributes. |
| * pthread_getattr_default_np: (libc)Default Thread Attributes. |
| * pthread_getspecific: (libc)Thread-specific Data. |
| * pthread_key_create: (libc)Thread-specific Data. |
| * pthread_key_delete: (libc)Thread-specific Data. |
| * pthread_rwlock_clockrdlock: (libc)Default Thread Attributes. |
| * pthread_rwlock_clockwrlock: (libc)Default Thread Attributes. |
| * pthread_setattr_default_np: (libc)Default Thread Attributes. |
| * pthread_setspecific: (libc)Thread-specific Data. |
| * ptsname: (libc)Allocation. |
| * ptsname_r: (libc)Allocation. |
| * putc: (libc)Simple Output. |
| * putc_unlocked: (libc)Simple Output. |
| * putchar: (libc)Simple Output. |
| * putchar_unlocked: (libc)Simple Output. |
| * putenv: (libc)Environment Access. |
| * putpwent: (libc)Writing a User Entry. |
| * puts: (libc)Simple Output. |
| * pututline: (libc)Manipulating the Database. |
| * pututxline: (libc)XPG Functions. |
| * putw: (libc)Simple Output. |
| * putwc: (libc)Simple Output. |
| * putwc_unlocked: (libc)Simple Output. |
| * putwchar: (libc)Simple Output. |
| * putwchar_unlocked: (libc)Simple Output. |
| * pwrite64: (libc)I/O Primitives. |
| * pwrite: (libc)I/O Primitives. |
| * pwritev2: (libc)Scatter-Gather. |
| * pwritev64: (libc)Scatter-Gather. |
| * pwritev64v2: (libc)Scatter-Gather. |
| * pwritev: (libc)Scatter-Gather. |
| * 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. |
| * reallocarray: (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. |
| * remainderfN: (libc)Remainder Functions. |
| * remainderfNx: (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. |
| * rintfN: (libc)Rounding Functions. |
| * rintfNx: (libc)Rounding Functions. |
| * rintl: (libc)Rounding Functions. |
| * rmdir: (libc)Deleting Files. |
| * round: (libc)Rounding Functions. |
| * roundeven: (libc)Rounding Functions. |
| * roundevenf: (libc)Rounding Functions. |
| * roundevenfN: (libc)Rounding Functions. |
| * roundevenfNx: (libc)Rounding Functions. |
| * roundevenl: (libc)Rounding Functions. |
| * roundf: (libc)Rounding Functions. |
| * roundfN: (libc)Rounding Functions. |
| * roundfNx: (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. |
| * scalblnfN: (libc)Normalization Functions. |
| * scalblnfNx: (libc)Normalization Functions. |
| * scalblnl: (libc)Normalization Functions. |
| * scalbn: (libc)Normalization Functions. |
| * scalbnf: (libc)Normalization Functions. |
| * scalbnfN: (libc)Normalization Functions. |
| * scalbnfNx: (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. |
| * sem_clockwait: (libc)Default Thread Attributes. |
| * sem_close: (libc)Semaphores. |
| * sem_destroy: (libc)Semaphores. |
| * sem_getvalue: (libc)Semaphores. |
| * sem_init: (libc)Semaphores. |
| * sem_open: (libc)Semaphores. |
| * sem_post: (libc)Semaphores. |
| * sem_timedwait: (libc)Semaphores. |
| * sem_trywait: (libc)Semaphores. |
| * sem_unlink: (libc)Semaphores. |
| * sem_wait: (libc)Semaphores. |
| * semctl: (libc)Semaphores. |
| * semget: (libc)Semaphores. |
| * semop: (libc)Semaphores. |
| * semtimedop: (libc)Semaphores. |
| * 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. |
| * setlinebuf: (libc)Controlling Buffering. |
| * setlocale: (libc)Setting the Locale. |
| * setlogmask: (libc)setlogmask. |
| * setmntent: (libc)mtab. |
| * setnetent: (libc)Networks Database. |
| * setnetgrent: (libc)Lookup Netgroup. |
| * setpayload: (libc)FP Bit Twiddling. |
| * setpayloadf: (libc)FP Bit Twiddling. |
| * setpayloadfN: (libc)FP Bit Twiddling. |
| * setpayloadfNx: (libc)FP Bit Twiddling. |
| * setpayloadl: (libc)FP Bit Twiddling. |
| * setpayloadsig: (libc)FP Bit Twiddling. |
| * setpayloadsigf: (libc)FP Bit Twiddling. |
| * setpayloadsigfN: (libc)FP Bit Twiddling. |
| * setpayloadsigfNx: (libc)FP Bit Twiddling. |
| * setpayloadsigl: (libc)FP Bit Twiddling. |
| * setpgid: (libc)Process Group Functions. |
| * setpgrp: (libc)Process Group Functions. |
| * setpriority: (libc)Traditional Scheduling Functions. |
| * setprotoent: (libc)Protocols Database. |
| * setpwent: (libc)Scanning All Users. |
| * setregid: (libc)Setting Groups. |
| * setreuid: (libc)Setting User ID. |
| * setrlimit64: (libc)Limits on Resources. |
| * setrlimit: (libc)Limits on Resources. |
| * setservent: (libc)Services Database. |
| * setsid: (libc)Process Group Functions. |
| * setsockopt: (libc)Socket Option Functions. |
| * setstate: (libc)BSD Random. |
| * setstate_r: (libc)BSD Random. |
| * settimeofday: (libc)High-Resolution Calendar. |
| * setuid: (libc)Setting User ID. |
| * setutent: (libc)Manipulating the Database. |
| * setutxent: (libc)XPG Functions. |
| * setvbuf: (libc)Controlling Buffering. |
| * shm_open: (libc)Memory-mapped I/O. |
| * shm_unlink: (libc)Memory-mapped I/O. |
| * shutdown: (libc)Closing a Socket. |
| * sigaction: (libc)Advanced Signal Handling. |
| * sigaddset: (libc)Signal Sets. |
| * sigaltstack: (libc)Signal Stack. |
| * sigblock: (libc)BSD Signal Handling. |
| * sigdelset: (libc)Signal Sets. |
| * sigemptyset: (libc)Signal Sets. |
| * sigfillset: (libc)Signal Sets. |
| * siginterrupt: (libc)BSD Signal Handling. |
| * sigismember: (libc)Signal Sets. |
| * siglongjmp: (libc)Non-Local Exits and Signals. |
| * sigmask: (libc)BSD Signal Handling. |
| * signal: (libc)Basic Signal Handling. |
| * signbit: (libc)FP Bit Twiddling. |
| * significand: (libc)Normalization Functions. |
| * significandf: (libc)Normalization Functions. |
| * significandl: (libc)Normalization Functions. |
| * sigpause: (libc)BSD Signal Handling. |
| * sigpending: (libc)Checking for Pending Signals. |
| * sigprocmask: (libc)Process Signal Mask. |
| * sigsetjmp: (libc)Non-Local Exits and Signals. |
| * sigsetmask: (libc)BSD Signal Handling. |
| * sigstack: (libc)Signal Stack. |
| * sigsuspend: (libc)Sigsuspend. |
| * sin: (libc)Trig Functions. |
| * sincos: (libc)Trig Functions. |
| * sincosf: (libc)Trig Functions. |
| * sincosfN: (libc)Trig Functions. |
| * sincosfNx: (libc)Trig Functions. |
| * sincosl: (libc)Trig Functions. |
| * sinf: (libc)Trig Functions. |
| * sinfN: (libc)Trig Functions. |
| * sinfNx: (libc)Trig Functions. |
| * sinh: (libc)Hyperbolic Functions. |
| * sinhf: (libc)Hyperbolic Functions. |
| * sinhfN: (libc)Hyperbolic Functions. |
| * sinhfNx: (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. |
| * sqrtfN: (libc)Exponents and Logarithms. |
| * sqrtfNx: (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 Strings and Arrays. |
| * stpncpy: (libc)Truncating Strings. |
| * strcasecmp: (libc)String/Array Comparison. |
| * strcasestr: (libc)Search Functions. |
| * strcat: (libc)Concatenating Strings. |
| * strchr: (libc)Search Functions. |
| * strchrnul: (libc)Search Functions. |
| * strcmp: (libc)String/Array Comparison. |
| * strcoll: (libc)Collation Functions. |
| * strcpy: (libc)Copying Strings and Arrays. |
| * strcspn: (libc)Search Functions. |
| * strdup: (libc)Copying Strings and Arrays. |
| * strdupa: (libc)Copying Strings and Arrays. |
| * strerror: (libc)Error Messages. |
| * strerror_r: (libc)Error Messages. |
| * strfmon: (libc)Formatting Numbers. |
| * strfromd: (libc)Printing of Floats. |
| * strfromf: (libc)Printing of Floats. |
| * strfromfN: (libc)Printing of Floats. |
| * strfromfNx: (libc)Printing of Floats. |
| * strfroml: (libc)Printing of Floats. |
| * strfry: (libc)Shuffling Bytes. |
| * strftime: (libc)Formatting Calendar Time. |
| * strlen: (libc)String Length. |
| * strncasecmp: (libc)String/Array Comparison. |
| * strncat: (libc)Truncating Strings. |
| * strncmp: (libc)String/Array Comparison. |
| * strncpy: (libc)Truncating Strings. |
| * strndup: (libc)Truncating Strings. |
| * strndupa: (libc)Truncating Strings. |
| * 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. |
| * strtofN: (libc)Parsing of Floats. |
| * strtofNx: (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. |
| * tanfN: (libc)Trig Functions. |
| * tanfNx: (libc)Trig Functions. |
| * tanh: (libc)Hyperbolic Functions. |
| * tanhf: (libc)Hyperbolic Functions. |
| * tanhfN: (libc)Hyperbolic Functions. |
| * tanhfNx: (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. |
| * tgammafN: (libc)Special Functions. |
| * tgammafNx: (libc)Special Functions. |
| * tgammal: (libc)Special Functions. |
| * tgkill: (libc)Signaling Another Process. |
| * thrd_create: (libc)ISO C Thread Management. |
| * thrd_current: (libc)ISO C Thread Management. |
| * thrd_detach: (libc)ISO C Thread Management. |
| * thrd_equal: (libc)ISO C Thread Management. |
| * thrd_exit: (libc)ISO C Thread Management. |
| * thrd_join: (libc)ISO C Thread Management. |
| * thrd_sleep: (libc)ISO C Thread Management. |
| * thrd_yield: (libc)ISO C Thread Management. |
| * 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. |
| * totalorder: (libc)FP Comparison Functions. |
| * totalorderf: (libc)FP Comparison Functions. |
| * totalorderfN: (libc)FP Comparison Functions. |
| * totalorderfNx: (libc)FP Comparison Functions. |
| * totalorderl: (libc)FP Comparison Functions. |
| * totalordermag: (libc)FP Comparison Functions. |
| * totalordermagf: (libc)FP Comparison Functions. |
| * totalordermagfN: (libc)FP Comparison Functions. |
| * totalordermagfNx: (libc)FP Comparison Functions. |
| * totalordermagl: (libc)FP Comparison Functions. |
| * 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. |
| * truncfN: (libc)Rounding Functions. |
| * truncfNx: (libc)Rounding Functions. |
| * truncl: (libc)Rounding Functions. |
| * tsearch: (libc)Tree Search Function. |
| * tss_create: (libc)ISO C Thread-local Storage. |
| * tss_delete: (libc)ISO C Thread-local Storage. |
| * tss_get: (libc)ISO C Thread-local Storage. |
| * tss_set: (libc)ISO C Thread-local Storage. |
| * ttyname: (libc)Is It a Terminal. |
| * ttyname_r: (libc)Is It a Terminal. |
| * twalk: (libc)Tree Search Function. |
| * twalk_r: (libc)Tree Search Function. |
| * tzset: (libc)Time Zone Functions. |
| * ufromfp: (libc)Rounding Functions. |
| * ufromfpf: (libc)Rounding Functions. |
| * ufromfpfN: (libc)Rounding Functions. |
| * ufromfpfNx: (libc)Rounding Functions. |
| * ufromfpl: (libc)Rounding Functions. |
| * ufromfpx: (libc)Rounding Functions. |
| * ufromfpxf: (libc)Rounding Functions. |
| * ufromfpxfN: (libc)Rounding Functions. |
| * ufromfpxfNx: (libc)Rounding Functions. |
| * ufromfpxl: (libc)Rounding 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 Strings and Arrays. |
| * wcpncpy: (libc)Truncating Strings. |
| * wcrtomb: (libc)Converting a Character. |
| * wcscasecmp: (libc)String/Array Comparison. |
| * wcscat: (libc)Concatenating Strings. |
| * wcschr: (libc)Search Functions. |
| * wcschrnul: (libc)Search Functions. |
| * wcscmp: (libc)String/Array Comparison. |
| * wcscoll: (libc)Collation Functions. |
| * wcscpy: (libc)Copying Strings and Arrays. |
| * wcscspn: (libc)Search Functions. |
| * wcsdup: (libc)Copying Strings and Arrays. |
| * wcsftime: (libc)Formatting Calendar Time. |
| * wcslen: (libc)String Length. |
| * wcsncasecmp: (libc)String/Array Comparison. |
| * wcsncat: (libc)Truncating Strings. |
| * wcsncmp: (libc)String/Array Comparison. |
| * wcsncpy: (libc)Truncating Strings. |
| * 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. |
| * wcstofN: (libc)Parsing of Floats. |
| * wcstofNx: (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 Strings and Arrays. |
| * wmemmove: (libc)Copying Strings and Arrays. |
| * wmempcpy: (libc)Copying Strings and Arrays. |
| * wmemset: (libc)Copying Strings and Arrays. |
| * 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. |
| * y0fN: (libc)Special Functions. |
| * y0fNx: (libc)Special Functions. |
| * y0l: (libc)Special Functions. |
| * y1: (libc)Special Functions. |
| * y1f: (libc)Special Functions. |
| * y1fN: (libc)Special Functions. |
| * y1fNx: (libc)Special Functions. |
| * y1l: (libc)Special Functions. |
| * yn: (libc)Special Functions. |
| * ynf: (libc)Special Functions. |
| * ynfN: (libc)Special Functions. |
| * ynfNx: (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.30 |
| (GNU Toolchain for the A-profile Architecture 9.2-2019.12 (arm-9.10)). |
| |
| Copyright (C) 1993-2019 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: Stopped and Terminated Jobs, Next: Continuing Stopped Jobs, Prev: Foreground and Background, Up: Implementing a Shell |
| |
| 28.5.5 Stopped and Terminated Jobs |
| ---------------------------------- |
| |
| When a foreground process is launched, the shell must block until all of |
| the processes in that job have either terminated or stopped. It can do |
| this by calling the `waitpid' function; see *note Process Completion::. |
| Use the `WUNTRACED' option so that status is reported for processes |
| that stop as well as processes that terminate. |
| |
| The shell must also check on the status of background jobs so that it |
| can report terminated and stopped jobs to the user; this can be done by |
| calling `waitpid' with the `WNOHANG' option. A good place to put a |
| such a check for terminated and stopped jobs is just before prompting |
| for a new command. |
| |
| The shell can also receive asynchronous notification that there is |
| status information available for a child process by establishing a |
| handler for `SIGCHLD' signals. *Note Signal Handling::. |
| |
| In the sample shell program, the `SIGCHLD' signal is normally |
| ignored. This is to avoid reentrancy problems involving the global data |
| structures the shell manipulates. But at specific times when the shell |
| is not using these data structures--such as when it is waiting for |
| input on the terminal--it makes sense to enable a handler for |
| `SIGCHLD'. The same function that is used to do the synchronous status |
| checks (`do_job_notification', in this case) can also be called from |
| within this handler. |
| |
| Here are the parts of the sample shell program that deal with |
| checking the status of jobs and reporting the information to the user. |
| |
| /* Store the status of the process PID that was returned by waitpid. |
| Return 0 if all went well, nonzero otherwise. */ |
| |
| int |
| mark_process_status (pid_t pid, int status) |
| { |
| job *j; |
| process *p; |
| |
| if (pid > 0) |
| { |
| /* Update the record for the process. */ |
| for (j = first_job; j; j = j->next) |
| for (p = j->first_process; p; p = p->next) |
| if (p->pid == pid) |
| { |
| p->status = status; |
| if (WIFSTOPPED (status)) |
| p->stopped = 1; |
| else |
| { |
| p->completed = 1; |
| if (WIFSIGNALED (status)) |
| fprintf (stderr, "%d: Terminated by signal %d.\n", |
| (int) pid, WTERMSIG (p->status)); |
| } |
| return 0; |
| } |
| fprintf (stderr, "No child process %d.\n", pid); |
| return -1; |
| } |
| else if (pid == 0 || errno == ECHILD) |
| /* No processes ready to report. */ |
| return -1; |
| else { |
| /* Other weird errors. */ |
| perror ("waitpid"); |
| return -1; |
| } |
| } |
| |
| /* Check for processes that have status information available, |
| without blocking. */ |
| |
| void |
| update_status (void) |
| { |
| int status; |
| pid_t pid; |
| |
| do |
| pid = waitpid (WAIT_ANY, &status, WUNTRACED|WNOHANG); |
| while (!mark_process_status (pid, status)); |
| } |
| |
| /* Check for processes that have status information available, |
| blocking until all processes in the given job have reported. */ |
| |
| void |
| wait_for_job (job *j) |
| { |
| int status; |
| pid_t pid; |
| |
| do |
| pid = waitpid (WAIT_ANY, &status, WUNTRACED); |
| while (!mark_process_status (pid, status) |
| && !job_is_stopped (j) |
| && !job_is_completed (j)); |
| } |
| |
| /* Format information about job status for the user to look at. */ |
| |
| void |
| format_job_info (job *j, const char *status) |
| { |
| fprintf (stderr, "%ld (%s): %s\n", (long)j->pgid, status, j->command); |
| } |
| |
| /* Notify the user about stopped or terminated jobs. |
| Delete terminated jobs from the active job list. */ |
| |
| void |
| do_job_notification (void) |
| { |
| job *j, *jlast, *jnext; |
| process *p; |
| |
| /* Update status information for child processes. */ |
| update_status (); |
| |
| jlast = NULL; |
| for (j = first_job; j; j = jnext) |
| { |
| jnext = j->next; |
| |
| /* If all processes have completed, tell the user the job has |
| completed and delete it from the list of active jobs. */ |
| if (job_is_completed (j)) { |
| format_job_info (j, "completed"); |
| if (jlast) |
| jlast->next = jnext; |
| else |
| first_job = jnext; |
| free_job (j); |
| } |
| |
| /* Notify the user about stopped jobs, |
| marking them so that we won't do this more than once. */ |
| else if (job_is_stopped (j) && !j->notified) { |
| format_job_info (j, "stopped"); |
| j->notified = 1; |
| jlast = j; |
| } |
| |
| /* Don't say anything about jobs that are still running. */ |
| else |
| jlast = j; |
| } |
| } |
| |
| |
| File: libc.info, Node: Continuing Stopped Jobs, Next: Missing Pieces, Prev: Stopped and Terminated Jobs, Up: Implementing a Shell |
| |
| 28.5.6 Continuing Stopped Jobs |
| ------------------------------ |
| |
| The shell can continue a stopped job by sending a `SIGCONT' signal to |
| its process group. If the job is being continued in the foreground, |
| the shell should first invoke `tcsetpgrp' to give the job access to the |
| terminal, and restore the saved terminal settings. After continuing a |
| job in the foreground, the shell should wait for the job to stop or |
| complete, as if the job had just been launched in the foreground. |
| |
| The sample shell program handles both newly created and continued |
| jobs with the same pair of functions, `put_job_in_foreground' and |
| `put_job_in_background'. The definitions of these functions were given |
| in *note Foreground and Background::. When continuing a stopped job, a |
| nonzero value is passed as the CONT argument to ensure that the |
| `SIGCONT' signal is sent and the terminal modes reset, as appropriate. |
| |
| This leaves only a function for updating the shell's internal |
| bookkeeping about the job being continued: |
| |
| /* Mark a stopped job J as being running again. */ |
| |
| void |
| mark_job_as_running (job *j) |
| { |
| Process *p; |
| |
| for (p = j->first_process; p; p = p->next) |
| p->stopped = 0; |
| j->notified = 0; |
| } |
| |
| /* Continue the job J. */ |
| |
| void |
| continue_job (job *j, int foreground) |
| { |
| mark_job_as_running (j); |
| if (foreground) |
| put_job_in_foreground (j, 1); |
| else |
| put_job_in_background (j, 1); |
| } |
| |
| |
| File: libc.info, Node: Missing Pieces, Prev: Continuing Stopped Jobs, Up: Implementing a Shell |
| |
| 28.5.7 The Missing Pieces |
| ------------------------- |
| |
| The code extracts for the sample shell included in this chapter are only |
| a part of the entire shell program. In particular, nothing at all has |
| been said about how `job' and `program' data structures are allocated |
| and initialized. |
| |
| Most real shells provide a complex user interface that has support |
| for a command language; variables; abbreviations, substitutions, and |
| pattern matching on file names; and the like. All of this is far too |
| complicated to explain here! Instead, we have concentrated on showing |
| how to implement the core process creation and job control functions |
| that can be called from such a shell. |
| |
| Here is a table summarizing the major entry points we have presented: |
| |
| `void init_shell (void)' |
| Initialize the shell's internal state. *Note Initializing the |
| Shell::. |
| |
| `void launch_job (job *J, int FOREGROUND)' |
| Launch the job J as either a foreground or background job. *Note |
| Launching Jobs::. |
| |
| `void do_job_notification (void)' |
| Check for and report any jobs that have terminated or stopped. |
| Can be called synchronously or within a handler for `SIGCHLD' |
| signals. *Note Stopped and Terminated Jobs::. |
| |
| `void continue_job (job *J, int FOREGROUND)' |
| Continue the job J. *Note Continuing Stopped Jobs::. |
| |
| Of course, a real shell would also want to provide other functions |
| for managing jobs. For example, it would be useful to have commands to |
| list all active jobs or to send a signal (such as `SIGKILL') to a job. |
| |
| |
| File: libc.info, Node: Functions for Job Control, Prev: Implementing a Shell, Up: Job Control |
| |
| 28.6 Functions for Job Control |
| ============================== |
| |
| This section contains detailed descriptions of the functions relating |
| to job control. |
| |
| * Menu: |
| |
| * Identifying the Terminal:: Determining the controlling terminal's name. |
| * Process Group Functions:: Functions for manipulating process groups. |
| * Terminal Access Functions:: Functions for controlling terminal access. |
| |
| |
| File: libc.info, Node: Identifying the Terminal, Next: Process Group Functions, Up: Functions for Job Control |
| |
| 28.6.1 Identifying the Controlling Terminal |
| ------------------------------------------- |
| |
| You can use the `ctermid' function to get a file name that you can use |
| to open the controlling terminal. In the GNU C Library, it returns the |
| same string all the time: `"/dev/tty"'. That is a special "magic" file |
| name that refers to the controlling terminal of the current process (if |
| it has one). To find the name of the specific terminal device, use |
| `ttyname'; *note Is It a Terminal::. |
| |
| The function `ctermid' is declared in the header file `stdio.h'. |
| |
| -- Function: char * ctermid (char *STRING) |
| Preliminary: | MT-Safe !posix/!string | AS-Safe | AC-Safe | *Note |
| POSIX Safety Concepts::. |
| |
| The `ctermid' function returns a string containing the file name of |
| the controlling terminal for the current process. If STRING is |
| not a null pointer, it should be an array that can hold at least |
| `L_ctermid' characters; the string is returned in this array. |
| Otherwise, a pointer to a string in a static area is returned, |
| which might get overwritten on subsequent calls to this function. |
| |
| An empty string is returned if the file name cannot be determined |
| for any reason. Even if a file name is returned, access to the |
| file it represents is not guaranteed. |
| |
| -- Macro: int L_ctermid |
| The value of this macro is an integer constant expression that |
| represents the size of a string large enough to hold the file name |
| returned by `ctermid'. |
| |
| See also the `isatty' and `ttyname' functions, in *note Is It a |
| Terminal::. |
| |
| |
| File: libc.info, Node: Process Group Functions, Next: Terminal Access Functions, Prev: Identifying the Terminal, Up: Functions for Job Control |
| |
| 28.6.2 Process Group Functions |
| ------------------------------ |
| |
| Here are descriptions of the functions for manipulating process groups. |
| Your program should include the header files `sys/types.h' and |
| `unistd.h' to use these functions. |
| |
| -- Function: pid_t setsid (void) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `setsid' function creates a new session. The calling process |
| becomes the session leader, and is put in a new process group whose |
| process group ID is the same as the process ID of that process. |
| There are initially no other processes in the new process group, |
| and no other process groups in the new session. |
| |
| This function also makes the calling process have no controlling |
| terminal. |
| |
| The `setsid' function returns the new process group ID of the |
| calling process if successful. A return value of `-1' indicates an |
| error. The following `errno' error conditions are defined for this |
| function: |
| |
| `EPERM' |
| The calling process is already a process group leader, or |
| there is already another process group around that has the |
| same process group ID. |
| |
| -- Function: pid_t getsid (pid_t PID) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `getsid' function returns the process group ID of the session |
| leader of the specified process. If a PID is `0', the process |
| group ID of the session leader of the current process is returned. |
| |
| In case of error `-1' is returned and `errno' is set. The |
| following `errno' error conditions are defined for this function: |
| |
| `ESRCH' |
| There is no process with the given process ID PID. |
| |
| `EPERM' |
| The calling process and the process specified by PID are in |
| different sessions, and the implementation doesn't allow to |
| access the process group ID of the session leader of the |
| process with ID PID from the calling process. |
| |
| -- Function: pid_t getpgrp (void) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `getpgrp' function returns the process group ID of the calling |
| process. |
| |
| -- Function: int getpgid (pid_t PID) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `getpgid' function returns the process group ID of the process |
| PID. You can supply a value of `0' for the PID argument to get |
| information about the calling process. |
| |
| In case of error `-1' is returned and `errno' is set. The |
| following `errno' error conditions are defined for this function: |
| |
| `ESRCH' |
| There is no process with the given process ID PID. The |
| calling process and the process specified by PID are in |
| different sessions, and the implementation doesn't allow to |
| access the process group ID of the process with ID PID from |
| the calling process. |
| |
| -- Function: int setpgid (pid_t PID, pid_t PGID) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `setpgid' function puts the process PID into the process group |
| PGID. As a special case, either PID or PGID can be zero to |
| indicate the process ID of the calling process. |
| |
| If the operation is successful, `setpgid' returns zero. Otherwise |
| it returns `-1'. The following `errno' error conditions are |
| defined for this function: |
| |
| `EACCES' |
| The child process named by PID has executed an `exec' |
| function since it was forked. |
| |
| `EINVAL' |
| The value of the PGID is not valid. |
| |
| `ENOSYS' |
| The system doesn't support job control. |
| |
| `EPERM' |
| The process indicated by the PID argument is a session leader, |
| or is not in the same session as the calling process, or the |
| value of the PGID argument doesn't match a process group ID |
| in the same session as the calling process. |
| |
| `ESRCH' |
| The process indicated by the PID argument is not the calling |
| process or a child of the calling process. |
| |
| -- Function: int setpgrp (pid_t PID, pid_t PGID) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This is the BSD Unix name for `setpgid'. Both functions do exactly |
| the same thing. |
| |
| |
| File: libc.info, Node: Terminal Access Functions, Prev: Process Group Functions, Up: Functions for Job Control |
| |
| 28.6.3 Functions for Controlling Terminal Access |
| ------------------------------------------------ |
| |
| These are the functions for reading or setting the foreground process |
| group of a terminal. You should include the header files `sys/types.h' |
| and `unistd.h' in your application to use these functions. |
| |
| Although these functions take a file descriptor argument to specify |
| the terminal device, the foreground job is associated with the terminal |
| file itself and not a particular open file descriptor. |
| |
| -- Function: pid_t tcgetpgrp (int FILEDES) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function returns the process group ID of the foreground |
| process group associated with the terminal open on descriptor |
| FILEDES. |
| |
| If there is no foreground process group, the return value is a |
| number greater than `1' that does not match the process group ID |
| of any existing process group. This can happen if all of the |
| processes in the job that was formerly the foreground job have |
| terminated, and no other job has yet been moved into the |
| foreground. |
| |
| In case of an error, a value of `-1' is returned. The following |
| `errno' error conditions are defined for this function: |
| |
| `EBADF' |
| The FILEDES argument is not a valid file descriptor. |
| |
| `ENOSYS' |
| The system doesn't support job control. |
| |
| `ENOTTY' |
| The terminal file associated with the FILEDES argument isn't |
| the controlling terminal of the calling process. |
| |
| -- Function: int tcsetpgrp (int FILEDES, pid_t PGID) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is used to set a terminal's foreground process group |
| ID. The argument FILEDES is a descriptor which specifies the |
| terminal; PGID specifies the process group. The calling process |
| must be a member of the same session as PGID and must have the same |
| controlling terminal. |
| |
| For terminal access purposes, this function is treated as output. |
| If it is called from a background process on its controlling |
| terminal, normally all processes in the process group are sent a |
| `SIGTTOU' signal. The exception is if the calling process itself |
| is ignoring or blocking `SIGTTOU' signals, in which case the |
| operation is performed and no signal is sent. |
| |
| If successful, `tcsetpgrp' returns `0'. A return value of `-1' |
| indicates an error. The following `errno' error conditions are |
| defined for this function: |
| |
| `EBADF' |
| The FILEDES argument is not a valid file descriptor. |
| |
| `EINVAL' |
| The PGID argument is not valid. |
| |
| `ENOSYS' |
| The system doesn't support job control. |
| |
| `ENOTTY' |
| The FILEDES isn't the controlling terminal of the calling |
| process. |
| |
| `EPERM' |
| The PGID isn't a process group in the same session as the |
| calling process. |
| |
| -- Function: pid_t tcgetsid (int FILDES) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is used to obtain the process group ID of the session |
| for which the terminal specified by FILDES is the controlling |
| terminal. If the call is successful the group ID is returned. |
| Otherwise the return value is `(pid_t) -1' and the global variable |
| `errno' is set to the following value: |
| `EBADF' |
| The FILEDES argument is not a valid file descriptor. |
| |
| `ENOTTY' |
| The calling process does not have a controlling terminal, or |
| the file is not the controlling terminal. |
| |
| |
| File: libc.info, Node: Name Service Switch, Next: Users and Groups, Prev: Job Control, Up: Top |
| |
| 29 System Databases and Name Service Switch |
| ******************************************* |
| |
| Various functions in the C Library need to be configured to work |
| correctly in the local environment. Traditionally, this was done by |
| using files (e.g., `/etc/passwd'), but other nameservices (like the |
| Network Information Service (NIS) and the Domain Name Service (DNS)) |
| became popular, and were hacked into the C library, usually with a fixed |
| search order. |
| |
| The GNU C Library contains a cleaner solution to this problem. It is |
| designed after a method used by Sun Microsystems in the C library of |
| Solaris 2. The GNU C Library follows their name and calls this scheme |
| "Name Service Switch" (NSS). |
| |
| Though the interface might be similar to Sun's version there is no |
| common code. We never saw any source code of Sun's implementation and |
| so the internal interface is incompatible. This also manifests in the |
| file names we use as we will see later. |
| |
| * Menu: |
| |
| * NSS Basics:: What is this NSS good for. |
| * NSS Configuration File:: Configuring NSS. |
| * NSS Module Internals:: How does it work internally. |
| * Extending NSS:: What to do to add services or databases. |
| |
| |
| File: libc.info, Node: NSS Basics, Next: NSS Configuration File, Prev: Name Service Switch, Up: Name Service Switch |
| |
| 29.1 NSS Basics |
| =============== |
| |
| The basic idea is to put the implementation of the different services |
| offered to access the databases in separate modules. This has some |
| advantages: |
| |
| 1. Contributors can add new services without adding them to the GNU C |
| Library. |
| |
| 2. The modules can be updated separately. |
| |
| 3. The C library image is smaller. |
| |
| To fulfill the first goal above, the ABI of the modules will be |
| described below. For getting the implementation of a new service right |
| it is important to understand how the functions in the modules get |
| called. They are in no way designed to be used by the programmer |
| directly. Instead the programmer should only use the documented and |
| standardized functions to access the databases. |
| |
| The databases available in the NSS are |
| |
| `aliases' |
| Mail aliases |
| |
| `ethers' |
| Ethernet numbers, |
| |
| `group' |
| Groups of users, *note Group Database::. |
| |
| `hosts' |
| Host names and numbers, *note Host Names::. |
| |
| `netgroup' |
| Network wide list of host and users, *note Netgroup Database::. |
| |
| `networks' |
| Network names and numbers, *note Networks Database::. |
| |
| `protocols' |
| Network protocols, *note Protocols Database::. |
| |
| `passwd' |
| User identities, *note User Database::. |
| |
| `rpc' |
| Remote procedure call names and numbers. |
| |
| `services' |
| Network services, *note Services Database::. |
| |
| `shadow' |
| User passphrase hashes and related information. |
| |
| There will be some more added later (`automount', `bootparams', |
| `netmasks', and `publickey'). |
| |
| |
| File: libc.info, Node: NSS Configuration File, Next: NSS Module Internals, Prev: NSS Basics, Up: Name Service Switch |
| |
| 29.2 The NSS Configuration File |
| =============================== |
| |
| Somehow the NSS code must be told about the wishes of the user. For |
| this reason there is the file `/etc/nsswitch.conf'. For each database, |
| this file contains a specification of how the lookup process should |
| work. The file could look like this: |
| |
| # /etc/nsswitch.conf |
| # |
| # Name Service Switch configuration file. |
| # |
| |
| passwd: db files nis |
| shadow: files |
| group: db files nis |
| |
| hosts: files nisplus nis dns |
| networks: nisplus [NOTFOUND=return] files |
| |
| ethers: nisplus [NOTFOUND=return] db files |
| protocols: nisplus [NOTFOUND=return] db files |
| rpc: nisplus [NOTFOUND=return] db files |
| services: nisplus [NOTFOUND=return] db files |
| |
| The first column is the database as you can guess from the table |
| above. The rest of the line specifies how the lookup process works. |
| Please note that you specify the way it works for each database |
| individually. This cannot be done with the old way of a monolithic |
| implementation. |
| |
| The configuration specification for each database can contain two |
| different items: |
| |
| * the service specification like `files', `db', or `nis'. |
| |
| * the reaction on lookup result like `[NOTFOUND=return]'. |
| |
| * Menu: |
| |
| * Services in the NSS configuration:: Service names in the NSS configuration. |
| * Actions in the NSS configuration:: React appropriately to the lookup result. |
| * Notes on NSS Configuration File:: Things to take care about while |
| configuring NSS. |
| |
| |
| File: libc.info, Node: Services in the NSS configuration, Next: Actions in the NSS configuration, Prev: NSS Configuration File, Up: NSS Configuration File |
| |
| 29.2.1 Services in the NSS configuration File |
| --------------------------------------------- |
| |
| The above example file mentions five different services: `files', `db', |
| `dns', `nis', and `nisplus'. This does not mean these services are |
| available on all sites and neither does it mean these are all the |
| services which will ever be available. |
| |
| In fact, these names are simply strings which the NSS code uses to |
| find the implicitly addressed functions. The internal interface will be |
| described later. Visible to the user are the modules which implement an |
| individual service. |
| |
| Assume the service NAME shall be used for a lookup. The code for |
| this service is implemented in a module called `libnss_NAME'. On a |
| system supporting shared libraries this is in fact a shared library |
| with the name (for example) `libnss_NAME.so.2'. The number at the end |
| is the currently used version of the interface which will not change |
| frequently. Normally the user should not have to be cognizant of these |
| files since they should be placed in a directory where they are found |
| automatically. Only the names of all available services are important. |
| |
| |
| File: libc.info, Node: Actions in the NSS configuration, Next: Notes on NSS Configuration File, Prev: Services in the NSS configuration, Up: NSS Configuration File |
| |
| 29.2.2 Actions in the NSS configuration |
| --------------------------------------- |
| |
| The second item in the specification gives the user much finer control |
| on the lookup process. Action items are placed between two service |
| names and are written within brackets. The general form is |
| |
| `[' ( `!'? STATUS `=' ACTION )+ `]' |
| |
| where |
| |
| STATUS => success | notfound | unavail | tryagain |
| ACTION => return | continue |
| |
| The case of the keywords is insignificant. The STATUS values are |
| the results of a call to a lookup function of a specific service. They |
| mean: |
| |
| `success' |
| No error occurred and the wanted entry is returned. The default |
| action for this is `return'. |
| |
| `notfound' |
| The lookup process works ok but the needed value was not found. |
| The default action is `continue'. |
| |
| `unavail' |
| The service is permanently unavailable. This can either mean the |
| needed file is not available, or, for DNS, the server is not |
| available or does not allow queries. The default action is |
| `continue'. |
| |
| `tryagain' |
| The service is temporarily unavailable. This could mean a file is |
| locked or a server currently cannot accept more connections. The |
| default action is `continue'. |
| |
| The ACTION values mean: |
| |
| `return' |
| If the status matches, stop the lookup process at this service |
| specification. If an entry is available, provide it to the |
| application. If an error occurred, report it to the application. |
| In case of a prior `merge' action, the data is combined with |
| previous lookup results, as explained below. |
| |
| `continue' |
| If the status matches, proceed with the lookup process at the next |
| entry, discarding the result of the current lookup (and any merged |
| data). An exception is the `initgroups' database and the |
| `success' status, where `continue' acts like `merge' below. |
| |
| `merge' |
| Proceed with the lookup process, retaining the current lookup |
| result. This action is useful only with the `success' status. If |
| a subsequent service lookup succeeds and has a matching `return' |
| specification, the results are merged, the lookup process ends, |
| and the merged results are returned to the application. If the |
| following service has a matching `merge' action, the lookup |
| process continues, retaining the combined data from this and any |
| previous lookups. |
| |
| After a `merge' action, errors from subsequent lookups are ignored, |
| and the data gathered so far will be returned. |
| |
| The `merge' only applies to the `success' status. It is currently |
| implemented for the `group' database and its group members field, |
| `gr_mem'. If specified for other databases, it causes the lookup |
| to fail (if the STATUS matches). |
| |
| When processing `merge' for `group' membership, the group GID and |
| name must be identical for both entries. If only one or the other |
| is a match, the behavior is undefined. |
| |
| |
| If we have a line like |
| |
| ethers: nisplus [NOTFOUND=return] db files |
| |
| this is equivalent to |
| |
| ethers: nisplus [SUCCESS=return NOTFOUND=return UNAVAIL=continue |
| TRYAGAIN=continue] |
| db [SUCCESS=return NOTFOUND=continue UNAVAIL=continue |
| TRYAGAIN=continue] |
| files |
| |
| (except that it would have to be written on one line). The default |
| value for the actions are normally what you want, and only need to be |
| changed in exceptional cases. |
| |
| If the optional `!' is placed before the STATUS this means the |
| following action is used for all statuses but STATUS itself. I.e., `!' |
| is negation as in the C language (and others). |
| |
| Before we explain the exception which makes this action item |
| necessary one more remark: obviously it makes no sense to add another |
| action item after the `files' service. Since there is no other service |
| following the action _always_ is `return'. |
| |
| Now, why is this `[NOTFOUND=return]' action useful? To understand |
| this we should know that the `nisplus' service is often complete; i.e., |
| if an entry is not available in the NIS+ tables it is not available |
| anywhere else. This is what is expressed by this action item: it is |
| useless to examine further services since they will not give us a |
| result. |
| |
| The situation would be different if the NIS+ service is not available |
| because the machine is booting. In this case the return value of the |
| lookup function is not `notfound' but instead `unavail'. And as you |
| can see in the complete form above: in this situation the `db' and |
| `files' services are used. Neat, isn't it? The system administrator |
| need not pay special care for the time the system is not completely |
| ready to work (while booting or shutdown or network problems). |
| |
| |
| File: libc.info, Node: Notes on NSS Configuration File, Prev: Actions in the NSS configuration, Up: NSS Configuration File |
| |
| 29.2.3 Notes on the NSS Configuration File |
| ------------------------------------------ |
| |
| Finally a few more hints. The NSS implementation is not completely |
| helpless if `/etc/nsswitch.conf' does not exist. For all supported |
| databases there is a default value so it should normally be possible to |
| get the system running even if the file is corrupted or missing. |
| |
| For the `hosts' and `networks' databases the default value is `dns |
| [!UNAVAIL=return] files'. I.e., the system is prepared for the DNS |
| service not to be available but if it is available the answer it |
| returns is definitive. |
| |
| The `passwd', `group', and `shadow' databases are traditionally |
| handled in a special way. The appropriate files in the `/etc' |
| directory are read but if an entry with a name starting with a `+' |
| character is found NIS is used. This kind of lookup remains possible |
| if the GNU C Library was configured with the `--enable-obsolete-nsl' |
| option and the special lookup service `compat' is used. If the GNU C |
| Library was configured with the `--enable-obsolete-nsl' option the |
| default value for the three databases above is `compat |
| [NOTFOUND=return] files'. If the `--enable-obsolete-nsl' option was |
| not used the default value for the services is `files'. |
| |
| For all other databases the default value is `files' unless the GNU |
| C Library was configured with `--enable-obsolete-rpc' option, in which |
| case it the default value is `nis [NOTFOUND=return] files'. |
| |
| A second point is that the user should try to optimize the lookup |
| process. The different service have different response times. A |
| simple file look up on a local file could be fast, but if the file is |
| long and the needed entry is near the end of the file this may take |
| quite some time. In this case it might be better to use the `db' |
| service which allows fast local access to large data sets. |
| |
| Often the situation is that some global information like NIS must be |
| used. So it is unavoidable to use service entries like `nis' etc. But |
| one should avoid slow services like this if possible. |
| |
| |
| File: libc.info, Node: NSS Module Internals, Next: Extending NSS, Prev: NSS Configuration File, Up: Name Service Switch |
| |
| 29.3 NSS Module Internals |
| ========================= |
| |
| Now it is time to describe what the modules look like. The functions |
| contained in a module are identified by their names. I.e., there is no |
| jump table or the like. How this is done is of no interest here; those |
| interested in this topic should read about Dynamic Linking. |
| |
| * Menu: |
| |
| * NSS Module Names:: Construction of the interface function of |
| the NSS modules. |
| * NSS Modules Interface:: Programming interface in the NSS module |
| functions. |
| |
| |
| File: libc.info, Node: NSS Module Names, Next: NSS Modules Interface, Prev: NSS Module Internals, Up: NSS Module Internals |
| |
| 29.3.1 The Naming Scheme of the NSS Modules |
| ------------------------------------------- |
| |
| The name of each function consists of various parts: |
| |
| _nss_SERVICE_FUNCTION |
| |
| SERVICE of course corresponds to the name of the module this |
| function is found in.(1) The FUNCTION part is derived from the |
| interface function in the C library itself. If the user calls the |
| function `gethostbyname' and the service used is `files' the function |
| |
| _nss_files_gethostbyname_r |
| |
| in the module |
| |
| libnss_files.so.2 |
| |
| is used. You see, what is explained above in not the whole truth. In |
| fact the NSS modules only contain reentrant versions of the lookup |
| functions. I.e., if the user would call the `gethostbyname_r' function |
| this also would end in the above function. For all user interface |
| functions the C library maps this call to a call to the reentrant |
| function. For reentrant functions this is trivial since the interface |
| is (nearly) the same. For the non-reentrant version the library keeps |
| internal buffers which are used to replace the user supplied buffer. |
| |
| I.e., the reentrant functions _can_ have counterparts. No service |
| module is forced to have functions for all databases and all kinds to |
| access them. If a function is not available it is simply treated as if |
| the function would return `unavail' (*note Actions in the NSS |
| configuration::). |
| |
| The file name `libnss_files.so.2' would be on a Solaris 2 system |
| `nss_files.so.2'. This is the difference mentioned above. Sun's NSS |
| modules are usable as modules which get indirectly loaded only. |
| |
| The NSS modules in the GNU C Library are prepared to be used as |
| normal libraries themselves. This is _not_ true at the moment, though. |
| However, the organization of the name space in the modules does not |
| make it impossible like it is for Solaris. Now you can see why the |
| modules are still libraries.(2) |
| |
| ---------- Footnotes ---------- |
| |
| (1) Now you might ask why this information is duplicated. The |
| answer is that we want to make it possible to link directly with these |
| shared objects. |
| |
| (2) There is a second explanation: we were too lazy to change the |
| Makefiles to allow the generation of shared objects not starting with |
| `lib' but don't tell this to anybody. |
| |
| |
| File: libc.info, Node: NSS Modules Interface, Prev: NSS Module Names, Up: NSS Module Internals |
| |
| 29.3.2 The Interface of the Function in NSS Modules |
| --------------------------------------------------- |
| |
| Now we know about the functions contained in the modules. It is now |
| time to describe the types. When we mentioned the reentrant versions of |
| the functions above, this means there are some additional arguments |
| (compared with the standard, non-reentrant versions). The prototypes |
| for the non-reentrant and reentrant versions of our function above are: |
| |
| struct hostent *gethostbyname (const char *name) |
| |
| int gethostbyname_r (const char *name, struct hostent *result_buf, |
| char *buf, size_t buflen, struct hostent **result, |
| int *h_errnop) |
| |
| The actual prototype of the function in the NSS modules in this case is |
| |
| enum nss_status _nss_files_gethostbyname_r (const char *name, |
| struct hostent *result_buf, |
| char *buf, size_t buflen, |
| int *errnop, int *h_errnop) |
| |
| I.e., the interface function is in fact the reentrant function with |
| the change of the return value, the omission of the RESULT parameter, |
| and the addition of the ERRNOP parameter. While the user-level |
| function returns a pointer to the result the reentrant function return |
| an `enum nss_status' value: |
| |
| `NSS_STATUS_TRYAGAIN' |
| numeric value `-2' |
| |
| `NSS_STATUS_UNAVAIL' |
| numeric value `-1' |
| |
| `NSS_STATUS_NOTFOUND' |
| numeric value `0' |
| |
| `NSS_STATUS_SUCCESS' |
| numeric value `1' |
| |
| Now you see where the action items of the `/etc/nsswitch.conf' file are |
| used. |
| |
| If you study the source code you will find there is a fifth value: |
| `NSS_STATUS_RETURN'. This is an internal use only value, used by a few |
| functions in places where none of the above value can be used. If |
| necessary the source code should be examined to learn about the details. |
| |
| In case the interface function has to return an error it is important |
| that the correct error code is stored in `*ERRNOP'. Some return status |
| values have only one associated error code, others have more. |
| |
| `NSS_STATUS_TRYAGAIN' `EAGAIN' One of the functions used ran |
| temporarily out of resources or a |
| service is currently not available. |
| `ERANGE' The provided buffer is not large |
| enough. The function should be |
| called again with a larger buffer. |
| `NSS_STATUS_UNAVAIL' `ENOENT' A necessary input file cannot be |
| found. |
| `NSS_STATUS_NOTFOUND' `ENOENT' The requested entry is not |
| available. |
| `NSS_STATUS_NOTFOUND' `SUCCESS' There are no entries. Use this to |
| avoid returning errors for inactive |
| services which may be enabled at a |
| later time. This is not the same as |
| the service being temporarily |
| unavailable. |
| |
| These are proposed values. There can be other error codes and the |
| described error codes can have different meaning. *With one |
| exception:* when returning `NSS_STATUS_TRYAGAIN' the error code |
| `ERANGE' _must_ mean that the user provided buffer is too small. |
| Everything else is non-critical. |
| |
| In statically linked programs, the main application and NSS modules |
| do not share the same thread-local variable `errno', which is the |
| reason why there is an explicit ERRNOP function argument. |
| |
| The above function has something special which is missing for almost |
| all the other module functions. There is an argument H_ERRNOP. This |
| points to a variable which will be filled with the error code in case |
| the execution of the function fails for some reason. (In statically |
| linked programs, the thread-local variable `h_errno' is not shared with |
| the main application.) |
| |
| The `getXXXbyYYY' functions are the most important functions in the |
| NSS modules. But there are others which implement the other ways to |
| access system databases (say for the user database, there are |
| `setpwent', `getpwent', and `endpwent'). These will be described in |
| more detail later. Here we give a general way to determine the |
| signature of the module function: |
| |
| * the return value is `enum nss_status'; |
| |
| * the name (*note NSS Module Names::); |
| |
| * the first arguments are identical to the arguments of the |
| non-reentrant function; |
| |
| * the next four arguments are: |
| |
| `STRUCT_TYPE *result_buf' |
| pointer to buffer where the result is stored. `STRUCT_TYPE' |
| is normally a struct which corresponds to the database. |
| |
| `char *buffer' |
| pointer to a buffer where the function can store additional |
| data for the result etc. |
| |
| `size_t buflen' |
| length of the buffer pointed to by BUFFER. |
| |
| `int *errnop' |
| the low-level error code to return to the application. If |
| the return value is not `NSS_STATUS_SUCCESS', `*ERRNOP' needs |
| to be set to a non-zero value. An NSS module should never set |
| `*ERRNOP' to zero. The value `ERANGE' is special, as |
| described above. |
| |
| * possibly a last argument H_ERRNOP, for the host name and network |
| name lookup functions. If the return value is not |
| `NSS_STATUS_SUCCESS', `*H_ERRNOP' needs to be set to a non-zero |
| value. A generic error code is `NETDB_INTERNAL', which instructs |
| the caller to examine `*ERRNOP' for further details. (This |
| includes the `ERANGE' special case.) |
| |
| This table is correct for all functions but the `set...ent' and |
| `end...ent' functions. |
| |
| |
| File: libc.info, Node: Extending NSS, Prev: NSS Module Internals, Up: Name Service Switch |
| |
| 29.4 Extending NSS |
| ================== |
| |
| One of the advantages of NSS mentioned above is that it can be extended |
| quite easily. There are two ways in which the extension can happen: |
| adding another database or adding another service. The former is |
| normally done only by the C library developers. It is here only |
| important to remember that adding another database is independent from |
| adding another service because a service need not support all databases |
| or lookup functions. |
| |
| A designer/implementer of a new service is therefore free to choose |
| the databases s/he is interested in and leave the rest for later (or |
| completely aside). |
| |
| * Menu: |
| |
| * Adding another Service to NSS:: What is to do to add a new service. |
| * NSS Module Function Internals:: Guidelines for writing new NSS |
| service functions. |
| |
| |
| File: libc.info, Node: Adding another Service to NSS, Next: NSS Module Function Internals, Prev: Extending NSS, Up: Extending NSS |
| |
| 29.4.1 Adding another Service to NSS |
| ------------------------------------ |
| |
| The sources for a new service need not (and should not) be part of the |
| GNU C Library itself. The developer retains complete control over the |
| sources and its development. The links between the C library and the |
| new service module consists solely of the interface functions. |
| |
| Each module is designed following a specific interface specification. |
| For now the version is 2 (the interface in version 1 was not adequate) |
| and this manifests in the version number of the shared library object of |
| the NSS modules: they have the extension `.2'. If the interface |
| changes again in an incompatible way, this number will be increased. |
| Modules using the old interface will still be usable. |
| |
| Developers of a new service will have to make sure that their module |
| is created using the correct interface number. This means the file |
| itself must have the correct name and on ELF systems the "soname" |
| (Shared Object Name) must also have this number. Building a module |
| from a bunch of object files on an ELF system using GNU CC could be |
| done like this: |
| |
| gcc -shared -o libnss_NAME.so.2 -Wl,-soname,libnss_NAME.so.2 OBJECTS |
| |
| *note Options for Linking: (gcc)Link Options, to learn more about this |
| command line. |
| |
| To use the new module the library must be able to find it. This can |
| be achieved by using options for the dynamic linker so that it will |
| search the directory where the binary is placed. For an ELF system |
| this could be done by adding the wanted directory to the value of |
| `LD_LIBRARY_PATH'. |
| |
| But this is not always possible since some programs (those which run |
| under IDs which do not belong to the user) ignore this variable. |
| Therefore the stable version of the module should be placed into a |
| directory which is searched by the dynamic linker. Normally this should |
| be the directory `$prefix/lib', where `$prefix' corresponds to the |
| value given to configure using the `--prefix' option. But be careful: |
| this should only be done if it is clear the module does not cause any |
| harm. System administrators should be careful. |
| |
| |
| File: libc.info, Node: NSS Module Function Internals, Prev: Adding another Service to NSS, Up: Extending NSS |
| |
| 29.4.2 Internals of the NSS Module Functions |
| -------------------------------------------- |
| |
| Until now we only provided the syntactic interface for the functions in |
| the NSS module. In fact there is not much more we can say since the |
| implementation obviously is different for each function. But a few |
| general rules must be followed by all functions. |
| |
| In fact there are four kinds of different functions which may appear |
| in the interface. All derive from the traditional ones for system |
| databases. DB in the following table is normally an abbreviation for |
| the database (e.g., it is `pw' for the user database). |
| |
| `enum nss_status _nss_DATABASE_setDBent (void)' |
| This function prepares the service for following operations. For a |
| simple file based lookup this means files could be opened, for |
| other services this function simply is a noop. |
| |
| One special case for this function is that it takes an additional |
| argument for some DATABASEs (i.e., the interface is `int setDBent |
| (int)'). *note Host Names::, which describes the `sethostent' |
| function. |
| |
| The return value should be NSS_STATUS_SUCCESS or according to the |
| table above in case of an error (*note NSS Modules Interface::). |
| |
| `enum nss_status _nss_DATABASE_endDBent (void)' |
| This function simply closes all files which are still open or |
| removes buffer caches. If there are no files or buffers to remove |
| this is again a simple noop. |
| |
| There normally is no return value other than NSS_STATUS_SUCCESS. |
| |
| `enum nss_status _nss_DATABASE_getDBent_r (STRUCTURE *result, char *buffer, size_t buflen, int *errnop)' |
| Since this function will be called several times in a row to |
| retrieve one entry after the other it must keep some kind of |
| state. But this also means the functions are not really |
| reentrant. They are reentrant only in that simultaneous calls to |
| this function will not try to write the retrieved data in the same |
| place (as it would be the case for the non-reentrant functions); |
| instead, it writes to the structure pointed to by the RESULT |
| parameter. But the calls share a common state and in the case of |
| a file access this means they return neighboring entries in the |
| file. |
| |
| The buffer of length BUFLEN pointed to by BUFFER can be used for |
| storing some additional data for the result. It is _not_ |
| guaranteed that the same buffer will be passed for the next call |
| of this function. Therefore one must not misuse this buffer to |
| save some state information from one call to another. |
| |
| Before the function returns with a failure code, the implementation |
| should store the value of the local `errno' variable in the |
| variable pointed to be ERRNOP. This is important to guarantee the |
| module working in statically linked programs. The stored value |
| must not be zero. |
| |
| As explained above this function could also have an additional last |
| argument. This depends on the database used; it happens only for |
| `host' and `networks'. |
| |
| The function shall return `NSS_STATUS_SUCCESS' as long as there are |
| more entries. When the last entry was read it should return |
| `NSS_STATUS_NOTFOUND'. When the buffer given as an argument is too |
| small for the data to be returned `NSS_STATUS_TRYAGAIN' should be |
| returned. When the service was not formerly initialized by a call |
| to `_nss_DATABASE_setDBent' all return values allowed for this |
| function can also be returned here. |
| |
| `enum nss_status _nss_DATABASE_getDBbyXX_r (PARAMS, STRUCTURE *result, char *buffer, size_t buflen, int *errnop)' |
| This function shall return the entry from the database which is |
| addressed by the PARAMS. The type and number of these arguments |
| vary. It must be individually determined by looking to the |
| user-level interface functions. All arguments given to the |
| non-reentrant version are here described by PARAMS. |
| |
| The result must be stored in the structure pointed to by RESULT. |
| If there are additional data to return (say strings, where the |
| RESULT structure only contains pointers) the function must use the |
| BUFFER of length BUFLEN. There must not be any references to |
| non-constant global data. |
| |
| The implementation of this function should honor the STAYOPEN flag |
| set by the `setDBent' function whenever this makes sense. |
| |
| Before the function returns, the implementation should store the |
| value of the local `errno' variable in the variable pointed to by |
| ERRNOP. This is important to guarantee the module works in |
| statically linked programs. |
| |
| Again, this function takes an additional last argument for the |
| `host' and `networks' database. |
| |
| The return value should as always follow the rules given above |
| (*note NSS Modules Interface::). |
| |
| |
| |
| File: libc.info, Node: Users and Groups, Next: System Management, Prev: Name Service Switch, Up: Top |
| |
| 30 Users and Groups |
| ******************* |
| |
| Every user who can log in on the system is identified by a unique number |
| called the "user ID". Each process has an effective user ID which says |
| which user's access permissions it has. |
| |
| Users are classified into "groups" for access control purposes. Each |
| process has one or more "group ID values" which say which groups the |
| process can use for access to files. |
| |
| The effective user and group IDs of a process collectively form its |
| "persona". This determines which files the process can access. |
| Normally, a process inherits its persona from the parent process, but |
| under special circumstances a process can change its persona and thus |
| change its access permissions. |
| |
| Each file in the system also has a user ID and a group ID. Access |
| control works by comparing the user and group IDs of the file with those |
| of the running process. |
| |
| The system keeps a database of all the registered users, and another |
| database of all the defined groups. There are library functions you |
| can use to examine these databases. |
| |
| * Menu: |
| |
| * User and Group IDs:: Each user has a unique numeric ID; |
| likewise for groups. |
| * Process Persona:: The user IDs and group IDs of a process. |
| * Why Change Persona:: Why a program might need to change |
| its user and/or group IDs. |
| * How Change Persona:: Changing the user and group IDs. |
| * Reading Persona:: How to examine the user and group IDs. |
| |
| * Setting User ID:: Functions for setting the user ID. |
| * Setting Groups:: Functions for setting the group IDs. |
| |
| * Enable/Disable Setuid:: Turning setuid access on and off. |
| * Setuid Program Example:: The pertinent parts of one sample program. |
| * Tips for Setuid:: How to avoid granting unlimited access. |
| |
| * Who Logged In:: Getting the name of the user who logged in, |
| or of the real user ID of the current process. |
| |
| * User Accounting Database:: Keeping information about users and various |
| actions in databases. |
| |
| * User Database:: Functions and data structures for |
| accessing the user database. |
| * Group Database:: Functions and data structures for |
| accessing the group database. |
| * Database Example:: Example program showing the use of database |
| inquiry functions. |
| * Netgroup Database:: Functions for accessing the netgroup database. |
| |
| |
| File: libc.info, Node: User and Group IDs, Next: Process Persona, Up: Users and Groups |
| |
| 30.1 User and Group IDs |
| ======================= |
| |
| Each user account on a computer system is identified by a "user name" |
| (or "login name") and "user ID". Normally, each user name has a unique |
| user ID, but it is possible for several login names to have the same |
| user ID. The user names and corresponding user IDs are stored in a |
| data base which you can access as described in *note User Database::. |
| |
| Users are classified in "groups". Each user name belongs to one |
| "default group" and may also belong to any number of "supplementary |
| groups". Users who are members of the same group can share resources |
| (such as files) that are not accessible to users who are not a member |
| of that group. Each group has a "group name" and "group ID". *Note |
| Group Database::, for how to find information about a group ID or group |
| name. |
| |
| |
| File: libc.info, Node: Process Persona, Next: Why Change Persona, Prev: User and Group IDs, Up: Users and Groups |
| |
| 30.2 The Persona of a Process |
| ============================= |
| |
| At any time, each process has an "effective user ID", a "effective |
| group ID", and a set of "supplementary group IDs". These IDs determine |
| the privileges of the process. They are collectively called the |
| "persona" of the process, because they determine "who it is" for |
| purposes of access control. |
| |
| Your login shell starts out with a persona which consists of your |
| user ID, your default group ID, and your supplementary group IDs (if |
| you are in more than one group). In normal circumstances, all your |
| other processes inherit these values. |
| |
| A process also has a "real user ID" which identifies the user who |
| created the process, and a "real group ID" which identifies that user's |
| default group. These values do not play a role in access control, so |
| we do not consider them part of the persona. But they are also |
| important. |
| |
| Both the real and effective user ID can be changed during the |
| lifetime of a process. *Note Why Change Persona::. |
| |
| For details on how a process's effective user ID and group IDs affect |
| its permission to access files, see *note Access Permission::. |
| |
| The effective user ID of a process also controls permissions for |
| sending signals using the `kill' function. *Note Signaling Another |
| Process::. |
| |
| Finally, there are many operations which can only be performed by a |
| process whose effective user ID is zero. A process with this user ID is |
| a "privileged process". Commonly the user name `root' is associated |
| with user ID 0, but there may be other user names with this ID. |
| |
| |
| File: libc.info, Node: Why Change Persona, Next: How Change Persona, Prev: Process Persona, Up: Users and Groups |
| |
| 30.3 Why Change the Persona of a Process? |
| ========================================= |
| |
| The most obvious situation where it is necessary for a process to change |
| its user and/or group IDs is the `login' program. When `login' starts |
| running, its user ID is `root'. Its job is to start a shell whose user |
| and group IDs are those of the user who is logging in. (To accomplish |
| this fully, `login' must set the real user and group IDs as well as its |
| persona. But this is a special case.) |
| |
| The more common case of changing persona is when an ordinary user |
| program needs access to a resource that wouldn't ordinarily be |
| accessible to the user actually running it. |
| |
| For example, you may have a file that is controlled by your program |
| but that shouldn't be read or modified directly by other users, either |
| because it implements some kind of locking protocol, or because you want |
| to preserve the integrity or privacy of the information it contains. |
| This kind of restricted access can be implemented by having the program |
| change its effective user or group ID to match that of the resource. |
| |
| Thus, imagine a game program that saves scores in a file. The game |
| program itself needs to be able to update this file no matter who is |
| running it, but if users can write the file without going through the |
| game, they can give themselves any scores they like. Some people |
| consider this undesirable, or even reprehensible. It can be prevented |
| by creating a new user ID and login name (say, `games') to own the |
| scores file, and make the file writable only by this user. Then, when |
| the game program wants to update this file, it can change its effective |
| user ID to be that for `games'. In effect, the program must adopt the |
| persona of `games' so it can write to the scores file. |
| |
| |
| File: libc.info, Node: How Change Persona, Next: Reading Persona, Prev: Why Change Persona, Up: Users and Groups |
| |
| 30.4 How an Application Can Change Persona |
| ========================================== |
| |
| The ability to change the persona of a process can be a source of |
| unintentional privacy violations, or even intentional abuse. Because of |
| the potential for problems, changing persona is restricted to special |
| circumstances. |
| |
| You can't arbitrarily set your user ID or group ID to anything you |
| want; only privileged processes can do that. Instead, the normal way |
| for a program to change its persona is that it has been set up in |
| advance to change to a particular user or group. This is the function |
| of the setuid and setgid bits of a file's access mode. *Note |
| Permission Bits::. |
| |
| When the setuid bit of an executable file is on, executing that file |
| gives the process a third user ID: the "file user ID". This ID is set |
| to the owner ID of the file. The system then changes the effective |
| user ID to the file user ID. The real user ID remains as it was. |
| Likewise, if the setgid bit is on, the process is given a "file group |
| ID" equal to the group ID of the file, and its effective group ID is |
| changed to the file group ID. |
| |
| If a process has a file ID (user or group), then it can at any time |
| change its effective ID to its real ID and back to its file ID. |
| Programs use this feature to relinquish their special privileges except |
| when they actually need them. This makes it less likely that they can |
| be tricked into doing something inappropriate with their privileges. |
| |
| *Portability Note:* Older systems do not have file IDs. To |
| determine if a system has this feature, you can test the compiler |
| define `_POSIX_SAVED_IDS'. (In the POSIX standard, file IDs are known |
| as saved IDs.) |
| |
| *Note File Attributes::, for a more general discussion of file modes |
| and accessibility. |
| |
| |
| File: libc.info, Node: Reading Persona, Next: Setting User ID, Prev: How Change Persona, Up: Users and Groups |
| |
| 30.5 Reading the Persona of a Process |
| ===================================== |
| |
| Here are detailed descriptions of the functions for reading the user and |
| group IDs of a process, both real and effective. To use these |
| facilities, you must include the header files `sys/types.h' and |
| `unistd.h'. |
| |
| -- Data Type: uid_t |
| This is an integer data type used to represent user IDs. In the |
| GNU C Library, this is an alias for `unsigned int'. |
| |
| -- Data Type: gid_t |
| This is an integer data type used to represent group IDs. In the |
| GNU C Library, this is an alias for `unsigned int'. |
| |
| -- Function: uid_t getuid (void) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `getuid' function returns the real user ID of the process. |
| |
| -- Function: gid_t getgid (void) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `getgid' function returns the real group ID of the process. |
| |
| -- Function: uid_t geteuid (void) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `geteuid' function returns the effective user ID of the |
| process. |
| |
| -- Function: gid_t getegid (void) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `getegid' function returns the effective group ID of the |
| process. |
| |
| -- Function: int getgroups (int COUNT, gid_t *GROUPS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `getgroups' function is used to inquire about the supplementary |
| group IDs of the process. Up to COUNT of these group IDs are |
| stored in the array GROUPS; the return value from the function is |
| the number of group IDs actually stored. If COUNT is smaller than |
| the total number of supplementary group IDs, then `getgroups' |
| returns a value of `-1' and `errno' is set to `EINVAL'. |
| |
| If COUNT is zero, then `getgroups' just returns the total number |
| of supplementary group IDs. On systems that do not support |
| supplementary groups, this will always be zero. |
| |
| Here's how to use `getgroups' to read all the supplementary group |
| IDs: |
| |
| gid_t * |
| read_all_groups (void) |
| { |
| int ngroups = getgroups (0, NULL); |
| gid_t *groups |
| = (gid_t *) xmalloc (ngroups * sizeof (gid_t)); |
| int val = getgroups (ngroups, groups); |
| if (val < 0) |
| { |
| free (groups); |
| return NULL; |
| } |
| return groups; |
| } |
| |
| |
| File: libc.info, Node: Setting User ID, Next: Setting Groups, Prev: Reading Persona, Up: Users and Groups |
| |
| 30.6 Setting the User ID |
| ======================== |
| |
| This section describes the functions for altering the user ID (real |
| and/or effective) of a process. To use these facilities, you must |
| include the header files `sys/types.h' and `unistd.h'. |
| |
| -- Function: int seteuid (uid_t NEWEUID) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| This function sets the effective user ID of a process to NEWEUID, |
| provided that the process is allowed to change its effective user |
| ID. A privileged process (effective user ID zero) can change its |
| effective user ID to any legal value. An unprivileged process |
| with a file user ID can change its effective user ID to its real |
| user ID or to its file user ID. Otherwise, a process may not |
| change its effective user ID at all. |
| |
| The `seteuid' function returns a value of `0' to indicate |
| successful completion, and a value of `-1' to indicate an error. |
| The following `errno' error conditions are defined for this |
| function: |
| |
| `EINVAL' |
| The value of the NEWEUID argument is invalid. |
| |
| `EPERM' |
| The process may not change to the specified ID. |
| |
| Older systems (those without the `_POSIX_SAVED_IDS' feature) do not |
| have this function. |
| |
| -- Function: int setuid (uid_t NEWUID) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| If the calling process is privileged, this function sets both the |
| real and effective user IDs of the process to NEWUID. It also |
| deletes the file user ID of the process, if any. NEWUID may be any |
| legal value. (Once this has been done, there is no way to recover |
| the old effective user ID.) |
| |
| If the process is not privileged, and the system supports the |
| `_POSIX_SAVED_IDS' feature, then this function behaves like |
| `seteuid'. |
| |
| The return values and error conditions are the same as for |
| `seteuid'. |
| |
| -- Function: int setreuid (uid_t RUID, uid_t EUID) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| This function sets the real user ID of the process to RUID and the |
| effective user ID to EUID. If RUID is `-1', it means not to |
| change the real user ID; likewise if EUID is `-1', it means not to |
| change the effective user ID. |
| |
| The `setreuid' function exists for compatibility with 4.3 BSD Unix, |
| which does not support file IDs. You can use this function to |
| swap the effective and real user IDs of the process. (Privileged |
| processes are not limited to this particular usage.) If file IDs |
| are supported, you should use that feature instead of this |
| function. *Note Enable/Disable Setuid::. |
| |
| The return value is `0' on success and `-1' on failure. The |
| following `errno' error conditions are defined for this function: |
| |
| `EPERM' |
| The process does not have the appropriate privileges; you do |
| not have permission to change to the specified ID. |
| |
| |
| File: libc.info, Node: Setting Groups, Next: Enable/Disable Setuid, Prev: Setting User ID, Up: Users and Groups |
| |
| 30.7 Setting the Group IDs |
| ========================== |
| |
| This section describes the functions for altering the group IDs (real |
| and effective) of a process. To use these facilities, you must include |
| the header files `sys/types.h' and `unistd.h'. |
| |
| -- Function: int setegid (gid_t NEWGID) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| This function sets the effective group ID of the process to |
| NEWGID, provided that the process is allowed to change its group |
| ID. Just as with `seteuid', if the process is privileged it may |
| change its effective group ID to any value; if it isn't, but it |
| has a file group ID, then it may change to its real group ID or |
| file group ID; otherwise it may not change its effective group ID. |
| |
| Note that a process is only privileged if its effective _user_ ID |
| is zero. The effective group ID only affects access permissions. |
| |
| The return values and error conditions for `setegid' are the same |
| as those for `seteuid'. |
| |
| This function is only present if `_POSIX_SAVED_IDS' is defined. |
| |
| -- Function: int setgid (gid_t NEWGID) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| This function sets both the real and effective group ID of the |
| process to NEWGID, provided that the process is privileged. It |
| also deletes the file group ID, if any. |
| |
| If the process is not privileged, then `setgid' behaves like |
| `setegid'. |
| |
| The return values and error conditions for `setgid' are the same |
| as those for `seteuid'. |
| |
| -- Function: int setregid (gid_t RGID, gid_t EGID) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| This function sets the real group ID of the process to RGID and |
| the effective group ID to EGID. If RGID is `-1', it means not to |
| change the real group ID; likewise if EGID is `-1', it means not |
| to change the effective group ID. |
| |
| The `setregid' function is provided for compatibility with 4.3 BSD |
| Unix, which does not support file IDs. You can use this function |
| to swap the effective and real group IDs of the process. |
| (Privileged processes are not limited to this usage.) If file IDs |
| are supported, you should use that feature instead of using this |
| function. *Note Enable/Disable Setuid::. |
| |
| The return values and error conditions for `setregid' are the same |
| as those for `setreuid'. |
| |
| `setuid' and `setgid' behave differently depending on whether the |
| effective user ID at the time is zero. If it is not zero, they behave |
| like `seteuid' and `setegid'. If it is, they change both effective and |
| real IDs and delete the file ID. To avoid confusion, we recommend you |
| always use `seteuid' and `setegid' except when you know the effective |
| user ID is zero and your intent is to change the persona permanently. |
| This case is rare--most of the programs that need it, such as `login' |
| and `su', have already been written. |
| |
| Note that if your program is setuid to some user other than `root', |
| there is no way to drop privileges permanently. |
| |
| The system also lets privileged processes change their supplementary |
| group IDs. To use `setgroups' or `initgroups', your programs should |
| include the header file `grp.h'. |
| |
| -- Function: int setgroups (size_t COUNT, const gid_t *GROUPS) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| This function sets the process's supplementary group IDs. It can |
| only be called from privileged processes. The COUNT argument |
| specifies the number of group IDs in the array GROUPS. |
| |
| This function returns `0' if successful and `-1' on error. The |
| following `errno' error conditions are defined for this function: |
| |
| `EPERM' |
| The calling process is not privileged. |
| |
| -- Function: int initgroups (const char *USER, gid_t GROUP) |
| Preliminary: | MT-Safe locale | AS-Unsafe dlopen plugin heap lock |
| | AC-Unsafe corrupt mem fd lock | *Note POSIX Safety Concepts::. |
| |
| The `initgroups' function sets the process's supplementary group |
| IDs to be the normal default for the user name USER. The group |
| GROUP is automatically included. |
| |
| This function works by scanning the group database for all the |
| groups USER belongs to. It then calls `setgroups' with the list it |
| has constructed. |
| |
| The return values and error conditions are the same as for |
| `setgroups'. |
| |
| If you are interested in the groups a particular user belongs to, |
| but do not want to change the process's supplementary group IDs, you |
| can use `getgrouplist'. To use `getgrouplist', your programs should |
| include the header file `grp.h'. |
| |
| -- Function: int getgrouplist (const char *USER, gid_t GROUP, gid_t |
| *GROUPS, int *NGROUPS) |
| Preliminary: | MT-Safe locale | AS-Unsafe dlopen plugin heap lock |
| | AC-Unsafe corrupt mem fd lock | *Note POSIX Safety Concepts::. |
| |
| The `getgrouplist' function scans the group database for all the |
| groups USER belongs to. Up to *NGROUPS group IDs corresponding to |
| these groups are stored in the array GROUPS; the return value from |
| the function is the number of group IDs actually stored. If |
| *NGROUPS is smaller than the total number of groups found, then |
| `getgrouplist' returns a value of `-1' and stores the actual |
| number of groups in *NGROUPS. The group GROUP is automatically |
| included in the list of groups returned by `getgrouplist'. |
| |
| Here's how to use `getgrouplist' to read all supplementary groups |
| for USER: |
| |
| gid_t * |
| supplementary_groups (char *user) |
| { |
| int ngroups = 16; |
| gid_t *groups |
| = (gid_t *) xmalloc (ngroups * sizeof (gid_t)); |
| struct passwd *pw = getpwnam (user); |
| |
| if (pw == NULL) |
| return NULL; |
| |
| if (getgrouplist (pw->pw_name, pw->pw_gid, groups, &ngroups) < 0) |
| { |
| groups = xrealloc (ngroups * sizeof (gid_t)); |
| getgrouplist (pw->pw_name, pw->pw_gid, groups, &ngroups); |
| } |
| return groups; |
| } |
| |
| |
| File: libc.info, Node: Enable/Disable Setuid, Next: Setuid Program Example, Prev: Setting Groups, Up: Users and Groups |
| |
| 30.8 Enabling and Disabling Setuid Access |
| ========================================= |
| |
| A typical setuid program does not need its special access all of the |
| time. It's a good idea to turn off this access when it isn't needed, |
| so it can't possibly give unintended access. |
| |
| If the system supports the `_POSIX_SAVED_IDS' feature, you can |
| accomplish this with `seteuid'. When the game program starts, its real |
| user ID is `jdoe', its effective user ID is `games', and its saved user |
| ID is also `games'. The program should record both user ID values once |
| at the beginning, like this: |
| |
| user_user_id = getuid (); |
| game_user_id = geteuid (); |
| |
| Then it can turn off game file access with |
| |
| seteuid (user_user_id); |
| |
| and turn it on with |
| |
| seteuid (game_user_id); |
| |
| Throughout this process, the real user ID remains `jdoe' and the file |
| user ID remains `games', so the program can always set its effective |
| user ID to either one. |
| |
| On other systems that don't support file user IDs, you can turn |
| setuid access on and off by using `setreuid' to swap the real and |
| effective user IDs of the process, as follows: |
| |
| setreuid (geteuid (), getuid ()); |
| |
| This special case is always allowed--it cannot fail. |
| |
| Why does this have the effect of toggling the setuid access? |
| Suppose a game program has just started, and its real user ID is `jdoe' |
| while its effective user ID is `games'. In this state, the game can |
| write the scores file. If it swaps the two uids, the real becomes |
| `games' and the effective becomes `jdoe'; now the program has only |
| `jdoe' access. Another swap brings `games' back to the effective user |
| ID and restores access to the scores file. |
| |
| In order to handle both kinds of systems, test for the saved user ID |
| feature with a preprocessor conditional, like this: |
| |
| #ifdef _POSIX_SAVED_IDS |
| seteuid (user_user_id); |
| #else |
| setreuid (geteuid (), getuid ()); |
| #endif |
| |
| |
| File: libc.info, Node: Setuid Program Example, Next: Tips for Setuid, Prev: Enable/Disable Setuid, Up: Users and Groups |
| |
| 30.9 Setuid Program Example |
| =========================== |
| |
| Here's an example showing how to set up a program that changes its |
| effective user ID. |
| |
| This is part of a game program called `caber-toss' that manipulates |
| a file `scores' that should be writable only by the game program |
| itself. The program assumes that its executable file will be installed |
| with the setuid bit set and owned by the same user as the `scores' |
| file. Typically, a system administrator will set up an account like |
| `games' for this purpose. |
| |
| The executable file is given mode `4755', so that doing an `ls -l' |
| on it produces output like: |
| |
| -rwsr-xr-x 1 games 184422 Jul 30 15:17 caber-toss |
| |
| The setuid bit shows up in the file modes as the `s'. |
| |
| The scores file is given mode `644', and doing an `ls -l' on it |
| shows: |
| |
| -rw-r--r-- 1 games 0 Jul 31 15:33 scores |
| |
| Here are the parts of the program that show how to set up the changed |
| user ID. This program is conditionalized so that it makes use of the |
| file IDs feature if it is supported, and otherwise uses `setreuid' to |
| swap the effective and real user IDs. |
| |
| #include <stdio.h> |
| #include <sys/types.h> |
| #include <unistd.h> |
| #include <stdlib.h> |
| |
| |
| /* Remember the effective and real UIDs. */ |
| |
| static uid_t euid, ruid; |
| |
| |
| /* Restore the effective UID to its original value. */ |
| |
| void |
| do_setuid (void) |
| { |
| int status; |
| |
| #ifdef _POSIX_SAVED_IDS |
| status = seteuid (euid); |
| #else |
| status = setreuid (ruid, euid); |
| #endif |
| if (status < 0) { |
| fprintf (stderr, "Couldn't set uid.\n"); |
| exit (status); |
| } |
| } |
| |
| |
| /* Set the effective UID to the real UID. */ |
| |
| void |
| undo_setuid (void) |
| { |
| int status; |
| |
| #ifdef _POSIX_SAVED_IDS |
| status = seteuid (ruid); |
| #else |
| status = setreuid (euid, ruid); |
| #endif |
| if (status < 0) { |
| fprintf (stderr, "Couldn't set uid.\n"); |
| exit (status); |
| } |
| } |
| |
| /* Main program. */ |
| |
| int |
| main (void) |
| { |
| /* Remember the real and effective user IDs. */ |
| ruid = getuid (); |
| euid = geteuid (); |
| undo_setuid (); |
| |
| /* Do the game and record the score. */ |
| ... |
| } |
| |
| Notice how the first thing the `main' function does is to set the |
| effective user ID back to the real user ID. This is so that any other |
| file accesses that are performed while the user is playing the game use |
| the real user ID for determining permissions. Only when the program |
| needs to open the scores file does it switch back to the file user ID, |
| like this: |
| |
| /* Record the score. */ |
| |
| int |
| record_score (int score) |
| { |
| FILE *stream; |
| char *myname; |
| |
| /* Open the scores file. */ |
| do_setuid (); |
| stream = fopen (SCORES_FILE, "a"); |
| undo_setuid (); |
| |
| /* Write the score to the file. */ |
| if (stream) |
| { |
| myname = cuserid (NULL); |
| if (score < 0) |
| fprintf (stream, "%10s: Couldn't lift the caber.\n", myname); |
| else |
| fprintf (stream, "%10s: %d feet.\n", myname, score); |
| fclose (stream); |
| return 0; |
| } |
| else |
| return -1; |
| } |
| |
| |
| File: libc.info, Node: Tips for Setuid, Next: Who Logged In, Prev: Setuid Program Example, Up: Users and Groups |
| |
| 30.10 Tips for Writing Setuid Programs |
| ====================================== |
| |
| It is easy for setuid programs to give the user access that isn't |
| intended--in fact, if you want to avoid this, you need to be careful. |
| Here are some guidelines for preventing unintended access and |
| minimizing its consequences when it does occur: |
| |
| * Don't have `setuid' programs with privileged user IDs such as |
| `root' unless it is absolutely necessary. If the resource is |
| specific to your particular program, it's better to define a new, |
| nonprivileged user ID or group ID just to manage that resource. |
| It's better if you can write your program to use a special group |
| than a special user. |
| |
| * Be cautious about using the `exec' functions in combination with |
| changing the effective user ID. Don't let users of your program |
| execute arbitrary programs under a changed user ID. Executing a |
| shell is especially bad news. Less obviously, the `execlp' and |
| `execvp' functions are a potential risk (since the program they |
| execute depends on the user's `PATH' environment variable). |
| |
| If you must `exec' another program under a changed ID, specify an |
| absolute file name (*note File Name Resolution::) for the |
| executable, and make sure that the protections on that executable |
| and _all_ containing directories are such that ordinary users |
| cannot replace it with some other program. |
| |
| You should also check the arguments passed to the program to make |
| sure they do not have unexpected effects. Likewise, you should |
| examine the environment variables. Decide which arguments and |
| variables are safe, and reject all others. |
| |
| You should never use `system' in a privileged program, because it |
| invokes a shell. |
| |
| * Only use the user ID controlling the resource in the part of the |
| program that actually uses that resource. When you're finished |
| with it, restore the effective user ID back to the actual user's |
| user ID. *Note Enable/Disable Setuid::. |
| |
| * If the `setuid' part of your program needs to access other files |
| besides the controlled resource, it should verify that the real |
| user would ordinarily have permission to access those files. You |
| can use the `access' function (*note Access Permission::) to check |
| this; it uses the real user and group IDs, rather than the |
| effective IDs. |
| |
| |
| File: libc.info, Node: Who Logged In, Next: User Accounting Database, Prev: Tips for Setuid, Up: Users and Groups |
| |
| 30.11 Identifying Who Logged In |
| =============================== |
| |
| You can use the functions listed in this section to determine the login |
| name of the user who is running a process, and the name of the user who |
| logged in the current session. See also the function `getuid' and |
| friends (*note Reading Persona::). How this information is collected by |
| the system and how to control/add/remove information from the background |
| storage is described in *note User Accounting Database::. |
| |
| The `getlogin' function is declared in `unistd.h', while `cuserid' |
| and `L_cuserid' are declared in `stdio.h'. |
| |
| -- Function: char * getlogin (void) |
| Preliminary: | MT-Unsafe race:getlogin race:utent sig:ALRM timer |
| locale | AS-Unsafe dlopen plugin heap lock | AC-Unsafe corrupt |
| lock fd mem | *Note POSIX Safety Concepts::. |
| |
| The `getlogin' function returns a pointer to a string containing |
| the name of the user logged in on the controlling terminal of the |
| process, or a null pointer if this information cannot be |
| determined. The string is statically allocated and might be |
| overwritten on subsequent calls to this function or to `cuserid'. |
| |
| -- Function: char * cuserid (char *STRING) |
| Preliminary: | MT-Unsafe race:cuserid/!string locale | AS-Unsafe |
| dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note |
| POSIX Safety Concepts::. |
| |
| The `cuserid' function returns a pointer to a string containing a |
| user name associated with the effective ID of the process. If |
| STRING is not a null pointer, it should be an array that can hold |
| at least `L_cuserid' characters; the string is returned in this |
| array. Otherwise, a pointer to a string in a static area is |
| returned. This string is statically allocated and might be |
| overwritten on subsequent calls to this function or to `getlogin'. |
| |
| The use of this function is deprecated since it is marked to be |
| withdrawn in XPG4.2 and has already been removed from newer |
| revisions of POSIX.1. |
| |
| -- Macro: int L_cuserid |
| An integer constant that indicates how long an array you might |
| need to store a user name. |
| |
| These functions let your program identify positively the user who is |
| running or the user who logged in this session. (These can differ when |
| setuid programs are involved; see *note Process Persona::.) The user |
| cannot do anything to fool these functions. |
| |
| For most purposes, it is more useful to use the environment variable |
| `LOGNAME' to find out who the user is. This is more flexible precisely |
| because the user can set `LOGNAME' arbitrarily. *Note Standard |
| Environment::. |
| |
| |
| File: libc.info, Node: User Accounting Database, Next: User Database, Prev: Who Logged In, Up: Users and Groups |
| |
| 30.12 The User Accounting Database |
| ================================== |
| |
| Most Unix-like operating systems keep track of logged in users by |
| maintaining a user accounting database. This user accounting database |
| stores for each terminal, who has logged on, at what time, the process |
| ID of the user's login shell, etc., etc., but also stores information |
| about the run level of the system, the time of the last system reboot, |
| and possibly more. |
| |
| The user accounting database typically lives in `/etc/utmp', |
| `/var/adm/utmp' or `/var/run/utmp'. However, these files should |
| *never* be accessed directly. For reading information from and writing |
| information to the user accounting database, the functions described in |
| this section should be used. |
| |
| * Menu: |
| |
| * Manipulating the Database:: Scanning and modifying the user |
| accounting database. |
| * XPG Functions:: A standardized way for doing the same thing. |
| * Logging In and Out:: Functions from BSD that modify the user |
| accounting database. |
| |
| |
| File: libc.info, Node: Manipulating the Database, Next: XPG Functions, Up: User Accounting Database |
| |
| 30.12.1 Manipulating the User Accounting Database |
| ------------------------------------------------- |
| |
| These functions and the corresponding data structures are declared in |
| the header file `utmp.h'. |
| |
| -- Data Type: struct exit_status |
| The `exit_status' data structure is used to hold information about |
| the exit status of processes marked as `DEAD_PROCESS' in the user |
| accounting database. |
| |
| `short int e_termination' |
| The exit status of the process. |
| |
| `short int e_exit' |
| The exit status of the process. |
| |
| -- Data Type: struct utmp |
| The `utmp' data structure is used to hold information about entries |
| in the user accounting database. On GNU systems it has the |
| following members: |
| |
| `short int ut_type' |
| Specifies the type of login; one of `EMPTY', `RUN_LVL', |
| `BOOT_TIME', `OLD_TIME', `NEW_TIME', `INIT_PROCESS', |
| `LOGIN_PROCESS', `USER_PROCESS', `DEAD_PROCESS' or |
| `ACCOUNTING'. |
| |
| `pid_t ut_pid' |
| The process ID number of the login process. |
| |
| `char ut_line[]' |
| The device name of the tty (without `/dev/'). |
| |
| `char ut_id[]' |
| The inittab ID of the process. |
| |
| `char ut_user[]' |
| The user's login name. |
| |
| `char ut_host[]' |
| The name of the host from which the user logged in. |
| |
| `struct exit_status ut_exit' |
| The exit status of a process marked as `DEAD_PROCESS'. |
| |
| `long ut_session' |
| The Session ID, used for windowing. |
| |
| `struct timeval ut_tv' |
| Time the entry was made. For entries of type `OLD_TIME' this |
| is the time when the system clock changed, and for entries of |
| type `NEW_TIME' this is the time the system clock was set to. |
| |
| `int32_t ut_addr_v6[4]' |
| The Internet address of a remote host. |
| |
| The `ut_type', `ut_pid', `ut_id', `ut_tv', and `ut_host' fields are |
| not available on all systems. Portable applications therefore should |
| be prepared for these situations. To help do this the `utmp.h' header |
| provides macros `_HAVE_UT_TYPE', `_HAVE_UT_PID', `_HAVE_UT_ID', |
| `_HAVE_UT_TV', and `_HAVE_UT_HOST' if the respective field is |
| available. The programmer can handle the situations by using `#ifdef' |
| in the program code. |
| |
| The following macros are defined for use as values for the `ut_type' |
| member of the `utmp' structure. The values are integer constants. |
| |
| `EMPTY' |
| This macro is used to indicate that the entry contains no valid |
| user accounting information. |
| |
| `RUN_LVL' |
| This macro is used to identify the system's runlevel. |
| |
| `BOOT_TIME' |
| This macro is used to identify the time of system boot. |
| |
| `OLD_TIME' |
| This macro is used to identify the time when the system clock |
| changed. |
| |
| `NEW_TIME' |
| This macro is used to identify the time after the system clock |
| changed. |
| |
| `INIT_PROCESS' |
| This macro is used to identify a process spawned by the init |
| process. |
| |
| `LOGIN_PROCESS' |
| This macro is used to identify the session leader of a logged in |
| user. |
| |
| `USER_PROCESS' |
| This macro is used to identify a user process. |
| |
| `DEAD_PROCESS' |
| This macro is used to identify a terminated process. |
| |
| `ACCOUNTING' |
| ??? |
| |
| The size of the `ut_line', `ut_id', `ut_user' and `ut_host' arrays |
| can be found using the `sizeof' operator. |
| |
| Many older systems have, instead of an `ut_tv' member, an `ut_time' |
| member, usually of type `time_t', for representing the time associated |
| with the entry. Therefore, for backwards compatibility only, `utmp.h' |
| defines `ut_time' as an alias for `ut_tv.tv_sec'. |
| |
| -- Function: void setutent (void) |
| Preliminary: | MT-Unsafe race:utent | AS-Unsafe lock | AC-Unsafe |
| lock fd | *Note POSIX Safety Concepts::. |
| |
| This function opens the user accounting database to begin scanning |
| it. You can then call `getutent', `getutid' or `getutline' to |
| read entries and `pututline' to write entries. |
| |
| If the database is already open, it resets the input to the |
| beginning of the database. |
| |
| -- Function: struct utmp * getutent (void) |
| Preliminary: | MT-Unsafe init race:utent race:utentbuf sig:ALRM |
| timer | AS-Unsafe heap lock | AC-Unsafe lock fd mem | *Note POSIX |
| Safety Concepts::. |
| |
| The `getutent' function reads the next entry from the user |
| accounting database. It returns a pointer to the entry, which is |
| statically allocated and may be overwritten by subsequent calls to |
| `getutent'. You must copy the contents of the structure if you |
| wish to save the information or you can use the `getutent_r' |
| function which stores the data in a user-provided buffer. |
| |
| A null pointer is returned in case no further entry is available. |
| |
| -- Function: void endutent (void) |
| Preliminary: | MT-Unsafe race:utent | AS-Unsafe lock | AC-Unsafe |
| lock fd | *Note POSIX Safety Concepts::. |
| |
| This function closes the user accounting database. |
| |
| -- Function: struct utmp * getutid (const struct utmp *ID) |
| Preliminary: | MT-Unsafe init race:utent sig:ALRM timer | |
| AS-Unsafe lock heap | AC-Unsafe lock mem fd | *Note POSIX Safety |
| Concepts::. |
| |
| This function searches forward from the current point in the |
| database for an entry that matches ID. If the `ut_type' member of |
| the ID structure is one of `RUN_LVL', `BOOT_TIME', `OLD_TIME' or |
| `NEW_TIME' the entries match if the `ut_type' members are |
| identical. If the `ut_type' member of the ID structure is |
| `INIT_PROCESS', `LOGIN_PROCESS', `USER_PROCESS' or `DEAD_PROCESS', |
| the entries match if the `ut_type' member of the entry read from |
| the database is one of these four, and the `ut_id' members match. |
| However if the `ut_id' member of either the ID structure or the |
| entry read from the database is empty it checks if the `ut_line' |
| members match instead. If a matching entry is found, `getutid' |
| returns a pointer to the entry, which is statically allocated, and |
| may be overwritten by a subsequent call to `getutent', `getutid' |
| or `getutline'. You must copy the contents of the structure if |
| you wish to save the information. |
| |
| A null pointer is returned in case the end of the database is |
| reached without a match. |
| |
| The `getutid' function may cache the last read entry. Therefore, |
| if you are using `getutid' to search for multiple occurrences, it |
| is necessary to zero out the static data after each call. |
| Otherwise `getutid' could just return a pointer to the same entry |
| over and over again. |
| |
| -- Function: struct utmp * getutline (const struct utmp *LINE) |
| Preliminary: | MT-Unsafe init race:utent sig:ALRM timer | |
| AS-Unsafe heap lock | AC-Unsafe lock fd mem | *Note POSIX Safety |
| Concepts::. |
| |
| This function searches forward from the current point in the |
| database until it finds an entry whose `ut_type' value is |
| `LOGIN_PROCESS' or `USER_PROCESS', and whose `ut_line' member |
| matches the `ut_line' member of the LINE structure. If it finds |
| such an entry, it returns a pointer to the entry which is |
| statically allocated, and may be overwritten by a subsequent call |
| to `getutent', `getutid' or `getutline'. You must copy the |
| contents of the structure if you wish to save the information. |
| |
| A null pointer is returned in case the end of the database is |
| reached without a match. |
| |
| The `getutline' function may cache the last read entry. Therefore |
| if you are using `getutline' to search for multiple occurrences, it |
| is necessary to zero out the static data after each call. |
| Otherwise `getutline' could just return a pointer to the same |
| entry over and over again. |
| |
| -- Function: struct utmp * pututline (const struct utmp *UTMP) |
| Preliminary: | MT-Unsafe race:utent sig:ALRM timer | AS-Unsafe lock |
| | AC-Unsafe lock fd | *Note POSIX Safety Concepts::. |
| |
| The `pututline' function inserts the entry `*UTMP' at the |
| appropriate place in the user accounting database. If it finds |
| that it is not already at the correct place in the database, it |
| uses `getutid' to search for the position to insert the entry, |
| however this will not modify the static structure returned by |
| `getutent', `getutid' and `getutline'. If this search fails, the |
| entry is appended to the database. |
| |
| The `pututline' function returns a pointer to a copy of the entry |
| inserted in the user accounting database, or a null pointer if the |
| entry could not be added. The following `errno' error conditions |
| are defined for this function: |
| |
| `EPERM' |
| The process does not have the appropriate privileges; you |
| cannot modify the user accounting database. |
| |
| All the `get*' functions mentioned before store the information they |
| return in a static buffer. This can be a problem in multi-threaded |
| programs since the data returned for the request is overwritten by the |
| return value data in another thread. Therefore the GNU C Library |
| provides as extensions three more functions which return the data in a |
| user-provided buffer. |
| |
| -- Function: int getutent_r (struct utmp *BUFFER, struct utmp **RESULT) |
| Preliminary: | MT-Unsafe race:utent sig:ALRM timer | AS-Unsafe lock |
| | AC-Unsafe lock fd | *Note POSIX Safety Concepts::. |
| |
| The `getutent_r' is equivalent to the `getutent' function. It |
| returns the next entry from the database. But instead of storing |
| the information in a static buffer it stores it in the buffer |
| pointed to by the parameter BUFFER. |
| |
| If the call was successful, the function returns `0' and the |
| pointer variable pointed to by the parameter RESULT contains a |
| pointer to the buffer which contains the result (this is most |
| probably the same value as BUFFER). If something went wrong |
| during the execution of `getutent_r' the function returns `-1'. |
| |
| This function is a GNU extension. |
| |
| -- Function: int getutid_r (const struct utmp *ID, struct utmp |
| *BUFFER, struct utmp **RESULT) |
| Preliminary: | MT-Unsafe race:utent sig:ALRM timer | AS-Unsafe lock |
| | AC-Unsafe lock fd | *Note POSIX Safety Concepts::. |
| |
| This function retrieves just like `getutid' the next entry matching |
| the information stored in ID. But the result is stored in the |
| buffer pointed to by the parameter BUFFER. |
| |
| If successful the function returns `0' and the pointer variable |
| pointed to by the parameter RESULT contains a pointer to the |
| buffer with the result (probably the same as RESULT. If not |
| successful the function return `-1'. |
| |
| This function is a GNU extension. |
| |
| -- Function: int getutline_r (const struct utmp *LINE, struct utmp |
| *BUFFER, struct utmp **RESULT) |
| Preliminary: | MT-Unsafe race:utent sig:ALRM timer | AS-Unsafe lock |
| | AC-Unsafe lock fd | *Note POSIX Safety Concepts::. |
| |
| This function retrieves just like `getutline' the next entry |
| matching the information stored in LINE. But the result is stored |
| in the buffer pointed to by the parameter BUFFER. |
| |
| If successful the function returns `0' and the pointer variable |
| pointed to by the parameter RESULT contains a pointer to the |
| buffer with the result (probably the same as RESULT. If not |
| successful the function return `-1'. |
| |
| This function is a GNU extension. |
| |
| In addition to the user accounting database, most systems keep a |
| number of similar databases. For example most systems keep a log file |
| with all previous logins (usually in `/etc/wtmp' or `/var/log/wtmp'). |
| |
| For specifying which database to examine, the following function |
| should be used. |
| |
| -- Function: int utmpname (const char *FILE) |
| Preliminary: | MT-Unsafe race:utent | AS-Unsafe lock heap | |
| AC-Unsafe lock mem | *Note POSIX Safety Concepts::. |
| |
| The `utmpname' function changes the name of the database to be |
| examined to FILE, and closes any previously opened database. By |
| default `getutent', `getutid', `getutline' and `pututline' read |
| from and write to the user accounting database. |
| |
| The following macros are defined for use as the FILE argument: |
| |
| -- Macro: char * _PATH_UTMP |
| This macro is used to specify the user accounting database. |
| |
| -- Macro: char * _PATH_WTMP |
| This macro is used to specify the user accounting log file. |
| |
| The `utmpname' function returns a value of `0' if the new name was |
| successfully stored, and a value of `-1' to indicate an error. |
| Note that `utmpname' does not try to open the database, and that |
| therefore the return value does not say anything about whether the |
| database can be successfully opened. |
| |
| Specially for maintaining log-like databases the GNU C Library |
| provides the following function: |
| |
| -- Function: void updwtmp (const char *WTMP_FILE, const struct utmp |
| *UTMP) |
| Preliminary: | MT-Unsafe sig:ALRM timer | AS-Unsafe | AC-Unsafe fd |
| | *Note POSIX Safety Concepts::. |
| |
| The `updwtmp' function appends the entry *UTMP to the database |
| specified by WTMP_FILE. For possible values for the WTMP_FILE |
| argument see the `utmpname' function. |
| |
| *Portability Note:* Although many operating systems provide a subset |
| of these functions, they are not standardized. There are often subtle |
| differences in the return types, and there are considerable differences |
| between the various definitions of `struct utmp'. When programming for |
| the GNU C Library, it is probably best to stick with the functions |
| described in this section. If however, you want your program to be |
| portable, consider using the XPG functions described in *note XPG |
| Functions::, or take a look at the BSD compatible functions in *note |
| Logging In and Out::. |
| |
| |
| File: libc.info, Node: XPG Functions, Next: Logging In and Out, Prev: Manipulating the Database, Up: User Accounting Database |
| |
| 30.12.2 XPG User Accounting Database Functions |
| ---------------------------------------------- |
| |
| These functions, described in the X/Open Portability Guide, are declared |
| in the header file `utmpx.h'. |
| |
| -- Data Type: struct utmpx |
| The `utmpx' data structure contains at least the following members: |
| |
| `short int ut_type' |
| Specifies the type of login; one of `EMPTY', `RUN_LVL', |
| `BOOT_TIME', `OLD_TIME', `NEW_TIME', `INIT_PROCESS', |
| `LOGIN_PROCESS', `USER_PROCESS' or `DEAD_PROCESS'. |
| |
| `pid_t ut_pid' |
| The process ID number of the login process. |
| |
| `char ut_line[]' |
| The device name of the tty (without `/dev/'). |
| |
| `char ut_id[]' |
| The inittab ID of the process. |
| |
| `char ut_user[]' |
| The user's login name. |
| |
| `struct timeval ut_tv' |
| Time the entry was made. For entries of type `OLD_TIME' this |
| is the time when the system clock changed, and for entries of |
| type `NEW_TIME' this is the time the system clock was set to. |
| In the GNU C Library, `struct utmpx' is identical to `struct utmp' |
| except for the fact that including `utmpx.h' does not make visible |
| the declaration of `struct exit_status'. |
| |
| The following macros are defined for use as values for the `ut_type' |
| member of the `utmpx' structure. The values are integer constants and |
| are, in the GNU C Library, identical to the definitions in `utmp.h'. |
| |
| `EMPTY' |
| This macro is used to indicate that the entry contains no valid |
| user accounting information. |
| |
| `RUN_LVL' |
| This macro is used to identify the system's runlevel. |
| |
| `BOOT_TIME' |
| This macro is used to identify the time of system boot. |
| |
| `OLD_TIME' |
| This macro is used to identify the time when the system clock |
| changed. |
| |
| `NEW_TIME' |
| This macro is used to identify the time after the system clock |
| changed. |
| |
| `INIT_PROCESS' |
| This macro is used to identify a process spawned by the init |
| process. |
| |
| `LOGIN_PROCESS' |
| This macro is used to identify the session leader of a logged in |
| user. |
| |
| `USER_PROCESS' |
| This macro is used to identify a user process. |
| |
| `DEAD_PROCESS' |
| This macro is used to identify a terminated process. |
| |
| The size of the `ut_line', `ut_id' and `ut_user' arrays can be found |
| using the `sizeof' operator. |
| |
| -- Function: void setutxent (void) |
| Preliminary: | MT-Unsafe race:utent | AS-Unsafe lock | AC-Unsafe |
| lock fd | *Note POSIX Safety Concepts::. |
| |
| This function is similar to `setutent'. In the GNU C Library it is |
| simply an alias for `setutent'. |
| |
| -- Function: struct utmpx * getutxent (void) |
| Preliminary: | MT-Unsafe init race:utent sig:ALRM timer | |
| AS-Unsafe heap lock | AC-Unsafe lock fd mem | *Note POSIX Safety |
| Concepts::. |
| |
| The `getutxent' function is similar to `getutent', but returns a |
| pointer to a `struct utmpx' instead of `struct utmp'. In the GNU |
| C Library it simply is an alias for `getutent'. |
| |
| -- Function: void endutxent (void) |
| Preliminary: | MT-Unsafe race:utent | AS-Unsafe lock | AC-Unsafe |
| lock | *Note POSIX Safety Concepts::. |
| |
| This function is similar to `endutent'. In the GNU C Library it is |
| simply an alias for `endutent'. |
| |
| -- Function: struct utmpx * getutxid (const struct utmpx *ID) |
| Preliminary: | MT-Unsafe init race:utent sig:ALRM timer | |
| AS-Unsafe lock heap | AC-Unsafe lock mem fd | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to `getutid', but uses `struct utmpx' |
| instead of `struct utmp'. In the GNU C Library it is simply an |
| alias for `getutid'. |
| |
| -- Function: struct utmpx * getutxline (const struct utmpx *LINE) |
| Preliminary: | MT-Unsafe init race:utent sig:ALRM timer | |
| AS-Unsafe heap lock | AC-Unsafe lock fd mem | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to `getutid', but uses `struct utmpx' |
| instead of `struct utmp'. In the GNU C Library it is simply an |
| alias for `getutline'. |
| |
| -- Function: struct utmpx * pututxline (const struct utmpx *UTMP) |
| Preliminary: | MT-Unsafe race:utent sig:ALRM timer | AS-Unsafe lock |
| | AC-Unsafe lock fd | *Note POSIX Safety Concepts::. |
| |
| The `pututxline' function is functionally identical to |
| `pututline', but uses `struct utmpx' instead of `struct utmp'. In |
| the GNU C Library, `pututxline' is simply an alias for `pututline'. |
| |
| -- Function: int utmpxname (const char *FILE) |
| Preliminary: | MT-Unsafe race:utent | AS-Unsafe lock heap | |
| AC-Unsafe lock mem | *Note POSIX Safety Concepts::. |
| |
| The `utmpxname' function is functionally identical to `utmpname'. |
| In the GNU C Library, `utmpxname' is simply an alias for |
| `utmpname'. |
| |
| You can translate between a traditional `struct utmp' and an XPG |
| `struct utmpx' with the following functions. In the GNU C Library, |
| these functions are merely copies, since the two structures are |
| identical. |
| |
| -- Function: int getutmp (const struct utmpx *UTMPX, struct utmp *UTMP) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `getutmp' copies the information, insofar as the structures are |
| compatible, from UTMPX to UTMP. |
| |
| -- Function: int getutmpx (const struct utmp *UTMP, struct utmpx |
| *UTMPX) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `getutmpx' copies the information, insofar as the structures are |
| compatible, from UTMP to UTMPX. |
| |
| |
| File: libc.info, Node: Logging In and Out, Prev: XPG Functions, Up: User Accounting Database |
| |
| 30.12.3 Logging In and Out |
| -------------------------- |
| |
| These functions, derived from BSD, are available in the separate |
| `libutil' library, and declared in `utmp.h'. |
| |
| Note that the `ut_user' member of `struct utmp' is called `ut_name' |
| in BSD. Therefore, `ut_name' is defined as an alias for `ut_user' in |
| `utmp.h'. |
| |
| -- Function: int login_tty (int FILEDES) |
| Preliminary: | MT-Unsafe race:ttyname | AS-Unsafe heap lock | |
| AC-Unsafe lock fd mem | *Note POSIX Safety Concepts::. |
| |
| This function makes FILEDES the controlling terminal of the |
| current process, redirects standard input, standard output and |
| standard error output to this terminal, and closes FILEDES. |
| |
| This function returns `0' on successful completion, and `-1' on |
| error. |
| |
| -- Function: void login (const struct utmp *ENTRY) |
| Preliminary: | MT-Unsafe race:utent sig:ALRM timer | AS-Unsafe |
| lock heap | AC-Unsafe lock corrupt fd mem | *Note POSIX Safety |
| Concepts::. |
| |
| The `login' functions inserts an entry into the user accounting |
| database. The `ut_line' member is set to the name of the terminal |
| on standard input. If standard input is not a terminal `login' |
| uses standard output or standard error output to determine the |
| name of the terminal. If `struct utmp' has a `ut_type' member, |
| `login' sets it to `USER_PROCESS', and if there is an `ut_pid' |
| member, it will be set to the process ID of the current process. |
| The remaining entries are copied from ENTRY. |
| |
| A copy of the entry is written to the user accounting log file. |
| |
| -- Function: int logout (const char *UT_LINE) |
| Preliminary: | MT-Unsafe race:utent sig:ALRM timer | AS-Unsafe |
| lock heap | AC-Unsafe lock fd mem | *Note POSIX Safety Concepts::. |
| |
| This function modifies the user accounting database to indicate |
| that the user on UT_LINE has logged out. |
| |
| The `logout' function returns `1' if the entry was successfully |
| written to the database, or `0' on error. |
| |
| -- Function: void logwtmp (const char *UT_LINE, const char *UT_NAME, |
| const char *UT_HOST) |
| Preliminary: | MT-Unsafe sig:ALRM timer | AS-Unsafe | AC-Unsafe fd |
| | *Note POSIX Safety Concepts::. |
| |
| The `logwtmp' function appends an entry to the user accounting log |
| file, for the current time and the information provided in the |
| UT_LINE, UT_NAME and UT_HOST arguments. |
| |
| *Portability Note:* The BSD `struct utmp' only has the `ut_line', |
| `ut_name', `ut_host' and `ut_time' members. Older systems do not even |
| have the `ut_host' member. |
| |
| |
| File: libc.info, Node: User Database, Next: Group Database, Prev: User Accounting Database, Up: Users and Groups |
| |
| 30.13 User Database |
| =================== |
| |
| This section describes how to search and scan the database of registered |
| users. The database itself is kept in the file `/etc/passwd' on most |
| systems, but on some systems a special network server gives access to |
| it. |
| |
| Historically, this database included one-way hashes of user |
| passphrases (*note Passphrase Storage::) as well as public information |
| about each user (such as their user ID and full name). Many of the |
| functions and data structures associated with this database, and the |
| filename `/etc/passwd' itself, reflect this history. However, the |
| information in this database is available to all users, and it is no |
| longer considered safe to make passphrase hashes available to all |
| users, so they have been moved to a "shadow" database that can only be |
| accessed with special privileges. |
| |
| * Menu: |
| |
| * User Data Structure:: What each user record contains. |
| * Lookup User:: How to look for a particular user. |
| * Scanning All Users:: Scanning the list of all users, one by one. |
| * Writing a User Entry:: How a program can rewrite a user's record. |
| |
| |
| File: libc.info, Node: User Data Structure, Next: Lookup User, Up: User Database |
| |
| 30.13.1 The Data Structure that Describes a User |
| ------------------------------------------------ |
| |
| The functions and data structures for accessing the system user database |
| are declared in the header file `pwd.h'. |
| |
| -- Data Type: struct passwd |
| The `passwd' data structure is used to hold information about |
| entries in the system user data base. It has at least the |
| following members: |
| |
| `char *pw_name' |
| The user's login name. |
| |
| `char *pw_passwd' |
| Historically, this field would hold the one-way hash of the |
| user's passphrase. Nowadays, it will almost always be the |
| single character `x', indicating that the hash is in the |
| shadow database. |
| |
| `uid_t pw_uid' |
| The user ID number. |
| |
| `gid_t pw_gid' |
| The user's default group ID number. |
| |
| `char *pw_gecos' |
| A string typically containing the user's real name, and |
| possibly other information such as a phone number. |
| |
| `char *pw_dir' |
| The user's home directory, or initial working directory. |
| This might be a null pointer, in which case the |
| interpretation is system-dependent. |
| |
| `char *pw_shell' |
| The user's default shell, or the initial program run when the |
| user logs in. This might be a null pointer, indicating that |
| the system default should be used. |
| |
| |
| File: libc.info, Node: Lookup User, Next: Scanning All Users, Prev: User Data Structure, Up: User Database |
| |
| 30.13.2 Looking Up One User |
| --------------------------- |
| |
| You can search the system user database for information about a |
| specific user using `getpwuid' or `getpwnam'. These functions are |
| declared in `pwd.h'. |
| |
| -- Function: struct passwd * getpwuid (uid_t UID) |
| Preliminary: | MT-Unsafe race:pwuid locale | AS-Unsafe dlopen |
| plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX |
| Safety Concepts::. |
| |
| This function returns a pointer to a statically-allocated structure |
| containing information about the user whose user ID is UID. This |
| structure may be overwritten on subsequent calls to `getpwuid'. |
| |
| A null pointer value indicates there is no user in the data base |
| with user ID UID. |
| |
| -- Function: int getpwuid_r (uid_t UID, struct passwd *RESULT_BUF, |
| char *BUFFER, size_t BUFLEN, struct passwd **RESULT) |
| Preliminary: | MT-Safe locale | AS-Unsafe dlopen plugin heap lock |
| | AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::. |
| |
| This function is similar to `getpwuid' in that it returns |
| information about the user whose user ID is UID. However, it |
| fills the user supplied structure pointed to by RESULT_BUF with |
| the information instead of using a static buffer. The first |
| BUFLEN bytes of the additional buffer pointed to by BUFFER are |
| used to contain additional information, normally strings which are |
| pointed to by the elements of the result structure. |
| |
| If a user with ID UID is found, the pointer returned in RESULT |
| points to the record which contains the wanted data (i.e., RESULT |
| contains the value RESULT_BUF). If no user is found or if an |
| error occurred, the pointer returned in RESULT is a null pointer. |
| The function returns zero or an error code. If the buffer BUFFER |
| is too small to contain all the needed information, the error code |
| `ERANGE' is returned and `errno' is set to `ERANGE'. |
| |
| -- Function: struct passwd * getpwnam (const char *NAME) |
| Preliminary: | MT-Unsafe race:pwnam locale | AS-Unsafe dlopen |
| plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX |
| Safety Concepts::. |
| |
| This function returns a pointer to a statically-allocated structure |
| containing information about the user whose user name is NAME. |
| This structure may be overwritten on subsequent calls to |
| `getpwnam'. |
| |
| A null pointer return indicates there is no user named NAME. |
| |
| -- Function: int getpwnam_r (const char *NAME, struct passwd |
| *RESULT_BUF, char *BUFFER, size_t BUFLEN, struct passwd |
| **RESULT) |
| Preliminary: | MT-Safe locale | AS-Unsafe dlopen plugin heap lock |
| | AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::. |
| |
| This function is similar to `getpwnam' in that it returns |
| information about the user whose user name is NAME. However, like |
| `getpwuid_r', it fills the user supplied buffers in RESULT_BUF and |
| BUFFER with the information instead of using a static buffer. |
| |
| The return values are the same as for `getpwuid_r'. |
| |
| |
| File: libc.info, Node: Scanning All Users, Next: Writing a User Entry, Prev: Lookup User, Up: User Database |
| |
| 30.13.3 Scanning the List of All Users |
| -------------------------------------- |
| |
| This section explains how a program can read the list of all users in |
| the system, one user at a time. The functions described here are |
| declared in `pwd.h'. |
| |
| You can use the `fgetpwent' function to read user entries from a |
| particular file. |
| |
| -- Function: struct passwd * fgetpwent (FILE *STREAM) |
| Preliminary: | MT-Unsafe race:fpwent | AS-Unsafe corrupt lock | |
| AC-Unsafe corrupt lock | *Note POSIX Safety Concepts::. |
| |
| This function reads the next user entry from STREAM and returns a |
| pointer to the entry. The structure is statically allocated and is |
| rewritten on subsequent calls to `fgetpwent'. You must copy the |
| contents of the structure if you wish to save the information. |
| |
| The stream must correspond to a file in the same format as the |
| standard user database file. |
| |
| -- Function: int fgetpwent_r (FILE *STREAM, struct passwd *RESULT_BUF, |
| char *BUFFER, size_t BUFLEN, struct passwd **RESULT) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock |
| | *Note POSIX Safety Concepts::. |
| |
| This function is similar to `fgetpwent' in that it reads the next |
| user entry from STREAM. But the result is returned in the |
| structure pointed to by RESULT_BUF. The first BUFLEN bytes of the |
| additional buffer pointed to by BUFFER are used to contain |
| additional information, normally strings which are pointed to by |
| the elements of the result structure. |
| |
| The stream must correspond to a file in the same format as the |
| standard user database file. |
| |
| If the function returns zero RESULT points to the structure with |
| the wanted data (normally this is in RESULT_BUF). If errors |
| occurred the return value is nonzero and RESULT contains a null |
| pointer. |
| |
| The way to scan all the entries in the user database is with |
| `setpwent', `getpwent', and `endpwent'. |
| |
| -- Function: void setpwent (void) |
| Preliminary: | MT-Unsafe race:pwent locale | AS-Unsafe dlopen |
| plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX |
| Safety Concepts::. |
| |
| This function initializes a stream which `getpwent' and |
| `getpwent_r' use to read the user database. |
| |
| -- Function: struct passwd * getpwent (void) |
| Preliminary: | MT-Unsafe race:pwent race:pwentbuf locale | |
| AS-Unsafe dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem |
| | *Note POSIX Safety Concepts::. |
| |
| The `getpwent' function reads the next entry from the stream |
| initialized by `setpwent'. It returns a pointer to the entry. The |
| structure is statically allocated and is rewritten on subsequent |
| calls to `getpwent'. You must copy the contents of the structure |
| if you wish to save the information. |
| |
| A null pointer is returned when no more entries are available. |
| |
| -- Function: int getpwent_r (struct passwd *RESULT_BUF, char *BUFFER, |
| size_t BUFLEN, struct passwd **RESULT) |
| Preliminary: | MT-Unsafe race:pwent locale | AS-Unsafe dlopen |
| plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX |
| Safety Concepts::. |
| |
| This function is similar to `getpwent' in that it returns the next |
| entry from the stream initialized by `setpwent'. Like |
| `fgetpwent_r', it uses the user-supplied buffers in RESULT_BUF and |
| BUFFER to return the information requested. |
| |
| The return values are the same as for `fgetpwent_r'. |
| |
| |
| -- Function: void endpwent (void) |
| Preliminary: | MT-Unsafe race:pwent locale | AS-Unsafe dlopen |
| plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX |
| Safety Concepts::. |
| |
| This function closes the internal stream used by `getpwent' or |
| `getpwent_r'. |
| |
| |
| File: libc.info, Node: Writing a User Entry, Prev: Scanning All Users, Up: User Database |
| |
| 30.13.4 Writing a User Entry |
| ---------------------------- |
| |
| -- Function: int putpwent (const struct passwd *P, FILE *STREAM) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt | AC-Unsafe lock |
| corrupt | *Note POSIX Safety Concepts::. |
| |
| This function writes the user entry `*P' to the stream STREAM, in |
| the format used for the standard user database file. The return |
| value is zero on success and nonzero on failure. |
| |
| This function exists for compatibility with SVID. We recommend |
| that you avoid using it, because it makes sense only on the |
| assumption that the `struct passwd' structure has no members |
| except the standard ones; on a system which merges the traditional |
| Unix data base with other extended information about users, adding |
| an entry using this function would inevitably leave out much of |
| the important information. |
| |
| The group and user ID fields are left empty if the group or user |
| name starts with a - or +. |
| |
| The function `putpwent' is declared in `pwd.h'. |
| |
| |
| File: libc.info, Node: Group Database, Next: Database Example, Prev: User Database, Up: Users and Groups |
| |
| 30.14 Group Database |
| ==================== |
| |
| This section describes how to search and scan the database of |
| registered groups. The database itself is kept in the file |
| `/etc/group' on most systems, but on some systems a special network |
| service provides access to it. |
| |
| * Menu: |
| |
| * Group Data Structure:: What each group record contains. |
| * Lookup Group:: How to look for a particular group. |
| * Scanning All Groups:: Scanning the list of all groups. |
| |
| |
| File: libc.info, Node: Group Data Structure, Next: Lookup Group, Up: Group Database |
| |
| 30.14.1 The Data Structure for a Group |
| -------------------------------------- |
| |
| The functions and data structures for accessing the system group |
| database are declared in the header file `grp.h'. |
| |
| -- Data Type: struct group |
| The `group' structure is used to hold information about an entry in |
| the system group database. It has at least the following members: |
| |
| `char *gr_name' |
| The name of the group. |
| |
| `gid_t gr_gid' |
| The group ID of the group. |
| |
| `char **gr_mem' |
| A vector of pointers to the names of users in the group. |
| Each user name is a null-terminated string, and the vector |
| itself is terminated by a null pointer. |
| |
| |
| File: libc.info, Node: Lookup Group, Next: Scanning All Groups, Prev: Group Data Structure, Up: Group Database |
| |
| 30.14.2 Looking Up One Group |
| ---------------------------- |
| |
| You can search the group database for information about a specific |
| group using `getgrgid' or `getgrnam'. These functions are declared in |
| `grp.h'. |
| |
| -- Function: struct group * getgrgid (gid_t GID) |
| Preliminary: | MT-Unsafe race:grgid locale | AS-Unsafe dlopen |
| plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX |
| Safety Concepts::. |
| |
| This function returns a pointer to a statically-allocated structure |
| containing information about the group whose group ID is GID. |
| This structure may be overwritten by subsequent calls to |
| `getgrgid'. |
| |
| A null pointer indicates there is no group with ID GID. |
| |
| -- Function: int getgrgid_r (gid_t GID, struct group *RESULT_BUF, char |
| *BUFFER, size_t BUFLEN, struct group **RESULT) |
| Preliminary: | MT-Safe locale | AS-Unsafe dlopen plugin heap lock |
| | AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::. |
| |
| This function is similar to `getgrgid' in that it returns |
| information about the group whose group ID is GID. However, it |
| fills the user supplied structure pointed to by RESULT_BUF with |
| the information instead of using a static buffer. The first |
| BUFLEN bytes of the additional buffer pointed to by BUFFER are |
| used to contain additional information, normally strings which are |
| pointed to by the elements of the result structure. |
| |
| If a group with ID GID is found, the pointer returned in RESULT |
| points to the record which contains the wanted data (i.e., RESULT |
| contains the value RESULT_BUF). If no group is found or if an |
| error occurred, the pointer returned in RESULT is a null pointer. |
| The function returns zero or an error code. If the buffer BUFFER |
| is too small to contain all the needed information, the error code |
| `ERANGE' is returned and `errno' is set to `ERANGE'. |
| |
| -- Function: struct group * getgrnam (const char *NAME) |
| Preliminary: | MT-Unsafe race:grnam locale | AS-Unsafe dlopen |
| plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX |
| Safety Concepts::. |
| |
| This function returns a pointer to a statically-allocated structure |
| containing information about the group whose group name is NAME. |
| This structure may be overwritten by subsequent calls to |
| `getgrnam'. |
| |
| A null pointer indicates there is no group named NAME. |
| |
| -- Function: int getgrnam_r (const char *NAME, struct group |
| *RESULT_BUF, char *BUFFER, size_t BUFLEN, struct group |
| **RESULT) |
| Preliminary: | MT-Safe locale | AS-Unsafe dlopen plugin heap lock |
| | AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::. |
| |
| This function is similar to `getgrnam' in that it returns |
| information about the group whose group name is NAME. Like |
| `getgrgid_r', it uses the user supplied buffers in RESULT_BUF and |
| BUFFER, not a static buffer. |
| |
| The return values are the same as for `getgrgid_r'. |
| |
| |
| File: libc.info, Node: Scanning All Groups, Prev: Lookup Group, Up: Group Database |
| |
| 30.14.3 Scanning the List of All Groups |
| --------------------------------------- |
| |
| This section explains how a program can read the list of all groups in |
| the system, one group at a time. The functions described here are |
| declared in `grp.h'. |
| |
| You can use the `fgetgrent' function to read group entries from a |
| particular file. |
| |
| -- Function: struct group * fgetgrent (FILE *STREAM) |
| Preliminary: | MT-Unsafe race:fgrent | AS-Unsafe corrupt lock | |
| AC-Unsafe corrupt lock | *Note POSIX Safety Concepts::. |
| |
| The `fgetgrent' function reads the next entry from STREAM. It |
| returns a pointer to the entry. The structure is statically |
| allocated and is overwritten on subsequent calls to `fgetgrent'. |
| You must copy the contents of the structure if you wish to save the |
| information. |
| |
| The stream must correspond to a file in the same format as the |
| standard group database file. |
| |
| -- Function: int fgetgrent_r (FILE *STREAM, struct group *RESULT_BUF, |
| char *BUFFER, size_t BUFLEN, struct group **RESULT) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock |
| | *Note POSIX Safety Concepts::. |
| |
| This function is similar to `fgetgrent' in that it reads the next |
| user entry from STREAM. But the result is returned in the |
| structure pointed to by RESULT_BUF. The first BUFLEN bytes of the |
| additional buffer pointed to by BUFFER are used to contain |
| additional information, normally strings which are pointed to by |
| the elements of the result structure. |
| |
| This stream must correspond to a file in the same format as the |
| standard group database file. |
| |
| If the function returns zero RESULT points to the structure with |
| the wanted data (normally this is in RESULT_BUF). If errors |
| occurred the return value is non-zero and RESULT contains a null |
| pointer. |
| |
| The way to scan all the entries in the group database is with |
| `setgrent', `getgrent', and `endgrent'. |
| |
| -- Function: void setgrent (void) |
| Preliminary: | MT-Unsafe race:grent locale | AS-Unsafe dlopen |
| plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX |
| Safety Concepts::. |
| |
| This function initializes a stream for reading from the group data |
| base. You use this stream by calling `getgrent' or `getgrent_r'. |
| |
| -- Function: struct group * getgrent (void) |
| Preliminary: | MT-Unsafe race:grent race:grentbuf locale | |
| AS-Unsafe dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem |
| | *Note POSIX Safety Concepts::. |
| |
| The `getgrent' function reads the next entry from the stream |
| initialized by `setgrent'. It returns a pointer to the entry. The |
| structure is statically allocated and is overwritten on subsequent |
| calls to `getgrent'. You must copy the contents of the structure |
| if you wish to save the information. |
| |
| -- Function: int getgrent_r (struct group *RESULT_BUF, char *BUFFER, |
| size_t BUFLEN, struct group **RESULT) |
| Preliminary: | MT-Unsafe race:grent locale | AS-Unsafe dlopen |
| plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX |
| Safety Concepts::. |
| |
| This function is similar to `getgrent' in that it returns the next |
| entry from the stream initialized by `setgrent'. Like |
| `fgetgrent_r', it places the result in user-supplied buffers |
| pointed to by RESULT_BUF and BUFFER. |
| |
| If the function returns zero RESULT contains a pointer to the data |
| (normally equal to RESULT_BUF). If errors occurred the return |
| value is non-zero and RESULT contains a null pointer. |
| |
| -- Function: void endgrent (void) |
| Preliminary: | MT-Unsafe race:grent locale | AS-Unsafe dlopen |
| plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX |
| Safety Concepts::. |
| |
| This function closes the internal stream used by `getgrent' or |
| `getgrent_r'. |
| |
| |
| File: libc.info, Node: Database Example, Next: Netgroup Database, Prev: Group Database, Up: Users and Groups |
| |
| 30.15 User and Group Database Example |
| ===================================== |
| |
| Here is an example program showing the use of the system database |
| inquiry functions. The program prints some information about the user |
| running the program. |
| |
| |
| #include <grp.h> |
| #include <pwd.h> |
| #include <sys/types.h> |
| #include <unistd.h> |
| #include <stdlib.h> |
| |
| int |
| main (void) |
| { |
| uid_t me; |
| struct passwd *my_passwd; |
| struct group *my_group; |
| char **members; |
| |
| /* Get information about the user ID. */ |
| me = getuid (); |
| my_passwd = getpwuid (me); |
| if (!my_passwd) |
| { |
| printf ("Couldn't find out about user %d.\n", (int) me); |
| exit (EXIT_FAILURE); |
| } |
| |
| /* Print the information. */ |
| printf ("I am %s.\n", my_passwd->pw_gecos); |
| printf ("My login name is %s.\n", my_passwd->pw_name); |
| printf ("My uid is %d.\n", (int) (my_passwd->pw_uid)); |
| printf ("My home directory is %s.\n", my_passwd->pw_dir); |
| printf ("My default shell is %s.\n", my_passwd->pw_shell); |
| |
| /* Get information about the default group ID. */ |
| my_group = getgrgid (my_passwd->pw_gid); |
| if (!my_group) |
| { |
| printf ("Couldn't find out about group %d.\n", |
| (int) my_passwd->pw_gid); |
| exit (EXIT_FAILURE); |
| } |
| |
| /* Print the information. */ |
| printf ("My default group is %s (%d).\n", |
| my_group->gr_name, (int) (my_passwd->pw_gid)); |
| printf ("The members of this group are:\n"); |
| members = my_group->gr_mem; |
| while (*members) |
| { |
| printf (" %s\n", *(members)); |
| members++; |
| } |
| |
| return EXIT_SUCCESS; |
| } |
| |
| Here is some output from this program: |
| |
| I am Throckmorton Snurd. |
| My login name is snurd. |
| My uid is 31093. |
| My home directory is /home/fsg/snurd. |
| My default shell is /bin/sh. |
| My default group is guest (12). |
| The members of this group are: |
| friedman |
| tami |
| |
| |
| File: libc.info, Node: Netgroup Database, Prev: Database Example, Up: Users and Groups |
| |
| 30.16 Netgroup Database |
| ======================= |
| |
| * Menu: |
| |
| * Netgroup Data:: Data in the Netgroup database and where |
| it comes from. |
| * Lookup Netgroup:: How to look for a particular netgroup. |
| * Netgroup Membership:: How to test for netgroup membership. |
| |
| |
| File: libc.info, Node: Netgroup Data, Next: Lookup Netgroup, Up: Netgroup Database |
| |
| 30.16.1 Netgroup Data |
| --------------------- |
| |
| Sometimes it is useful to group users according to other criteria |
| (*note Group Database::). E.g., it is useful to associate a certain |
| group of users with a certain machine. On the other hand grouping of |
| host names is not supported so far. |
| |
| In Sun Microsystems' SunOS appeared a new kind of database, the |
| netgroup database. It allows grouping hosts, users, and domains |
| freely, giving them individual names. To be more concrete, a netgroup |
| is a list of triples consisting of a host name, a user name, and a |
| domain name where any of the entries can be a wildcard entry matching |
| all inputs. A last possibility is that names of other netgroups can |
| also be given in the list specifying a netgroup. So one can construct |
| arbitrary hierarchies without loops. |
| |
| Sun's implementation allows netgroups only for the `nis' or |
| `nisplus' service, *note Services in the NSS configuration::. The |
| implementation in the GNU C Library has no such restriction. An entry |
| in either of the input services must have the following form: |
| |
| GROUPNAME ( GROUPNAME | `('HOSTNAME`,'USERNAME`,'`domainname'`)' )+ |
| |
| Any of the fields in the triple can be empty which means anything |
| matches. While describing the functions we will see that the opposite |
| case is useful as well. I.e., there may be entries which will not |
| match any input. For entries like this, a name consisting of the single |
| character `-' shall be used. |
| |
| |
| File: libc.info, Node: Lookup Netgroup, Next: Netgroup Membership, Prev: Netgroup Data, Up: Netgroup Database |
| |
| 30.16.2 Looking up one Netgroup |
| ------------------------------- |
| |
| The lookup functions for netgroups are a bit different than all other |
| system database handling functions. Since a single netgroup can contain |
| many entries a two-step process is needed. First a single netgroup is |
| selected and then one can iterate over all entries in this netgroup. |
| These functions are declared in `netdb.h'. |
| |
| -- Function: int setnetgrent (const char *NETGROUP) |
| Preliminary: | MT-Unsafe race:netgrent locale | AS-Unsafe dlopen |
| plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX |
| Safety Concepts::. |
| |
| A call to this function initializes the internal state of the |
| library to allow following calls of `getnetgrent' to iterate over |
| all entries in the netgroup with name NETGROUP. |
| |
| When the call is successful (i.e., when a netgroup with this name |
| exists) the return value is `1'. When the return value is `0' no |
| netgroup of this name is known or some other error occurred. |
| |
| It is important to remember that there is only one single state for |
| iterating the netgroups. Even if the programmer uses the |
| `getnetgrent_r' function the result is not really reentrant since |
| always only one single netgroup at a time can be processed. If the |
| program needs to process more than one netgroup simultaneously she must |
| protect this by using external locking. This problem was introduced in |
| the original netgroups implementation in SunOS and since we must stay |
| compatible it is not possible to change this. |
| |
| Some other functions also use the netgroups state. Currently these |
| are the `innetgr' function and parts of the implementation of the |
| `compat' service part of the NSS implementation. |
| |
| -- Function: int getnetgrent (char **HOSTP, char **USERP, char |
| **DOMAINP) |
| Preliminary: | MT-Unsafe race:netgrent race:netgrentbuf locale | |
| AS-Unsafe dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem |
| | *Note POSIX Safety Concepts::. |
| |
| This function returns the next unprocessed entry of the currently |
| selected netgroup. The string pointers, in which addresses are |
| passed in the arguments HOSTP, USERP, and DOMAINP, will contain |
| after a successful call pointers to appropriate strings. If the |
| string in the next entry is empty the pointer has the value `NULL'. |
| The returned string pointers are only valid if none of the netgroup |
| related functions are called. |
| |
| The return value is `1' if the next entry was successfully read. A |
| value of `0' means no further entries exist or internal errors |
| occurred. |
| |
| -- Function: int getnetgrent_r (char **HOSTP, char **USERP, char |
| **DOMAINP, char *BUFFER, size_t BUFLEN) |
| Preliminary: | MT-Unsafe race:netgrent locale | AS-Unsafe dlopen |
| plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX |
| Safety Concepts::. |
| |
| This function is similar to `getnetgrent' with only one exception: |
| the strings the three string pointers HOSTP, USERP, and DOMAINP |
| point to, are placed in the buffer of BUFLEN bytes starting at |
| BUFFER. This means the returned values are valid even after other |
| netgroup related functions are called. |
| |
| The return value is `1' if the next entry was successfully read and |
| the buffer contains enough room to place the strings in it. `0' is |
| returned in case no more entries are found, the buffer is too |
| small, or internal errors occurred. |
| |
| This function is a GNU extension. The original implementation in |
| the SunOS libc does not provide this function. |
| |
| -- Function: void endnetgrent (void) |
| Preliminary: | MT-Unsafe race:netgrent | AS-Unsafe dlopen plugin |
| heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX Safety |
| Concepts::. |
| |
| This function frees all buffers which were allocated to process |
| the last selected netgroup. As a result all string pointers |
| returned by calls to `getnetgrent' are invalid afterwards. |
| |
| |
| File: libc.info, Node: Netgroup Membership, Prev: Lookup Netgroup, Up: Netgroup Database |
| |
| 30.16.3 Testing for Netgroup Membership |
| --------------------------------------- |
| |
| It is often not necessary to scan the whole netgroup since often the |
| only interesting question is whether a given entry is part of the |
| selected netgroup. |
| |
| -- Function: int innetgr (const char *NETGROUP, const char *HOST, |
| const char *USER, const char *DOMAIN) |
| Preliminary: | MT-Unsafe race:netgrent locale | AS-Unsafe dlopen |
| plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX |
| Safety Concepts::. |
| |
| This function tests whether the triple specified by the parameters |
| HOST, USER, and DOMAIN is part of the netgroup NETGROUP. Using |
| this function has the advantage that |
| |
| 1. no other netgroup function can use the global netgroup state |
| since internal locking is used and |
| |
| 2. the function is implemented more efficiently than successive |
| calls to the other `set'/`get'/`endnetgrent' functions. |
| |
| Any of the pointers HOST, USER, or DOMAIN can be `NULL' which |
| means any value is accepted in this position. This is also true |
| for the name `-' which should not match any other string otherwise. |
| |
| The return value is `1' if an entry matching the given triple is |
| found in the netgroup. The return value is `0' if the netgroup |
| itself is not found, the netgroup does not contain the triple or |
| internal errors occurred. |
| |
| |
| File: libc.info, Node: System Management, Next: System Configuration, Prev: Users and Groups, Up: Top |
| |
| 31 System Management |
| ******************** |
| |
| This chapter describes facilities for controlling the system that |
| underlies a process (including the operating system and hardware) and |
| for getting information about it. Anyone can generally use the |
| informational facilities, but usually only a properly privileged process |
| can make changes. |
| |
| * Menu: |
| |
| * Host Identification:: Determining the name of the machine. |
| * Platform Type:: Determining operating system and basic |
| machine type |
| * Filesystem Handling:: Controlling/querying mounts |
| * System Parameters:: Getting and setting various system parameters |
| |
| To get information on parameters of the system that are built into |
| the system, such as the maximum length of a filename, *note System |
| Configuration::. |
| |
| |
| File: libc.info, Node: Host Identification, Next: Platform Type, Up: System Management |
| |
| 31.1 Host Identification |
| ======================== |
| |
| This section explains how to identify the particular system on which |
| your program is running. First, let's review the various ways computer |
| systems are named, which is a little complicated because of the history |
| of the development of the Internet. |
| |
| Every Unix system (also known as a host) has a host name, whether |
| it's connected to a network or not. In its simplest form, as used |
| before computer networks were an issue, it's just a word like `chicken'. |
| |
| But any system attached to the Internet or any network like it |
| conforms to a more rigorous naming convention as part of the Domain |
| Name System (DNS). In the DNS, every host name is composed of two |
| parts: |
| |
| 1. hostname |
| |
| 2. domain name |
| |
| You will note that "hostname" looks a lot like "host name", but is |
| not the same thing, and that people often incorrectly refer to entire |
| host names as "domain names." |
| |
| In the DNS, the full host name is properly called the FQDN (Fully |
| Qualified Domain Name) and consists of the hostname, then a period, |
| then the domain name. The domain name itself usually has multiple |
| components separated by periods. So for example, a system's hostname |
| may be `chicken' and its domain name might be `ai.mit.edu', so its FQDN |
| (which is its host name) is `chicken.ai.mit.edu'. |
| |
| Adding to the confusion, though, is that the DNS is not the only |
| name space in which a computer needs to be known. Another name space |
| is the NIS (aka YP) name space. For NIS purposes, there is another |
| domain name, which is called the NIS domain name or the YP domain name. |
| It need not have anything to do with the DNS domain name. |
| |
| Confusing things even more is the fact that in the DNS, it is |
| possible for multiple FQDNs to refer to the same system. However, |
| there is always exactly one of them that is the true host name, and it |
| is called the canonical FQDN. |
| |
| In some contexts, the host name is called a "node name." |
| |
| For more information on DNS host naming, see *note Host Names::. |
| |
| Prototypes for these functions appear in `unistd.h'. |
| |
| The programs `hostname', `hostid', and `domainname' work by calling |
| these functions. |
| |
| -- Function: int gethostname (char *NAME, size_t SIZE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function returns the host name of the system on which it is |
| called, in the array NAME. The SIZE argument specifies the size of |
| this array, in bytes. Note that this is _not_ the DNS hostname. |
| If the system participates in the DNS, this is the FQDN (see |
| above). |
| |
| The return value is `0' on success and `-1' on failure. In the |
| GNU C Library, `gethostname' fails if SIZE is not large enough; |
| then you can try again with a larger array. The following `errno' |
| error condition is defined for this function: |
| |
| `ENAMETOOLONG' |
| The SIZE argument is less than the size of the host name plus |
| one. |
| |
| On some systems, there is a symbol for the maximum possible host |
| name length: `MAXHOSTNAMELEN'. It is defined in `sys/param.h'. |
| But you can't count on this to exist, so it is cleaner to handle |
| failure and try again. |
| |
| `gethostname' stores the beginning of the host name in NAME even |
| if the host name won't entirely fit. For some purposes, a |
| truncated host name is good enough. If it is, you can ignore the |
| error code. |
| |
| -- Function: int sethostname (const char *NAME, size_t LENGTH) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `sethostname' function sets the host name of the system that |
| calls it to NAME, a string with length LENGTH. Only privileged |
| processes are permitted to do this. |
| |
| Usually `sethostname' gets called just once, at system boot time. |
| Often, the program that calls it sets it to the value it finds in |
| the file `/etc/hostname'. |
| |
| Be sure to set the host name to the full host name, not just the |
| DNS hostname (see above). |
| |
| The return value is `0' on success and `-1' on failure. The |
| following `errno' error condition is defined for this function: |
| |
| `EPERM' |
| This process cannot set the host name because it is not |
| privileged. |
| |
| -- Function: int getdomainnname (char *NAME, size_t LENGTH) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `getdomainname' returns the NIS (aka YP) domain name of the system |
| on which it is called. Note that this is not the more popular DNS |
| domain name. Get that with `gethostname'. |
| |
| The specifics of this function are analogous to `gethostname', |
| above. |
| |
| |
| -- Function: int setdomainname (const char *NAME, size_t LENGTH) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `setdomainname' sets the NIS (aka YP) domain name of the system on |
| which it is called. Note that this is not the more popular DNS |
| domain name. Set that with `sethostname'. |
| |
| The specifics of this function are analogous to `sethostname', |
| above. |
| |
| |
| -- Function: long int gethostid (void) |
| Preliminary: | MT-Safe hostid env locale | AS-Unsafe dlopen plugin |
| corrupt heap lock | AC-Unsafe lock corrupt mem fd | *Note POSIX |
| Safety Concepts::. |
| |
| This function returns the "host ID" of the machine the program is |
| running on. By convention, this is usually the primary Internet |
| IP address of that machine, converted to a `long int'. However, |
| on some systems it is a meaningless but unique number which is |
| hard-coded for each machine. |
| |
| This is not widely used. It arose in BSD 4.2, but was dropped in |
| BSD 4.4. It is not required by POSIX. |
| |
| The proper way to query the IP address is to use `gethostbyname' |
| on the results of `gethostname'. For more information on IP |
| addresses, *Note Host Addresses::. |
| |
| -- Function: int sethostid (long int ID) |
| Preliminary: | MT-Unsafe const:hostid | AS-Unsafe | AC-Unsafe |
| corrupt fd | *Note POSIX Safety Concepts::. |
| |
| The `sethostid' function sets the "host ID" of the host machine to |
| ID. Only privileged processes are permitted to do this. Usually |
| it happens just once, at system boot time. |
| |
| The proper way to establish the primary IP address of a system is |
| to configure the IP address resolver to associate that IP address |
| with the system's host name as returned by `gethostname'. For |
| example, put a record for the system in `/etc/hosts'. |
| |
| See `gethostid' above for more information on host ids. |
| |
| The return value is `0' on success and `-1' on failure. The |
| following `errno' error conditions are defined for this function: |
| |
| `EPERM' |
| This process cannot set the host name because it is not |
| privileged. |
| |
| `ENOSYS' |
| The operating system does not support setting the host ID. |
| On some systems, the host ID is a meaningless but unique |
| number hard-coded for each machine. |
| |
| |
| File: libc.info, Node: Platform Type, Next: Filesystem Handling, Prev: Host Identification, Up: System Management |
| |
| 31.2 Platform Type Identification |
| ================================= |
| |
| You can use the `uname' function to find out some information about the |
| type of computer your program is running on. This function and the |
| associated data type are declared in the header file `sys/utsname.h'. |
| |
| As a bonus, `uname' also gives some information identifying the |
| particular system your program is running on. This is the same |
| information which you can get with functions targeted to this purpose |
| described in *note Host Identification::. |
| |
| -- Data Type: struct utsname |
| The `utsname' structure is used to hold information returned by |
| the `uname' function. It has the following members: |
| |
| `char sysname[]' |
| This is the name of the operating system in use. |
| |
| `char release[]' |
| This is the current release level of the operating system |
| implementation. |
| |
| `char version[]' |
| This is the current version level within the release of the |
| operating system. |
| |
| `char machine[]' |
| This is a description of the type of hardware that is in use. |
| |
| Some systems provide a mechanism to interrogate the kernel |
| directly for this information. On systems without such a |
| mechanism, the GNU C Library fills in this field based on the |
| configuration name that was specified when building and |
| installing the library. |
| |
| GNU uses a three-part name to describe a system |
| configuration; the three parts are CPU, MANUFACTURER and |
| SYSTEM-TYPE, and they are separated with dashes. Any |
| possible combination of three names is potentially |
| meaningful, but most such combinations are meaningless in |
| practice and even the meaningful ones are not necessarily |
| supported by any particular GNU program. |
| |
| Since the value in `machine' is supposed to describe just the |
| hardware, it consists of the first two parts of the |
| configuration name: `CPU-MANUFACTURER'. For example, it |
| might be one of these: |
| |
| `"sparc-sun"', `"i386-ANYTHING"', `"m68k-hp"', |
| `"m68k-sony"', `"m68k-sun"', `"mips-dec"' |
| |
| `char nodename[]' |
| This is the host name of this particular computer. In the |
| GNU C Library, the value is the same as that returned by |
| `gethostname'; see *note Host Identification::. |
| |
| `gethostname' is implemented with a call to `uname'. |
| |
| `char domainname[]' |
| This is the NIS or YP domain name. It is the same value |
| returned by `getdomainname'; see *note Host Identification::. |
| This element is a relatively recent invention and use of it |
| is not as portable as use of the rest of the structure. |
| |
| |
| -- Function: int uname (struct utsname *INFO) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `uname' function fills in the structure pointed to by INFO |
| with information about the operating system and host machine. A |
| non-negative return value indicates that the data was successfully |
| stored. |
| |
| `-1' as the return value indicates an error. The only error |
| possible is `EFAULT', which we normally don't mention as it is |
| always a possibility. |
| |
| |
| File: libc.info, Node: Filesystem Handling, Next: System Parameters, Prev: Platform Type, Up: System Management |
| |
| 31.3 Controlling and Querying Mounts |
| ==================================== |
| |
| All files are in filesystems, and before you can access any file, its |
| filesystem must be mounted. Because of Unix's concept of _Everything |
| is a file_, mounting of filesystems is central to doing almost |
| anything. This section explains how to find out what filesystems are |
| currently mounted and what filesystems are available for mounting, and |
| how to change what is mounted. |
| |
| The classic filesystem is the contents of a disk drive. The concept |
| is considerably more abstract, though, and lots of things other than |
| disk drives can be mounted. |
| |
| Some block devices don't correspond to traditional devices like disk |
| drives. For example, a loop device is a block device whose driver uses |
| a regular file in another filesystem as its medium. So if that regular |
| file contains appropriate data for a filesystem, you can by mounting the |
| loop device essentially mount a regular file. |
| |
| Some filesystems aren't based on a device of any kind. The "proc" |
| filesystem, for example, contains files whose data is made up by the |
| filesystem driver on the fly whenever you ask for it. And when you |
| write to it, the data you write causes changes in the system. No data |
| gets stored. |
| |
| * Menu: |
| |
| * Mount Information:: What is or could be mounted? |
| * Mount-Unmount-Remount:: Controlling what is mounted and how |
| |
| |
| File: libc.info, Node: Mount Information, Next: Mount-Unmount-Remount, Up: Filesystem Handling |
| |
| 31.3.1 Mount Information |
| ------------------------ |
| |
| For some programs it is desirable and necessary to access information |
| about whether a certain filesystem is mounted and, if it is, where, or |
| simply to get lists of all the available filesystems. The GNU C Library |
| provides some functions to retrieve this information portably. |
| |
| Traditionally Unix systems have a file named `/etc/fstab' which |
| describes all possibly mounted filesystems. The `mount' program uses |
| this file to mount at startup time of the system all the necessary |
| filesystems. The information about all the filesystems actually |
| mounted is normally kept in a file named either `/var/run/mtab' or |
| `/etc/mtab'. Both files share the same syntax and it is crucial that |
| this syntax is followed all the time. Therefore it is best to never |
| directly write to the files. The functions described in this section |
| can do this and they also provide the functionality to convert the |
| external textual representation to the internal representation. |
| |
| Note that the `fstab' and `mtab' files are maintained on a system by |
| _convention_. It is possible for the files not to exist or not to be |
| consistent with what is really mounted or available to mount, if the |
| system's administration policy allows it. But programs that mount and |
| unmount filesystems typically maintain and use these files as described |
| herein. |
| |
| The filenames given above should never be used directly. The |
| portable way to handle these files is to use the macros `_PATH_FSTAB', |
| defined in `fstab.h', or `_PATH_MNTTAB', defined in `mntent.h' and |
| `paths.h', for `fstab'; and the macro `_PATH_MOUNTED', also defined in |
| `mntent.h' and `paths.h', for `mtab'. There are also two alternate |
| macro names `FSTAB', `MNTTAB', and `MOUNTED' defined but these names |
| are deprecated and kept only for backward compatibility. The names |
| `_PATH_MNTTAB' and `_PATH_MOUNTED' should always be used. |
| |
| * Menu: |
| |
| * fstab:: The `fstab' file |
| * mtab:: The `mtab' file |
| * Other Mount Information:: Other (non-libc) sources of mount information |
| |
| |
| File: libc.info, Node: fstab, Next: mtab, Up: Mount Information |
| |
| 31.3.1.1 The `fstab' file |
| ......................... |
| |
| The internal representation for entries of the file is `struct fstab', |
| defined in `fstab.h'. |
| |
| -- Data Type: struct fstab |
| This structure is used with the `getfsent', `getfsspec', and |
| `getfsfile' functions. |
| |
| `char *fs_spec' |
| This element describes the device from which the filesystem |
| is mounted. Normally this is the name of a special device, |
| such as a hard disk partition, but it could also be a more or |
| less generic string. For "NFS" it would be a hostname and |
| directory name combination. |
| |
| Even though the element is not declared `const' it shouldn't |
| be modified. The missing `const' has historic reasons, since |
| this function predates ISO C. The same is true for the other |
| string elements of this structure. |
| |
| `char *fs_file' |
| This describes the mount point on the local system. I.e., |
| accessing any file in this filesystem has implicitly or |
| explicitly this string as a prefix. |
| |
| `char *fs_vfstype' |
| This is the type of the filesystem. Depending on what the |
| underlying kernel understands it can be any string. |
| |
| `char *fs_mntops' |
| This is a string containing options passed to the kernel with |
| the `mount' call. Again, this can be almost anything. There |
| can be more than one option, separated from the others by a |
| comma. Each option consists of a name and an optional value |
| part, introduced by an `=' character. |
| |
| If the value of this element must be processed it should |
| ideally be done using the `getsubopt' function; see *note |
| Suboptions::. |
| |
| `const char *fs_type' |
| This name is poorly chosen. This element points to a string |
| (possibly in the `fs_mntops' string) which describes the |
| modes with which the filesystem is mounted. `fstab' defines |
| five macros to describe the possible values: |
| |
| `FSTAB_RW' |
| The filesystem gets mounted with read and write enabled. |
| |
| `FSTAB_RQ' |
| The filesystem gets mounted with read and write enabled. |
| Write access is restricted by quotas. |
| |
| `FSTAB_RO' |
| The filesystem gets mounted read-only. |
| |
| `FSTAB_SW' |
| This is not a real filesystem, it is a swap device. |
| |
| `FSTAB_XX' |
| This entry from the `fstab' file is totally ignored. |
| |
| Testing for equality with these values must happen using |
| `strcmp' since these are all strings. Comparing the pointer |
| will probably always fail. |
| |
| `int fs_freq' |
| This element describes the dump frequency in days. |
| |
| `int fs_passno' |
| This element describes the pass number on parallel dumps. It |
| is closely related to the `dump' utility used on Unix systems. |
| |
| To read the entire content of the of the `fstab' file the GNU C |
| Library contains a set of three functions which are designed in the |
| usual way. |
| |
| -- Function: int setfsent (void) |
| Preliminary: | MT-Unsafe race:fsent | AS-Unsafe heap corrupt lock |
| | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::. |
| |
| This function makes sure that the internal read pointer for the |
| `fstab' file is at the beginning of the file. This is done by |
| either opening the file or resetting the read pointer. |
| |
| Since the file handle is internal to the libc this function is not |
| thread-safe. |
| |
| This function returns a non-zero value if the operation was |
| successful and the `getfs*' functions can be used to read the |
| entries of the file. |
| |
| -- Function: void endfsent (void) |
| Preliminary: | MT-Unsafe race:fsent | AS-Unsafe heap corrupt lock |
| | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::. |
| |
| This function makes sure that all resources acquired by a prior |
| call to `setfsent' (explicitly or implicitly by calling |
| `getfsent') are freed. |
| |
| -- Function: struct fstab * getfsent (void) |
| Preliminary: | MT-Unsafe race:fsent locale | AS-Unsafe corrupt |
| heap lock | AC-Unsafe corrupt lock mem | *Note POSIX Safety |
| Concepts::. |
| |
| This function returns the next entry of the `fstab' file. If this |
| is the first call to any of the functions handling `fstab' since |
| program start or the last call of `endfsent', the file will be |
| opened. |
| |
| The function returns a pointer to a variable of type `struct |
| fstab'. This variable is shared by all threads and therefore this |
| function is not thread-safe. If an error occurred `getfsent' |
| returns a `NULL' pointer. |
| |
| -- Function: struct fstab * getfsspec (const char *NAME) |
| Preliminary: | MT-Unsafe race:fsent locale | AS-Unsafe corrupt |
| heap lock | AC-Unsafe corrupt lock mem | *Note POSIX Safety |
| Concepts::. |
| |
| This function returns the next entry of the `fstab' file which has |
| a string equal to NAME pointed to by the `fs_spec' element. Since |
| there is normally exactly one entry for each special device it |
| makes no sense to call this function more than once for the same |
| argument. If this is the first call to any of the functions |
| handling `fstab' since program start or the last call of |
| `endfsent', the file will be opened. |
| |
| The function returns a pointer to a variable of type `struct |
| fstab'. This variable is shared by all threads and therefore this |
| function is not thread-safe. If an error occurred `getfsent' |
| returns a `NULL' pointer. |
| |
| -- Function: struct fstab * getfsfile (const char *NAME) |
| Preliminary: | MT-Unsafe race:fsent locale | AS-Unsafe corrupt |
| heap lock | AC-Unsafe corrupt lock mem | *Note POSIX Safety |
| Concepts::. |
| |
| This function returns the next entry of the `fstab' file which has |
| a string equal to NAME pointed to by the `fs_file' element. Since |
| there is normally exactly one entry for each mount point it makes |
| no sense to call this function more than once for the same |
| argument. If this is the first call to any of the functions |
| handling `fstab' since program start or the last call of |
| `endfsent', the file will be opened. |
| |
| The function returns a pointer to a variable of type `struct |
| fstab'. This variable is shared by all threads and therefore this |
| function is not thread-safe. If an error occurred `getfsent' |
| returns a `NULL' pointer. |
| |
| |
| File: libc.info, Node: mtab, Next: Other Mount Information, Prev: fstab, Up: Mount Information |
| |
| 31.3.1.2 The `mtab' file |
| ........................ |
| |
| The following functions and data structure access the `mtab' file. |
| |
| -- Data Type: struct mntent |
| This structure is used with the `getmntent', `getmntent_r', |
| `addmntent', and `hasmntopt' functions. |
| |
| `char *mnt_fsname' |
| This element contains a pointer to a string describing the |
| name of the special device from which the filesystem is |
| mounted. It corresponds to the `fs_spec' element in `struct |
| fstab'. |
| |
| `char *mnt_dir' |
| This element points to a string describing the mount point of |
| the filesystem. It corresponds to the `fs_file' element in |
| `struct fstab'. |
| |
| `char *mnt_type' |
| `mnt_type' describes the filesystem type and is therefore |
| equivalent to `fs_vfstype' in `struct fstab'. `mntent.h' |
| defines a few symbolic names for some of the values this |
| string can have. But since the kernel can support arbitrary |
| filesystems it does not make much sense to give them symbolic |
| names. If one knows the symbol name one also knows the |
| filesystem name. Nevertheless here follows the list of the |
| symbols provided in `mntent.h'. |
| |
| `MNTTYPE_IGNORE' |
| This symbol expands to `"ignore"'. The value is |
| sometimes used in `fstab' files to make sure entries are |
| not used without removing them. |
| |
| `MNTTYPE_NFS' |
| Expands to `"nfs"'. Using this macro sometimes could |
| make sense since it names the default NFS |
| implementation, in case both version 2 and 3 are |
| supported. |
| |
| `MNTTYPE_SWAP' |
| This symbol expands to `"swap"'. It names the special |
| `fstab' entry which names one of the possibly multiple |
| swap partitions. |
| |
| `char *mnt_opts' |
| The element contains a string describing the options used |
| while mounting the filesystem. As for the equivalent element |
| `fs_mntops' of `struct fstab' it is best to use the function |
| `getsubopt' (*note Suboptions::) to access the parts of this |
| string. |
| |
| The `mntent.h' file defines a number of macros with string |
| values which correspond to some of the options understood by |
| the kernel. There might be many more options which are |
| possible so it doesn't make much sense to rely on these |
| macros but to be consistent here is the list: |
| |
| `MNTOPT_DEFAULTS' |
| Expands to `"defaults"'. This option should be used |
| alone since it indicates all values for the customizable |
| values are chosen to be the default. |
| |
| `MNTOPT_RO' |
| Expands to `"ro"'. See the `FSTAB_RO' value, it means |
| the filesystem is mounted read-only. |
| |
| `MNTOPT_RW' |
| Expands to `"rw"'. See the `FSTAB_RW' value, it means |
| the filesystem is mounted with read and write |
| permissions. |
| |
| `MNTOPT_SUID' |
| Expands to `"suid"'. This means that the SUID bit |
| (*note How Change Persona::) is respected when a program |
| from the filesystem is started. |
| |
| `MNTOPT_NOSUID' |
| Expands to `"nosuid"'. This is the opposite of |
| `MNTOPT_SUID', the SUID bit for all files from the |
| filesystem is ignored. |
| |
| `MNTOPT_NOAUTO' |
| Expands to `"noauto"'. At startup time the `mount' |
| program will ignore this entry if it is started with the |
| `-a' option to mount all filesystems mentioned in the |
| `fstab' file. |
| |
| As for the `FSTAB_*' entries introduced above it is important |
| to use `strcmp' to check for equality. |
| |
| `mnt_freq' |
| This elements corresponds to `fs_freq' and also specifies the |
| frequency in days in which dumps are made. |
| |
| `mnt_passno' |
| This element is equivalent to `fs_passno' with the same |
| meaning which is uninteresting for all programs beside `dump'. |
| |
| For accessing the `mtab' file there is again a set of three |
| functions to access all entries in a row. Unlike the functions to |
| handle `fstab' these functions do not access a fixed file and there is |
| even a thread safe variant of the get function. Besides this the GNU C |
| Library contains functions to alter the file and test for specific |
| options. |
| |
| -- Function: FILE * setmntent (const char *FILE, const char *MODE) |
| Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem fd |
| lock | *Note POSIX Safety Concepts::. |
| |
| The `setmntent' function prepares the file named FILE which must |
| be in the format of a `fstab' and `mtab' file for the upcoming |
| processing through the other functions of the family. The MODE |
| parameter can be chosen in the way the OPENTYPE parameter for |
| `fopen' (*note Opening Streams::) can be chosen. If the file is |
| opened for writing the file is also allowed to be empty. |
| |
| If the file was successfully opened `setmntent' returns a file |
| handle for future use. Otherwise the return value is `NULL' and |
| `errno' is set accordingly. |
| |
| -- Function: int endmntent (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock mem |
| fd | *Note POSIX Safety Concepts::. |
| |
| This function takes for the STREAM parameter a file handle which |
| previously was returned from the `setmntent' call. `endmntent' |
| closes the stream and frees all resources. |
| |
| The return value is 1 unless an error occurred in which case it is |
| 0. |
| |
| -- Function: struct mntent * getmntent (FILE *STREAM) |
| Preliminary: | MT-Unsafe race:mntentbuf locale | AS-Unsafe corrupt |
| heap init | AC-Unsafe init corrupt lock mem | *Note POSIX Safety |
| Concepts::. |
| |
| The `getmntent' function takes as the parameter a file handle |
| previously returned by a successful call to `setmntent'. It |
| returns a pointer to a static variable of type `struct mntent' |
| which is filled with the information from the next entry from the |
| file currently read. |
| |
| The file format used prescribes the use of spaces or tab |
| characters to separate the fields. This makes it harder to use |
| names containing one of these characters (e.g., mount points using |
| spaces). Therefore these characters are encoded in the files and |
| the `getmntent' function takes care of the decoding while reading |
| the entries back in. `'\040'' is used to encode a space |
| character, `'\011'' to encode a tab character, `'\012'' to encode |
| a newline character, and `'\\'' to encode a backslash. |
| |
| If there was an error or the end of the file is reached the return |
| value is `NULL'. |
| |
| This function is not thread-safe since all calls to this function |
| return a pointer to the same static variable. `getmntent_r' |
| should be used in situations where multiple threads access the |
| file. |
| |
| -- Function: struct mntent * getmntent_r (FILE *STREAM, struct mntent |
| *RESULT, char *BUFFER, int BUFSIZE) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe |
| corrupt lock mem | *Note POSIX Safety Concepts::. |
| |
| The `getmntent_r' function is the reentrant variant of |
| `getmntent'. It also returns the next entry from the file and |
| returns a pointer. The actual variable the values are stored in |
| is not static, though. Instead the function stores the values in |
| the variable pointed to by the RESULT parameter. Additional |
| information (e.g., the strings pointed to by the elements of the |
| result) are kept in the buffer of size BUFSIZE pointed to by |
| BUFFER. |
| |
| Escaped characters (space, tab, backslash) are converted back in |
| the same way as it happens for `getmentent'. |
| |
| The function returns a `NULL' pointer in error cases. Errors |
| could be: |
| * error while reading the file, |
| |
| * end of file reached, |
| |
| * BUFSIZE is too small for reading a complete new entry. |
| |
| -- Function: int addmntent (FILE *STREAM, const struct mntent *MNT) |
| Preliminary: | MT-Safe race:stream locale | AS-Unsafe corrupt | |
| AC-Unsafe corrupt | *Note POSIX Safety Concepts::. |
| |
| The `addmntent' function allows adding a new entry to the file |
| previously opened with `setmntent'. The new entries are always |
| appended. I.e., even if the position of the file descriptor is |
| not at the end of the file this function does not overwrite an |
| existing entry following the current position. |
| |
| The implication of this is that to remove an entry from a file one |
| has to create a new file while leaving out the entry to be removed |
| and after closing the file remove the old one and rename the new |
| file to the chosen name. |
| |
| This function takes care of spaces and tab characters in the names |
| to be written to the file. It converts them and the backslash |
| character into the format described in the `getmntent' description |
| above. |
| |
| This function returns 0 in case the operation was successful. |
| Otherwise the return value is 1 and `errno' is set appropriately. |
| |
| -- Function: char * hasmntopt (const struct mntent *MNT, const char |
| *OPT) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function can be used to check whether the string pointed to |
| by the `mnt_opts' element of the variable pointed to by MNT |
| contains the option OPT. If this is true a pointer to the |
| beginning of the option in the `mnt_opts' element is returned. If |
| no such option exists the function returns `NULL'. |
| |
| This function is useful to test whether a specific option is |
| present but when all options have to be processed one is better |
| off with using the `getsubopt' function to iterate over all |
| options in the string. |
| |
| |
| File: libc.info, Node: Other Mount Information, Prev: mtab, Up: Mount Information |
| |
| 31.3.1.3 Other (Non-libc) Sources of Mount Information |
| ...................................................... |
| |
| On a system with a Linux kernel and the `proc' filesystem, you can get |
| information on currently mounted filesystems from the file `mounts' in |
| the `proc' filesystem. Its format is similar to that of the `mtab' |
| file, but represents what is truly mounted without relying on |
| facilities outside the kernel to keep `mtab' up to date. |
| |
| |
| File: libc.info, Node: Mount-Unmount-Remount, Prev: Mount Information, Up: Filesystem Handling |
| |
| 31.3.2 Mount, Unmount, Remount |
| ------------------------------ |
| |
| This section describes the functions for mounting, unmounting, and |
| remounting filesystems. |
| |
| Only the superuser can mount, unmount, or remount a filesystem. |
| |
| These functions do not access the `fstab' and `mtab' files. You |
| should maintain and use these separately. *Note Mount Information::. |
| |
| The symbols in this section are declared in `sys/mount.h'. |
| |
| -- Function: int mount (const char *SPECIAL_FILE, const char *DIR, |
| const char *FSTYPE, unsigned long int OPTIONS, const void |
| *DATA) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `mount' mounts or remounts a filesystem. The two operations are |
| quite different and are merged rather unnaturally into this one |
| function. The `MS_REMOUNT' option, explained below, determines |
| whether `mount' mounts or remounts. |
| |
| For a mount, the filesystem on the block device represented by the |
| device special file named SPECIAL_FILE gets mounted over the mount |
| point DIR. This means that the directory DIR (along with any |
| files in it) is no longer visible; in its place (and still with |
| the name DIR) is the root directory of the filesystem on the |
| device. |
| |
| As an exception, if the filesystem type (see below) is one which |
| is not based on a device (e.g. "proc"), `mount' instantiates a |
| filesystem and mounts it over DIR and ignores SPECIAL_FILE. |
| |
| For a remount, DIR specifies the mount point where the filesystem |
| to be remounted is (and remains) mounted and SPECIAL_FILE is |
| ignored. Remounting a filesystem means changing the options that |
| control operations on the filesystem while it is mounted. It does |
| not mean unmounting and mounting again. |
| |
| For a mount, you must identify the type of the filesystem with |
| FSTYPE. This type tells the kernel how to access the filesystem |
| and can be thought of as the name of a filesystem driver. The |
| acceptable values are system dependent. On a system with a Linux |
| kernel and the `proc' filesystem, the list of possible values is |
| in the file `filesystems' in the `proc' filesystem (e.g. type `cat |
| /proc/filesystems' to see the list). With a Linux kernel, the |
| types of filesystems that `mount' can mount, and their type names, |
| depends on what filesystem drivers are configured into the kernel |
| or loaded as loadable kernel modules. An example of a common |
| value for FSTYPE is `ext2'. |
| |
| For a remount, `mount' ignores FSTYPE. |
| |
| OPTIONS specifies a variety of options that apply until the |
| filesystem is unmounted or remounted. The precise meaning of an |
| option depends on the filesystem and with some filesystems, an |
| option may have no effect at all. Furthermore, for some |
| filesystems, some of these options (but never `MS_RDONLY') can be |
| overridden for individual file accesses via `ioctl'. |
| |
| OPTIONS is a bit string with bit fields defined using the |
| following mask and masked value macros: |
| |
| `MS_MGC_MASK' |
| This multibit field contains a magic number. If it does not |
| have the value `MS_MGC_VAL', `mount' assumes all the |
| following bits are zero and the DATA argument is a null |
| string, regardless of their actual values. |
| |
| `MS_REMOUNT' |
| This bit on means to remount the filesystem. Off means to |
| mount it. |
| |
| `MS_RDONLY' |
| This bit on specifies that no writing to the filesystem shall |
| be allowed while it is mounted. This cannot be overridden by |
| `ioctl'. This option is available on nearly all filesystems. |
| |
| `MS_NOSUID' |
| This bit on specifies that Setuid and Setgid permissions on |
| files in the filesystem shall be ignored while it is mounted. |
| |
| `MS_NOEXEC' |
| This bit on specifies that no files in the filesystem shall |
| be executed while the filesystem is mounted. |
| |
| `MS_NODEV' |
| This bit on specifies that no device special files in the |
| filesystem shall be accessible while the filesystem is |
| mounted. |
| |
| `MS_SYNCHRONOUS' |
| This bit on specifies that all writes to the filesystem while |
| it is mounted shall be synchronous; i.e., data shall be |
| synced before each write completes rather than held in the |
| buffer cache. |
| |
| `MS_MANDLOCK' |
| This bit on specifies that mandatory locks on files shall be |
| permitted while the filesystem is mounted. |
| |
| `MS_NOATIME' |
| This bit on specifies that access times of files shall not be |
| updated when the files are accessed while the filesystem is |
| mounted. |
| |
| `MS_NODIRATIME' |
| This bit on specifies that access times of directories shall |
| not be updated when the directories are accessed while the |
| filesystem in mounted. |
| |
| |
| Any bits not covered by the above masks should be set off; |
| otherwise, results are undefined. |
| |
| The meaning of DATA depends on the filesystem type and is |
| controlled entirely by the filesystem driver in the kernel. |
| |
| Example: |
| |
| #include <sys/mount.h> |
| |
| mount("/dev/hdb", "/cdrom", MS_MGC_VAL | MS_RDONLY | MS_NOSUID, ""); |
| |
| mount("/dev/hda2", "/mnt", MS_MGC_VAL | MS_REMOUNT, ""); |
| |
| Appropriate arguments for `mount' are conventionally recorded in |
| the `fstab' table. *Note Mount Information::. |
| |
| The return value is zero if the mount or remount is successful. |
| Otherwise, it is `-1' and `errno' is set appropriately. The |
| values of `errno' are filesystem dependent, but here is a general |
| list: |
| |
| `EPERM' |
| The process is not superuser. |
| |
| `ENODEV' |
| The file system type FSTYPE is not known to the kernel. |
| |
| `ENOTBLK' |
| The file DEV is not a block device special file. |
| |
| `EBUSY' |
| * The device is already mounted. |
| |
| * The mount point is busy. (E.g. it is some process' |
| working directory or has a filesystem mounted on it |
| already). |
| |
| * The request is to remount read-only, but there are files |
| open for writing. |
| |
| `EINVAL' |
| * A remount was attempted, but there is no filesystem |
| mounted over the specified mount point. |
| |
| * The supposed filesystem has an invalid superblock. |
| |
| |
| `EACCES' |
| * The filesystem is inherently read-only (possibly due to |
| a switch on the device) and the process attempted to |
| mount it read/write (by setting the `MS_RDONLY' bit off). |
| |
| * SPECIAL_FILE or DIR is not accessible due to file |
| permissions. |
| |
| * SPECIAL_FILE is not accessible because it is in a |
| filesystem that is mounted with the `MS_NODEV' option. |
| |
| |
| `EM_FILE' |
| The table of dummy devices is full. `mount' needs to create a |
| dummy device (aka "unnamed" device) if the filesystem being |
| mounted is not one that uses a device. |
| |
| |
| |
| -- Function: int umount2 (const char *FILE, int FLAGS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `umount2' unmounts a filesystem. |
| |
| You can identify the filesystem to unmount either by the device |
| special file that contains the filesystem or by the mount point. |
| The effect is the same. Specify either as the string FILE. |
| |
| FLAGS contains the one-bit field identified by the following mask |
| macro: |
| |
| `MNT_FORCE' |
| This bit on means to force the unmounting even if the |
| filesystem is busy, by making it unbusy first. If the bit is |
| off and the filesystem is busy, `umount2' fails with `errno' |
| = `EBUSY'. Depending on the filesystem, this may override |
| all, some, or no busy conditions. |
| |
| |
| All other bits in FLAGS should be set to zero; otherwise, the |
| result is undefined. |
| |
| Example: |
| |
| #include <sys/mount.h> |
| |
| umount2("/mnt", MNT_FORCE); |
| |
| umount2("/dev/hdd1", 0); |
| |
| After the filesystem is unmounted, the directory that was the |
| mount point is visible, as are any files in it. |
| |
| As part of unmounting, `umount2' syncs the filesystem. |
| |
| If the unmounting is successful, the return value is zero. |
| Otherwise, it is `-1' and `errno' is set accordingly: |
| |
| `EPERM' |
| The process is not superuser. |
| |
| `EBUSY' |
| The filesystem cannot be unmounted because it is busy. E.g. |
| it contains a directory that is some process's working |
| directory or a file that some process has open. With some |
| filesystems in some cases, you can avoid this failure with |
| the `MNT_FORCE' option. |
| |
| `EINVAL' |
| FILE validly refers to a file, but that file is neither a |
| mount point nor a device special file of a currently mounted |
| filesystem. |
| |
| |
| This function is not available on all systems. |
| |
| -- Function: int umount (const char *FILE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `umount' does the same thing as `umount2' with FLAGS set to |
| zeroes. It is more widely available than `umount2' but since it |
| lacks the possibility to forcefully unmount a filesystem is |
| deprecated when `umount2' is also available. |
| |
| |
| File: libc.info, Node: System Parameters, Prev: Filesystem Handling, Up: System Management |
| |
| 31.4 System Parameters |
| ====================== |
| |
| This section describes the `sysctl' function, which gets and sets a |
| variety of system parameters. |
| |
| The symbols used in this section are declared in the file |
| `sys/sysctl.h'. |
| |
| -- Function: int sysctl (int *NAMES, int NLEN, void *OLDVAL, size_t |
| *OLDLENP, void *NEWVAL, size_t NEWLEN) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `sysctl' gets or sets a specified system parameter. There are so |
| many of these parameters that it is not practical to list them all |
| here, but here are some examples: |
| |
| * network domain name |
| |
| * paging parameters |
| |
| * network Address Resolution Protocol timeout time |
| |
| * maximum number of files that may be open |
| |
| * root filesystem device |
| |
| * when kernel was built |
| |
| The set of available parameters depends on the kernel |
| configuration and can change while the system is running, |
| particularly when you load and unload loadable kernel modules. |
| |
| The system parameters with which `sysctl' is concerned are arranged |
| in a hierarchical structure like a hierarchical filesystem. To |
| identify a particular parameter, you specify a path through the |
| structure in a way analogous to specifying the pathname of a file. |
| Each component of the path is specified by an integer and each of |
| these integers has a macro defined for it by `sys/sysctl.h'. |
| NAMES is the path, in the form of an array of integers. Each |
| component of the path is one element of the array, in order. NLEN |
| is the number of components in the path. |
| |
| For example, the first component of the path for all the paging |
| parameters is the value `CTL_VM'. For the free page thresholds, |
| the second component of the path is `VM_FREEPG'. So to get the |
| free page threshold values, make NAMES an array containing the two |
| elements `CTL_VM' and `VM_FREEPG' and make NLEN = 2. |
| |
| The format of the value of a parameter depends on the parameter. |
| Sometimes it is an integer; sometimes it is an ASCII string; |
| sometimes it is an elaborate structure. In the case of the free |
| page thresholds used in the example above, the parameter value is |
| a structure containing several integers. |
| |
| In any case, you identify a place to return the parameter's value |
| with OLDVAL and specify the amount of storage available at that |
| location as *OLDLENP. *OLDLENP does double duty because it is |
| also the output location that contains the actual length of the |
| returned value. |
| |
| If you don't want the parameter value returned, specify a null |
| pointer for OLDVAL. |
| |
| To set the parameter, specify the address and length of the new |
| value as NEWVAL and NEWLEN. If you don't want to set the |
| parameter, specify a null pointer as NEWVAL. |
| |
| If you get and set a parameter in the same `sysctl' call, the value |
| returned is the value of the parameter before it was set. |
| |
| Each system parameter has a set of permissions similar to the |
| permissions for a file (including the permissions on directories |
| in its path) that determine whether you may get or set it. For |
| the purposes of these permissions, every parameter is considered |
| to be owned by the superuser and Group 0 so processes with that |
| effective uid or gid may have more access to system parameters. |
| Unlike with files, the superuser does not invariably have full |
| permission to all system parameters, because some of them are |
| designed not to be changed ever. |
| |
| `sysctl' returns a zero return value if it succeeds. Otherwise, it |
| returns `-1' and sets `errno' appropriately. Besides the failures |
| that apply to all system calls, the following are the `errno' |
| codes for all possible failures: |
| |
| `EPERM' |
| The process is not permitted to access one of the components |
| of the path of the system parameter or is not permitted to |
| access the system parameter itself in the way (read or write) |
| that it requested. |
| |
| `ENOTDIR' |
| There is no system parameter corresponding to NAME. |
| |
| `EFAULT' |
| OLDVAL is not null, which means the process wanted to read |
| the parameter, but *OLDLENP is zero, so there is no place to |
| return it. |
| |
| `EINVAL' |
| * The process attempted to set a system parameter to a |
| value that is not valid for that parameter. |
| |
| * The space provided for the return of the system |
| parameter is not the right size for that parameter. |
| |
| `ENOMEM' |
| This value may be returned instead of the more correct |
| `EINVAL' in some cases where the space provided for the |
| return of the system parameter is too small. |
| |
| |
| |
| If you have a Linux kernel with the `proc' filesystem, you can get |
| and set most of the same parameters by reading and writing to files in |
| the `sys' directory of the `proc' filesystem. In the `sys' directory, |
| the directory structure represents the hierarchical structure of the |
| parameters. E.g. you can display the free page thresholds with |
| cat /proc/sys/vm/freepages |
| |
| Some more traditional and more widely available, though less general, |
| GNU C Library functions for getting and setting some of the same system |
| parameters are: |
| |
| * `getdomainname', `setdomainname' |
| |
| * `gethostname', `sethostname' (*Note Host Identification::.) |
| |
| * `uname' (*Note Platform Type::.) |
| |
| |
| File: libc.info, Node: System Configuration, Next: Cryptographic Functions, Prev: System Management, Up: Top |
| |
| 32 System Configuration Parameters |
| ********************************** |
| |
| The functions and macros listed in this chapter give information about |
| configuration parameters of the operating system--for example, capacity |
| limits, presence of optional POSIX features, and the default path for |
| executable files (*note String Parameters::). |
| |
| * Menu: |
| |
| * General Limits:: Constants and functions that describe |
| various process-related limits that have |
| one uniform value for any given machine. |
| * System Options:: Optional POSIX features. |
| * Version Supported:: Version numbers of POSIX.1 and POSIX.2. |
| * Sysconf:: Getting specific configuration values |
| of general limits and system options. |
| * Minimums:: Minimum values for general limits. |
| |
| * Limits for Files:: Size limitations that pertain to individual files. |
| These can vary between file systems |
| or even from file to file. |
| * Options for Files:: Optional features that some files may support. |
| * File Minimums:: Minimum values for file limits. |
| * Pathconf:: Getting the limit values for a particular file. |
| |
| * Utility Limits:: Capacity limits of some POSIX.2 utility programs. |
| * Utility Minimums:: Minimum allowable values of those limits. |
| |
| * String Parameters:: Getting the default search path. |
| |
| |
| File: libc.info, Node: General Limits, Next: System Options, Up: System Configuration |
| |
| 32.1 General Capacity Limits |
| ============================ |
| |
| The POSIX.1 and POSIX.2 standards specify a number of parameters that |
| describe capacity limitations of the system. These limits can be fixed |
| constants for a given operating system, or they can vary from machine to |
| machine. For example, some limit values may be configurable by the |
| system administrator, either at run time or by rebuilding the kernel, |
| and this should not require recompiling application programs. |
| |
| Each of the following limit parameters has a macro that is defined in |
| `limits.h' only if the system has a fixed, uniform limit for the |
| parameter in question. If the system allows different file systems or |
| files to have different limits, then the macro is undefined; use |
| `sysconf' to find out the limit that applies at a particular time on a |
| particular machine. *Note Sysconf::. |
| |
| Each of these parameters also has another macro, with a name starting |
| with `_POSIX', which gives the lowest value that the limit is allowed |
| to have on _any_ POSIX system. *Note Minimums::. |
| |
| -- Macro: int ARG_MAX |
| If defined, the unvarying maximum combined length of the ARGV and |
| ENVIRON arguments that can be passed to the `exec' functions. |
| |
| -- Macro: int CHILD_MAX |
| If defined, the unvarying maximum number of processes that can |
| exist with the same real user ID at any one time. In BSD and GNU, |
| this is controlled by the `RLIMIT_NPROC' resource limit; *note |
| Limits on Resources::. |
| |
| -- Macro: int OPEN_MAX |
| If defined, the unvarying maximum number of files that a single |
| process can have open simultaneously. In BSD and GNU, this is |
| controlled by the `RLIMIT_NOFILE' resource limit; *note Limits on |
| Resources::. |
| |
| -- Macro: int STREAM_MAX |
| If defined, the unvarying maximum number of streams that a single |
| process can have open simultaneously. *Note Opening Streams::. |
| |
| -- Macro: int TZNAME_MAX |
| If defined, the unvarying maximum length of a time zone name. |
| *Note Time Zone Functions::. |
| |
| These limit macros are always defined in `limits.h'. |
| |
| -- Macro: int NGROUPS_MAX |
| The maximum number of supplementary group IDs that one process can |
| have. |
| |
| The value of this macro is actually a lower bound for the maximum. |
| That is, you can count on being able to have that many |
| supplementary group IDs, but a particular machine might let you |
| have even more. You can use `sysconf' to see whether a particular |
| machine will let you have more (*note Sysconf::). |
| |
| -- Macro: ssize_t SSIZE_MAX |
| The largest value that can fit in an object of type `ssize_t'. |
| Effectively, this is the limit on the number of bytes that can be |
| read or written in a single operation. |
| |
| This macro is defined in all POSIX systems because this limit is |
| never configurable. |
| |
| -- Macro: int RE_DUP_MAX |
| The largest number of repetitions you are guaranteed is allowed in |
| the construct `\{MIN,MAX\}' in a regular expression. |
| |
| The value of this macro is actually a lower bound for the maximum. |
| That is, you can count on being able to have that many |
| repetitions, but a particular machine might let you have even |
| more. You can use `sysconf' to see whether a particular machine |
| will let you have more (*note Sysconf::). And even the value that |
| `sysconf' tells you is just a lower bound--larger values might |
| work. |
| |
| This macro is defined in all POSIX.2 systems, because POSIX.2 says |
| it should always be defined even if there is no specific imposed |
| limit. |
| |
| |
| File: libc.info, Node: System Options, Next: Version Supported, Prev: General Limits, Up: System Configuration |
| |
| 32.2 Overall System Options |
| =========================== |
| |
| POSIX defines certain system-specific options that not all POSIX systems |
| support. Since these options are provided in the kernel, not in the |
| library, simply using the GNU C Library does not guarantee any of these |
| features are supported; it depends on the system you are using. |
| |
| You can test for the availability of a given option using the macros |
| in this section, together with the function `sysconf'. The macros are |
| defined only if you include `unistd.h'. |
| |
| For the following macros, if the macro is defined in `unistd.h', |
| then the option is supported. Otherwise, the option may or may not be |
| supported; use `sysconf' to find out. *Note Sysconf::. |
| |
| -- Macro: int _POSIX_JOB_CONTROL |
| If this symbol is defined, it indicates that the system supports |
| job control. Otherwise, the implementation behaves as if all |
| processes within a session belong to a single process group. |
| *Note Job Control::. Systems conforming to the 2001 revision of |
| POSIX, or newer, will always define this symbol. |
| |
| -- Macro: int _POSIX_SAVED_IDS |
| If this symbol is defined, it indicates that the system remembers |
| the effective user and group IDs of a process before it executes an |
| executable file with the set-user-ID or set-group-ID bits set, and |
| that explicitly changing the effective user or group IDs back to |
| these values is permitted. If this option is not defined, then if |
| a nonprivileged process changes its effective user or group ID to |
| the real user or group ID of the process, it can't change it back |
| again. *Note Enable/Disable Setuid::. |
| |
| For the following macros, if the macro is defined in `unistd.h', |
| then its value indicates whether the option is supported. A value of |
| `-1' means no, and any other value means yes. If the macro is not |
| defined, then the option may or may not be supported; use `sysconf' to |
| find out. *Note Sysconf::. |
| |
| -- Macro: int _POSIX2_C_DEV |
| If this symbol is defined, it indicates that the system has the |
| POSIX.2 C compiler command, `c89'. The GNU C Library always |
| defines this as `1', on the assumption that you would not have |
| installed it if you didn't have a C compiler. |
| |
| -- Macro: int _POSIX2_FORT_DEV |
| If this symbol is defined, it indicates that the system has the |
| POSIX.2 Fortran compiler command, `fort77'. The GNU C Library |
| never defines this, because we don't know what the system has. |
| |
| -- Macro: int _POSIX2_FORT_RUN |
| If this symbol is defined, it indicates that the system has the |
| POSIX.2 `asa' command to interpret Fortran carriage control. The |
| GNU C Library never defines this, because we don't know what the |
| system has. |
| |
| -- Macro: int _POSIX2_LOCALEDEF |
| If this symbol is defined, it indicates that the system has the |
| POSIX.2 `localedef' command. The GNU C Library never defines |
| this, because we don't know what the system has. |
| |
| -- Macro: int _POSIX2_SW_DEV |
| If this symbol is defined, it indicates that the system has the |
| POSIX.2 commands `ar', `make', and `strip'. The GNU C Library |
| always defines this as `1', on the assumption that you had to have |
| `ar' and `make' to install the library, and it's unlikely that |
| `strip' would be absent when those are present. |
| |
| |
| File: libc.info, Node: Version Supported, Next: Sysconf, Prev: System Options, Up: System Configuration |
| |
| 32.3 Which Version of POSIX is Supported |
| ======================================== |
| |
| -- Macro: long int _POSIX_VERSION |
| This constant represents the version of the POSIX.1 standard to |
| which the implementation conforms. For an implementation |
| conforming to the 1995 POSIX.1 standard, the value is the integer |
| `199506L'. |
| |
| `_POSIX_VERSION' is always defined (in `unistd.h') in any POSIX |
| system. |
| |
| *Usage Note:* Don't try to test whether the system supports POSIX |
| by including `unistd.h' and then checking whether `_POSIX_VERSION' |
| is defined. On a non-POSIX system, this will probably fail |
| because there is no `unistd.h'. We do not know of _any_ way you |
| can reliably test at compilation time whether your target system |
| supports POSIX or whether `unistd.h' exists. |
| |
| -- Macro: long int _POSIX2_C_VERSION |
| This constant represents the version of the POSIX.2 standard which |
| the library and system kernel support. We don't know what value |
| this will be for the first version of the POSIX.2 standard, |
| because the value is based on the year and month in which the |
| standard is officially adopted. |
| |
| The value of this symbol says nothing about the utilities |
| installed on the system. |
| |
| *Usage Note:* You can use this macro to tell whether a POSIX.1 |
| system library supports POSIX.2 as well. Any POSIX.1 system |
| contains `unistd.h', so include that file and then test `defined |
| (_POSIX2_C_VERSION)'. |
| |
| |
| File: libc.info, Node: Sysconf, Next: Minimums, Prev: Version Supported, Up: System Configuration |
| |
| 32.4 Using `sysconf' |
| ==================== |
| |
| When your system has configurable system limits, you can use the |
| `sysconf' function to find out the value that applies to any particular |
| machine. The function and the associated PARAMETER constants are |
| declared in the header file `unistd.h'. |
| |
| * Menu: |
| |
| * Sysconf Definition:: Detailed specifications of `sysconf'. |
| * Constants for Sysconf:: The list of parameters `sysconf' can read. |
| * Examples of Sysconf:: How to use `sysconf' and the parameter |
| macros properly together. |
| |
| |
| File: libc.info, Node: Sysconf Definition, Next: Constants for Sysconf, Up: Sysconf |
| |
| 32.4.1 Definition of `sysconf' |
| ------------------------------ |
| |
| -- Function: long int sysconf (int PARAMETER) |
| Preliminary: | MT-Safe env | AS-Unsafe lock heap | AC-Unsafe lock |
| mem fd | *Note POSIX Safety Concepts::. |
| |
| This function is used to inquire about runtime system parameters. |
| The PARAMETER argument should be one of the `_SC_' symbols listed |
| below. |
| |
| The normal return value from `sysconf' is the value you requested. |
| A value of `-1' is returned both if the implementation does not |
| impose a limit, and in case of an error. |
| |
| The following `errno' error conditions are defined for this |
| function: |
| |
| `EINVAL' |
| The value of the PARAMETER is invalid. |
| |
| |
| File: libc.info, Node: Constants for Sysconf, Next: Examples of Sysconf, Prev: Sysconf Definition, Up: Sysconf |
| |
| 32.4.2 Constants for `sysconf' Parameters |
| ----------------------------------------- |
| |
| Here are the symbolic constants for use as the PARAMETER argument to |
| `sysconf'. The values are all integer constants (more specifically, |
| enumeration type values). |
| |
| `_SC_ARG_MAX' |
| Inquire about the parameter corresponding to `ARG_MAX'. |
| |
| `_SC_CHILD_MAX' |
| Inquire about the parameter corresponding to `CHILD_MAX'. |
| |
| `_SC_OPEN_MAX' |
| Inquire about the parameter corresponding to `OPEN_MAX'. |
| |
| `_SC_STREAM_MAX' |
| Inquire about the parameter corresponding to `STREAM_MAX'. |
| |
| `_SC_TZNAME_MAX' |
| Inquire about the parameter corresponding to `TZNAME_MAX'. |
| |
| `_SC_NGROUPS_MAX' |
| Inquire about the parameter corresponding to `NGROUPS_MAX'. |
| |
| `_SC_JOB_CONTROL' |
| Inquire about the parameter corresponding to `_POSIX_JOB_CONTROL'. |
| |
| `_SC_SAVED_IDS' |
| Inquire about the parameter corresponding to `_POSIX_SAVED_IDS'. |
| |
| `_SC_VERSION' |
| Inquire about the parameter corresponding to `_POSIX_VERSION'. |
| |
| `_SC_CLK_TCK' |
| Inquire about the number of clock ticks per second; *note CPU |
| Time::. The corresponding parameter `CLK_TCK' is obsolete. |
| |
| `_SC_CHARCLASS_NAME_MAX' |
| Inquire about the parameter corresponding to maximal length |
| allowed for a character class name in an extended locale |
| specification. These extensions are not yet standardized and so |
| this option is not standardized as well. |
| |
| `_SC_REALTIME_SIGNALS' |
| Inquire about the parameter corresponding to |
| `_POSIX_REALTIME_SIGNALS'. |
| |
| `_SC_PRIORITY_SCHEDULING' |
| Inquire about the parameter corresponding to |
| `_POSIX_PRIORITY_SCHEDULING'. |
| |
| `_SC_TIMERS' |
| Inquire about the parameter corresponding to `_POSIX_TIMERS'. |
| |
| `_SC_ASYNCHRONOUS_IO' |
| Inquire about the parameter corresponding to |
| `_POSIX_ASYNCHRONOUS_IO'. |
| |
| `_SC_PRIORITIZED_IO' |
| Inquire about the parameter corresponding to |
| `_POSIX_PRIORITIZED_IO'. |
| |
| `_SC_SYNCHRONIZED_IO' |
| Inquire about the parameter corresponding to |
| `_POSIX_SYNCHRONIZED_IO'. |
| |
| `_SC_FSYNC' |
| Inquire about the parameter corresponding to `_POSIX_FSYNC'. |
| |
| `_SC_MAPPED_FILES' |
| Inquire about the parameter corresponding to `_POSIX_MAPPED_FILES'. |
| |
| `_SC_MEMLOCK' |
| Inquire about the parameter corresponding to `_POSIX_MEMLOCK'. |
| |
| `_SC_MEMLOCK_RANGE' |
| Inquire about the parameter corresponding to |
| `_POSIX_MEMLOCK_RANGE'. |
| |
| `_SC_MEMORY_PROTECTION' |
| Inquire about the parameter corresponding to |
| `_POSIX_MEMORY_PROTECTION'. |
| |
| `_SC_MESSAGE_PASSING' |
| Inquire about the parameter corresponding to |
| `_POSIX_MESSAGE_PASSING'. |
| |
| `_SC_SEMAPHORES' |
| Inquire about the parameter corresponding to `_POSIX_SEMAPHORES'. |
| |
| `_SC_SHARED_MEMORY_OBJECTS' |
| Inquire about the parameter corresponding to |
| `_POSIX_SHARED_MEMORY_OBJECTS'. |
| |
| `_SC_AIO_LISTIO_MAX' |
| Inquire about the parameter corresponding to |
| `_POSIX_AIO_LISTIO_MAX'. |
| |
| `_SC_AIO_MAX' |
| Inquire about the parameter corresponding to `_POSIX_AIO_MAX'. |
| |
| `_SC_AIO_PRIO_DELTA_MAX' |
| Inquire about the value by which a process can decrease its |
| asynchronous I/O priority level from its own scheduling priority. |
| This corresponds to the run-time invariant value |
| `AIO_PRIO_DELTA_MAX'. |
| |
| `_SC_DELAYTIMER_MAX' |
| Inquire about the parameter corresponding to |
| `_POSIX_DELAYTIMER_MAX'. |
| |
| `_SC_MQ_OPEN_MAX' |
| Inquire about the parameter corresponding to `_POSIX_MQ_OPEN_MAX'. |
| |
| `_SC_MQ_PRIO_MAX' |
| Inquire about the parameter corresponding to `_POSIX_MQ_PRIO_MAX'. |
| |
| `_SC_RTSIG_MAX' |
| Inquire about the parameter corresponding to `_POSIX_RTSIG_MAX'. |
| |
| `_SC_SEM_NSEMS_MAX' |
| Inquire about the parameter corresponding to |
| `_POSIX_SEM_NSEMS_MAX'. |
| |
| `_SC_SEM_VALUE_MAX' |
| Inquire about the parameter corresponding to |
| `_POSIX_SEM_VALUE_MAX'. |
| |
| `_SC_SIGQUEUE_MAX' |
| Inquire about the parameter corresponding to `_POSIX_SIGQUEUE_MAX'. |
| |
| `_SC_TIMER_MAX' |
| Inquire about the parameter corresponding to `_POSIX_TIMER_MAX'. |
| |
| `_SC_PII' |
| Inquire about the parameter corresponding to `_POSIX_PII'. |
| |
| `_SC_PII_XTI' |
| Inquire about the parameter corresponding to `_POSIX_PII_XTI'. |
| |
| `_SC_PII_SOCKET' |
| Inquire about the parameter corresponding to `_POSIX_PII_SOCKET'. |
| |
| `_SC_PII_INTERNET' |
| Inquire about the parameter corresponding to `_POSIX_PII_INTERNET'. |
| |
| `_SC_PII_OSI' |
| Inquire about the parameter corresponding to `_POSIX_PII_OSI'. |
| |
| `_SC_SELECT' |
| Inquire about the parameter corresponding to `_POSIX_SELECT'. |
| |
| `_SC_UIO_MAXIOV' |
| Inquire about the parameter corresponding to `_POSIX_UIO_MAXIOV'. |
| |
| `_SC_PII_INTERNET_STREAM' |
| Inquire about the parameter corresponding to |
| `_POSIX_PII_INTERNET_STREAM'. |
| |
| `_SC_PII_INTERNET_DGRAM' |
| Inquire about the parameter corresponding to |
| `_POSIX_PII_INTERNET_DGRAM'. |
| |
| `_SC_PII_OSI_COTS' |
| Inquire about the parameter corresponding to `_POSIX_PII_OSI_COTS'. |
| |
| `_SC_PII_OSI_CLTS' |
| Inquire about the parameter corresponding to `_POSIX_PII_OSI_CLTS'. |
| |
| `_SC_PII_OSI_M' |
| Inquire about the parameter corresponding to `_POSIX_PII_OSI_M'. |
| |
| `_SC_T_IOV_MAX' |
| Inquire about the value associated with the `T_IOV_MAX' variable. |
| |
| `_SC_THREADS' |
| Inquire about the parameter corresponding to `_POSIX_THREADS'. |
| |
| `_SC_THREAD_SAFE_FUNCTIONS' |
| Inquire about the parameter corresponding to |
| `_POSIX_THREAD_SAFE_FUNCTIONS'. |
| |
| `_SC_GETGR_R_SIZE_MAX' |
| Inquire about the parameter corresponding to |
| `_POSIX_GETGR_R_SIZE_MAX'. |
| |
| `_SC_GETPW_R_SIZE_MAX' |
| Inquire about the parameter corresponding to |
| `_POSIX_GETPW_R_SIZE_MAX'. |
| |
| `_SC_LOGIN_NAME_MAX' |
| Inquire about the parameter corresponding to |
| `_POSIX_LOGIN_NAME_MAX'. |
| |
| `_SC_TTY_NAME_MAX' |
| Inquire about the parameter corresponding to `_POSIX_TTY_NAME_MAX'. |
| |
| `_SC_THREAD_DESTRUCTOR_ITERATIONS' |
| Inquire about the parameter corresponding to |
| `_POSIX_THREAD_DESTRUCTOR_ITERATIONS'. |
| |
| `_SC_THREAD_KEYS_MAX' |
| Inquire about the parameter corresponding to |
| `_POSIX_THREAD_KEYS_MAX'. |
| |
| `_SC_THREAD_STACK_MIN' |
| Inquire about the parameter corresponding to |
| `_POSIX_THREAD_STACK_MIN'. |
| |
| `_SC_THREAD_THREADS_MAX' |
| Inquire about the parameter corresponding to |
| `_POSIX_THREAD_THREADS_MAX'. |
| |
| `_SC_THREAD_ATTR_STACKADDR' |
| Inquire about the parameter corresponding to |
| a `_POSIX_THREAD_ATTR_STACKADDR'. |
| |
| `_SC_THREAD_ATTR_STACKSIZE' |
| Inquire about the parameter corresponding to |
| `_POSIX_THREAD_ATTR_STACKSIZE'. |
| |
| `_SC_THREAD_PRIORITY_SCHEDULING' |
| Inquire about the parameter corresponding to |
| `_POSIX_THREAD_PRIORITY_SCHEDULING'. |
| |
| `_SC_THREAD_PRIO_INHERIT' |
| Inquire about the parameter corresponding to |
| `_POSIX_THREAD_PRIO_INHERIT'. |
| |
| `_SC_THREAD_PRIO_PROTECT' |
| Inquire about the parameter corresponding to |
| `_POSIX_THREAD_PRIO_PROTECT'. |
| |
| `_SC_THREAD_PROCESS_SHARED' |
| Inquire about the parameter corresponding to |
| `_POSIX_THREAD_PROCESS_SHARED'. |
| |
| `_SC_2_C_DEV' |
| Inquire about whether the system has the POSIX.2 C compiler |
| command, `c89'. |
| |
| `_SC_2_FORT_DEV' |
| Inquire about whether the system has the POSIX.2 Fortran compiler |
| command, `fort77'. |
| |
| `_SC_2_FORT_RUN' |
| Inquire about whether the system has the POSIX.2 `asa' command to |
| interpret Fortran carriage control. |
| |
| `_SC_2_LOCALEDEF' |
| Inquire about whether the system has the POSIX.2 `localedef' |
| command. |
| |
| `_SC_2_SW_DEV' |
| Inquire about whether the system has the POSIX.2 commands `ar', |
| `make', and `strip'. |
| |
| `_SC_BC_BASE_MAX' |
| Inquire about the maximum value of `obase' in the `bc' utility. |
| |
| `_SC_BC_DIM_MAX' |
| Inquire about the maximum size of an array in the `bc' utility. |
| |
| `_SC_BC_SCALE_MAX' |
| Inquire about the maximum value of `scale' in the `bc' utility. |
| |
| `_SC_BC_STRING_MAX' |
| Inquire about the maximum size of a string constant in the `bc' |
| utility. |
| |
| `_SC_COLL_WEIGHTS_MAX' |
| Inquire about the maximum number of weights that can necessarily |
| be used in defining the collating sequence for a locale. |
| |
| `_SC_EXPR_NEST_MAX' |
| Inquire about the maximum number of expressions nested within |
| parentheses when using the `expr' utility. |
| |
| `_SC_LINE_MAX' |
| Inquire about the maximum size of a text line that the POSIX.2 text |
| utilities can handle. |
| |
| `_SC_EQUIV_CLASS_MAX' |
| Inquire about the maximum number of weights that can be assigned |
| to an entry of the `LC_COLLATE' category `order' keyword in a |
| locale definition. The GNU C Library does not presently support |
| locale definitions. |
| |
| `_SC_VERSION' |
| Inquire about the version number of POSIX.1 that the library and |
| kernel support. |
| |
| `_SC_2_VERSION' |
| Inquire about the version number of POSIX.2 that the system |
| utilities support. |
| |
| `_SC_PAGESIZE' |
| Inquire about the virtual memory page size of the machine. |
| `getpagesize' returns the same value (*note Query Memory |
| Parameters::). |
| |
| `_SC_NPROCESSORS_CONF' |
| Inquire about the number of configured processors. |
| |
| `_SC_NPROCESSORS_ONLN' |
| Inquire about the number of processors online. |
| |
| `_SC_PHYS_PAGES' |
| Inquire about the number of physical pages in the system. |
| |
| `_SC_AVPHYS_PAGES' |
| Inquire about the number of available physical pages in the system. |
| |
| `_SC_ATEXIT_MAX' |
| Inquire about the number of functions which can be registered as |
| termination functions for `atexit'; *note Cleanups on Exit::. |
| |
| `_SC_LEVEL1_ICACHE_SIZE' |
| Inquire about the size of the Level 1 instruction cache. |
| |
| `_SC_LEVEL1_ICACHE_ASSOC' |
| Inquire about the associativity of the Level 1 instruction cache. |
| |
| `_SC_LEVEL1_ICACHE_LINESIZE' |
| Inquire about the line length of the Level 1 instruction cache. |
| |
| On aarch64, the cache line size returned is the minimum |
| instruction cache line size observable by userspace. This is |
| typically the same as the L1 icache size but on some cores it may |
| not be so. However, it is specified in the architecture that |
| operations such as cache line invalidation are consistent with the |
| size reported with this variable. |
| |
| `_SC_LEVEL1_DCACHE_SIZE' |
| Inquire about the size of the Level 1 data cache. |
| |
| `_SC_LEVEL1_DCACHE_ASSOC' |
| Inquire about the associativity of the Level 1 data cache. |
| |
| `_SC_LEVEL1_DCACHE_LINESIZE' |
| Inquire about the line length of the Level 1 data cache. |
| |
| On aarch64, the cache line size returned is the minimum data cache |
| line size observable by userspace. This is typically the same as |
| the L1 dcache size but on some cores it may not be so. However, |
| it is specified in the architecture that operations such as cache |
| line invalidation are consistent with the size reported with this |
| variable. |
| |
| `_SC_LEVEL2_CACHE_SIZE' |
| Inquire about the size of the Level 2 cache. |
| |
| `_SC_LEVEL2_CACHE_ASSOC' |
| Inquire about the associativity of the Level 2 cache. |
| |
| `_SC_LEVEL2_CACHE_LINESIZE' |
| Inquire about the line length of the Level 2 cache. |
| |
| `_SC_LEVEL3_CACHE_SIZE' |
| Inquire about the size of the Level 3 cache. |
| |
| `_SC_LEVEL3_CACHE_ASSOC' |
| Inquire about the associativity of the Level 3 cache. |
| |
| `_SC_LEVEL3_CACHE_LINESIZE' |
| Inquire about the line length of the Level 3 cache. |
| |
| `_SC_LEVEL4_CACHE_SIZE' |
| Inquire about the size of the Level 4 cache. |
| |
| `_SC_LEVEL4_CACHE_ASSOC' |
| Inquire about the associativity of the Level 4 cache. |
| |
| `_SC_LEVEL4_CACHE_LINESIZE' |
| Inquire about the line length of the Level 4 cache. |
| |
| `_SC_XOPEN_VERSION' |
| Inquire about the parameter corresponding to `_XOPEN_VERSION'. |
| |
| `_SC_XOPEN_XCU_VERSION' |
| Inquire about the parameter corresponding to `_XOPEN_XCU_VERSION'. |
| |
| `_SC_XOPEN_UNIX' |
| Inquire about the parameter corresponding to `_XOPEN_UNIX'. |
| |
| `_SC_XOPEN_REALTIME' |
| Inquire about the parameter corresponding to `_XOPEN_REALTIME'. |
| |
| `_SC_XOPEN_REALTIME_THREADS' |
| Inquire about the parameter corresponding to |
| `_XOPEN_REALTIME_THREADS'. |
| |
| `_SC_XOPEN_LEGACY' |
| Inquire about the parameter corresponding to `_XOPEN_LEGACY'. |
| |
| `_SC_XOPEN_CRYPT' |
| Inquire about the parameter corresponding to `_XOPEN_CRYPT'. The |
| GNU C Library no longer implements the `_XOPEN_CRYPT' extensions, |
| so `sysconf (_SC_XOPEN_CRYPT)' always returns `-1'. |
| |
| `_SC_XOPEN_ENH_I18N' |
| Inquire about the parameter corresponding to `_XOPEN_ENH_I18N'. |
| |
| `_SC_XOPEN_SHM' |
| Inquire about the parameter corresponding to `_XOPEN_SHM'. |
| |
| `_SC_XOPEN_XPG2' |
| Inquire about the parameter corresponding to `_XOPEN_XPG2'. |
| |
| `_SC_XOPEN_XPG3' |
| Inquire about the parameter corresponding to `_XOPEN_XPG3'. |
| |
| `_SC_XOPEN_XPG4' |
| Inquire about the parameter corresponding to `_XOPEN_XPG4'. |
| |
| `_SC_CHAR_BIT' |
| Inquire about the number of bits in a variable of type `char'. |
| |
| `_SC_CHAR_MAX' |
| Inquire about the maximum value which can be stored in a variable |
| of type `char'. |
| |
| `_SC_CHAR_MIN' |
| Inquire about the minimum value which can be stored in a variable |
| of type `char'. |
| |
| `_SC_INT_MAX' |
| Inquire about the maximum value which can be stored in a variable |
| of type `int'. |
| |
| `_SC_INT_MIN' |
| Inquire about the minimum value which can be stored in a variable |
| of type `int'. |
| |
| `_SC_LONG_BIT' |
| Inquire about the number of bits in a variable of type `long int'. |
| |
| `_SC_WORD_BIT' |
| Inquire about the number of bits in a variable of a register word. |
| |
| `_SC_MB_LEN_MAX' |
| Inquire about the maximum length of a multi-byte representation of |
| a wide character value. |
| |
| `_SC_NZERO' |
| Inquire about the value used to internally represent the zero |
| priority level for the process execution. |
| |
| `_SC_SSIZE_MAX' |
| Inquire about the maximum value which can be stored in a variable |
| of type `ssize_t'. |
| |
| `_SC_SCHAR_MAX' |
| Inquire about the maximum value which can be stored in a variable |
| of type `signed char'. |
| |
| `_SC_SCHAR_MIN' |
| Inquire about the minimum value which can be stored in a variable |
| of type `signed char'. |
| |
| `_SC_SHRT_MAX' |
| Inquire about the maximum value which can be stored in a variable |
| of type `short int'. |
| |
| `_SC_SHRT_MIN' |
| Inquire about the minimum value which can be stored in a variable |
| of type `short int'. |
| |
| `_SC_UCHAR_MAX' |
| Inquire about the maximum value which can be stored in a variable |
| of type `unsigned char'. |
| |
| `_SC_UINT_MAX' |
| Inquire about the maximum value which can be stored in a variable |
| of type `unsigned int'. |
| |
| `_SC_ULONG_MAX' |
| Inquire about the maximum value which can be stored in a variable |
| of type `unsigned long int'. |
| |
| `_SC_USHRT_MAX' |
| Inquire about the maximum value which can be stored in a variable |
| of type `unsigned short int'. |
| |
| `_SC_NL_ARGMAX' |
| Inquire about the parameter corresponding to `NL_ARGMAX'. |
| |
| `_SC_NL_LANGMAX' |
| Inquire about the parameter corresponding to `NL_LANGMAX'. |
| |
| `_SC_NL_MSGMAX' |
| Inquire about the parameter corresponding to `NL_MSGMAX'. |
| |
| `_SC_NL_NMAX' |
| Inquire about the parameter corresponding to `NL_NMAX'. |
| |
| `_SC_NL_SETMAX' |
| Inquire about the parameter corresponding to `NL_SETMAX'. |
| |
| `_SC_NL_TEXTMAX' |
| Inquire about the parameter corresponding to `NL_TEXTMAX'. |
| |
| |
| File: libc.info, Node: Examples of Sysconf, Prev: Constants for Sysconf, Up: Sysconf |
| |
| 32.4.3 Examples of `sysconf' |
| ---------------------------- |
| |
| We recommend that you first test for a macro definition for the |
| parameter you are interested in, and call `sysconf' only if the macro |
| is not defined. For example, here is how to test whether job control |
| is supported: |
| |
| int |
| have_job_control (void) |
| { |
| #ifdef _POSIX_JOB_CONTROL |
| return 1; |
| #else |
| int value = sysconf (_SC_JOB_CONTROL); |
| if (value < 0) |
| /* If the system is that badly wedged, |
| there's no use trying to go on. */ |
| fatal (strerror (errno)); |
| return value; |
| #endif |
| } |
| |
| Here is how to get the value of a numeric limit: |
| |
| int |
| get_child_max () |
| { |
| #ifdef CHILD_MAX |
| return CHILD_MAX; |
| #else |
| int value = sysconf (_SC_CHILD_MAX); |
| if (value < 0) |
| fatal (strerror (errno)); |
| return value; |
| #endif |
| } |
| |
| |
| File: libc.info, Node: Minimums, Next: Limits for Files, Prev: Sysconf, Up: System Configuration |
| |
| 32.5 Minimum Values for General Capacity Limits |
| =============================================== |
| |
| Here are the names for the POSIX minimum upper bounds for the system |
| limit parameters. The significance of these values is that you can |
| safely push to these limits without checking whether the particular |
| system you are using can go that far. |
| |
| `_POSIX_AIO_LISTIO_MAX' |
| The most restrictive limit permitted by POSIX for the maximum |
| number of I/O operations that can be specified in a list I/O call. |
| The value of this constant is `2'; thus you can add up to two new |
| entries of the list of outstanding operations. |
| |
| `_POSIX_AIO_MAX' |
| The most restrictive limit permitted by POSIX for the maximum |
| number of outstanding asynchronous I/O operations. The value of |
| this constant is `1'. So you cannot expect that you can issue |
| more than one operation and immediately continue with the normal |
| work, receiving the notifications asynchronously. |
| |
| `_POSIX_ARG_MAX' |
| The value of this macro is the most restrictive limit permitted by |
| POSIX for the maximum combined length of the ARGV and ENVIRON |
| arguments that can be passed to the `exec' functions. Its value |
| is `4096'. |
| |
| `_POSIX_CHILD_MAX' |
| The value of this macro is the most restrictive limit permitted by |
| POSIX for the maximum number of simultaneous processes per real |
| user ID. Its value is `6'. |
| |
| `_POSIX_NGROUPS_MAX' |
| The value of this macro is the most restrictive limit permitted by |
| POSIX for the maximum number of supplementary group IDs per |
| process. Its value is `0'. |
| |
| `_POSIX_OPEN_MAX' |
| The value of this macro is the most restrictive limit permitted by |
| POSIX for the maximum number of files that a single process can |
| have open simultaneously. Its value is `16'. |
| |
| `_POSIX_SSIZE_MAX' |
| The value of this macro is the most restrictive limit permitted by |
| POSIX for the maximum value that can be stored in an object of type |
| `ssize_t'. Its value is `32767'. |
| |
| `_POSIX_STREAM_MAX' |
| The value of this macro is the most restrictive limit permitted by |
| POSIX for the maximum number of streams that a single process can |
| have open simultaneously. Its value is `8'. |
| |
| `_POSIX_TZNAME_MAX' |
| The value of this macro is the most restrictive limit permitted by |
| POSIX for the maximum length of a time zone name. Its value is |
| `3'. |
| |
| `_POSIX2_RE_DUP_MAX' |
| The value of this macro is the most restrictive limit permitted by |
| POSIX for the numbers used in the `\{MIN,MAX\}' construct in a |
| regular expression. Its value is `255'. |
| |
| |
| File: libc.info, Node: Limits for Files, Next: Options for Files, Prev: Minimums, Up: System Configuration |
| |
| 32.6 Limits on File System Capacity |
| =================================== |
| |
| The POSIX.1 standard specifies a number of parameters that describe the |
| limitations of the file system. It's possible for the system to have a |
| fixed, uniform limit for a parameter, but this isn't the usual case. On |
| most systems, it's possible for different file systems (and, for some |
| parameters, even different files) to have different maximum limits. For |
| example, this is very likely if you use NFS to mount some of the file |
| systems from other machines. |
| |
| Each of the following macros is defined in `limits.h' only if the |
| system has a fixed, uniform limit for the parameter in question. If the |
| system allows different file systems or files to have different limits, |
| then the macro is undefined; use `pathconf' or `fpathconf' to find out |
| the limit that applies to a particular file. *Note Pathconf::. |
| |
| Each parameter also has another macro, with a name starting with |
| `_POSIX', which gives the lowest value that the limit is allowed to |
| have on _any_ POSIX system. *Note File Minimums::. |
| |
| -- Macro: int LINK_MAX |
| The uniform system limit (if any) for the number of names for a |
| given file. *Note Hard Links::. |
| |
| -- Macro: int MAX_CANON |
| The uniform system limit (if any) for the amount of text in a line |
| of input when input editing is enabled. *Note Canonical or Not::. |
| |
| -- Macro: int MAX_INPUT |
| The uniform system limit (if any) for the total number of |
| characters typed ahead as input. *Note I/O Queues::. |
| |
| -- Macro: int NAME_MAX |
| The uniform system limit (if any) for the length of a file name |
| component, not including the terminating null character. |
| |
| *Portability Note:* On some systems, the GNU C Library defines |
| `NAME_MAX', but does not actually enforce this limit. |
| |
| -- Macro: int PATH_MAX |
| The uniform system limit (if any) for the length of an entire file |
| name (that is, the argument given to system calls such as `open'), |
| including the terminating null character. |
| |
| *Portability Note:* The GNU C Library does not enforce this limit |
| even if `PATH_MAX' is defined. |
| |
| -- Macro: int PIPE_BUF |
| The uniform system limit (if any) for the number of bytes that can |
| be written atomically to a pipe. If multiple processes are |
| writing to the same pipe simultaneously, output from different |
| processes might be interleaved in chunks of this size. *Note |
| Pipes and FIFOs::. |
| |
| These are alternative macro names for some of the same information. |
| |
| -- Macro: int MAXNAMLEN |
| This is the BSD name for `NAME_MAX'. It is defined in `dirent.h'. |
| |
| -- Macro: int FILENAME_MAX |
| The value of this macro is an integer constant expression that |
| represents the maximum length of a file name string. It is |
| defined in `stdio.h'. |
| |
| Unlike `PATH_MAX', this macro is defined even if there is no actual |
| limit imposed. In such a case, its value is typically a very large |
| number. *This is always the case on GNU/Hurd systems.* |
| |
| *Usage Note:* Don't use `FILENAME_MAX' as the size of an array in |
| which to store a file name! You can't possibly make an array that |
| big! Use dynamic allocation (*note Memory Allocation::) instead. |
| |
| |
| File: libc.info, Node: Options for Files, Next: File Minimums, Prev: Limits for Files, Up: System Configuration |
| |
| 32.7 Optional Features in File Support |
| ====================================== |
| |
| POSIX defines certain system-specific options in the system calls for |
| operating on files. Some systems support these options and others do |
| not. Since these options are provided in the kernel, not in the |
| library, simply using the GNU C Library does not guarantee that any of |
| these features is supported; it depends on the system you are using. |
| They can also vary between file systems on a single machine. |
| |
| This section describes the macros you can test to determine whether a |
| particular option is supported on your machine. If a given macro is |
| defined in `unistd.h', then its value says whether the corresponding |
| feature is supported. (A value of `-1' indicates no; any other value |
| indicates yes.) If the macro is undefined, it means particular files |
| may or may not support the feature. |
| |
| Since all the machines that support the GNU C Library also support |
| NFS, one can never make a general statement about whether all file |
| systems support the `_POSIX_CHOWN_RESTRICTED' and `_POSIX_NO_TRUNC' |
| features. So these names are never defined as macros in the GNU C |
| Library. |
| |
| -- Macro: int _POSIX_CHOWN_RESTRICTED |
| If this option is in effect, the `chown' function is restricted so |
| that the only changes permitted to nonprivileged processes is to |
| change the group owner of a file to either be the effective group |
| ID of the process, or one of its supplementary group IDs. *Note |
| File Owner::. |
| |
| -- Macro: int _POSIX_NO_TRUNC |
| If this option is in effect, file name components longer than |
| `NAME_MAX' generate an `ENAMETOOLONG' error. Otherwise, file name |
| components that are too long are silently truncated. |
| |
| -- Macro: unsigned char _POSIX_VDISABLE |
| This option is only meaningful for files that are terminal devices. |
| If it is enabled, then handling for special control characters can |
| be disabled individually. *Note Special Characters::. |
| |
| If one of these macros is undefined, that means that the option |
| might be in effect for some files and not for others. To inquire about |
| a particular file, call `pathconf' or `fpathconf'. *Note Pathconf::. |
| |
| |
| File: libc.info, Node: File Minimums, Next: Pathconf, Prev: Options for Files, Up: System Configuration |
| |
| 32.8 Minimum Values for File System Limits |
| ========================================== |
| |
| Here are the names for the POSIX minimum upper bounds for some of the |
| above parameters. The significance of these values is that you can |
| safely push to these limits without checking whether the particular |
| system you are using can go that far. In most cases GNU systems do not |
| have these strict limitations. The actual limit should be requested if |
| necessary. |
| |
| `_POSIX_LINK_MAX' |
| The most restrictive limit permitted by POSIX for the maximum |
| value of a file's link count. The value of this constant is `8'; |
| thus, you can always make up to eight names for a file without |
| running into a system limit. |
| |
| `_POSIX_MAX_CANON' |
| The most restrictive limit permitted by POSIX for the maximum |
| number of bytes in a canonical input line from a terminal device. |
| The value of this constant is `255'. |
| |
| `_POSIX_MAX_INPUT' |
| The most restrictive limit permitted by POSIX for the maximum |
| number of bytes in a terminal device input queue (or typeahead |
| buffer). *Note Input Modes::. The value of this constant is |
| `255'. |
| |
| `_POSIX_NAME_MAX' |
| The most restrictive limit permitted by POSIX for the maximum |
| number of bytes in a file name component. The value of this |
| constant is `14'. |
| |
| `_POSIX_PATH_MAX' |
| The most restrictive limit permitted by POSIX for the maximum |
| number of bytes in a file name. The value of this constant is |
| `256'. |
| |
| `_POSIX_PIPE_BUF' |
| The most restrictive limit permitted by POSIX for the maximum |
| number of bytes that can be written atomically to a pipe. The |
| value of this constant is `512'. |
| |
| `SYMLINK_MAX' |
| Maximum number of bytes in a symbolic link. |
| |
| `POSIX_REC_INCR_XFER_SIZE' |
| Recommended increment for file transfer sizes between the |
| `POSIX_REC_MIN_XFER_SIZE' and `POSIX_REC_MAX_XFER_SIZE' values. |
| |
| `POSIX_REC_MAX_XFER_SIZE' |
| Maximum recommended file transfer size. |
| |
| `POSIX_REC_MIN_XFER_SIZE' |
| Minimum recommended file transfer size. |
| |
| `POSIX_REC_XFER_ALIGN' |
| Recommended file transfer buffer alignment. |
| |
| |
| File: libc.info, Node: Pathconf, Next: Utility Limits, Prev: File Minimums, Up: System Configuration |
| |
| 32.9 Using `pathconf' |
| ===================== |
| |
| When your machine allows different files to have different values for a |
| file system parameter, you can use the functions in this section to find |
| out the value that applies to any particular file. |
| |
| These functions and the associated constants for the PARAMETER |
| argument are declared in the header file `unistd.h'. |
| |
| -- Function: long int pathconf (const char *FILENAME, int PARAMETER) |
| Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock fd |
| mem | *Note POSIX Safety Concepts::. |
| |
| This function is used to inquire about the limits that apply to |
| the file named FILENAME. |
| |
| The PARAMETER argument should be one of the `_PC_' constants |
| listed below. |
| |
| The normal return value from `pathconf' is the value you requested. |
| A value of `-1' is returned both if the implementation does not |
| impose a limit, and in case of an error. In the former case, |
| `errno' is not set, while in the latter case, `errno' is set to |
| indicate the cause of the problem. So the only way to use this |
| function robustly is to store `0' into `errno' just before calling |
| it. |
| |
| Besides the usual file name errors (*note File Name Errors::), the |
| following error condition is defined for this function: |
| |
| `EINVAL' |
| The value of PARAMETER is invalid, or the implementation |
| doesn't support the PARAMETER for the specific file. |
| |
| -- Function: long int fpathconf (int FILEDES, int PARAMETER) |
| Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock fd |
| mem | *Note POSIX Safety Concepts::. |
| |
| This is just like `pathconf' except that an open file descriptor |
| is used to specify the file for which information is requested, |
| instead of a file name. |
| |
| The following `errno' error conditions are defined for this |
| function: |
| |
| `EBADF' |
| The FILEDES argument is not a valid file descriptor. |
| |
| `EINVAL' |
| The value of PARAMETER is invalid, or the implementation |
| doesn't support the PARAMETER for the specific file. |
| |
| Here are the symbolic constants that you can use as the PARAMETER |
| argument to `pathconf' and `fpathconf'. The values are all integer |
| constants. |
| |
| `_PC_LINK_MAX' |
| Inquire about the value of `LINK_MAX'. |
| |
| `_PC_MAX_CANON' |
| Inquire about the value of `MAX_CANON'. |
| |
| `_PC_MAX_INPUT' |
| Inquire about the value of `MAX_INPUT'. |
| |
| `_PC_NAME_MAX' |
| Inquire about the value of `NAME_MAX'. |
| |
| `_PC_PATH_MAX' |
| Inquire about the value of `PATH_MAX'. |
| |
| `_PC_PIPE_BUF' |
| Inquire about the value of `PIPE_BUF'. |
| |
| `_PC_CHOWN_RESTRICTED' |
| Inquire about the value of `_POSIX_CHOWN_RESTRICTED'. |
| |
| `_PC_NO_TRUNC' |
| Inquire about the value of `_POSIX_NO_TRUNC'. |
| |
| `_PC_VDISABLE' |
| Inquire about the value of `_POSIX_VDISABLE'. |
| |
| `_PC_SYNC_IO' |
| Inquire about the value of `_POSIX_SYNC_IO'. |
| |
| `_PC_ASYNC_IO' |
| Inquire about the value of `_POSIX_ASYNC_IO'. |
| |
| `_PC_PRIO_IO' |
| Inquire about the value of `_POSIX_PRIO_IO'. |
| |
| `_PC_FILESIZEBITS' |
| Inquire about the availability of large files on the filesystem. |
| |
| `_PC_REC_INCR_XFER_SIZE' |
| Inquire about the value of `POSIX_REC_INCR_XFER_SIZE'. |
| |
| `_PC_REC_MAX_XFER_SIZE' |
| Inquire about the value of `POSIX_REC_MAX_XFER_SIZE'. |
| |
| `_PC_REC_MIN_XFER_SIZE' |
| Inquire about the value of `POSIX_REC_MIN_XFER_SIZE'. |
| |
| `_PC_REC_XFER_ALIGN' |
| Inquire about the value of `POSIX_REC_XFER_ALIGN'. |
| |
| *Portability Note:* On some systems, the GNU C Library does not |
| enforce `_PC_NAME_MAX' or `_PC_PATH_MAX' limits. |
| |
| |
| File: libc.info, Node: Utility Limits, Next: Utility Minimums, Prev: Pathconf, Up: System Configuration |
| |
| 32.10 Utility Program Capacity Limits |
| ===================================== |
| |
| The POSIX.2 standard specifies certain system limits that you can access |
| through `sysconf' that apply to utility behavior rather than the |
| behavior of the library or the operating system. |
| |
| The GNU C Library defines macros for these limits, and `sysconf' |
| returns values for them if you ask; but these values convey no |
| meaningful information. They are simply the smallest values that |
| POSIX.2 permits. |
| |
| -- Macro: int BC_BASE_MAX |
| The largest value of `obase' that the `bc' utility is guaranteed |
| to support. |
| |
| -- Macro: int BC_DIM_MAX |
| The largest number of elements in one array that the `bc' utility |
| is guaranteed to support. |
| |
| -- Macro: int BC_SCALE_MAX |
| The largest value of `scale' that the `bc' utility is guaranteed |
| to support. |
| |
| -- Macro: int BC_STRING_MAX |
| The largest number of characters in one string constant that the |
| `bc' utility is guaranteed to support. |
| |
| -- Macro: int COLL_WEIGHTS_MAX |
| The largest number of weights that can necessarily be used in |
| defining the collating sequence for a locale. |
| |
| -- Macro: int EXPR_NEST_MAX |
| The maximum number of expressions that can be nested within |
| parentheses by the `expr' utility. |
| |
| -- Macro: int LINE_MAX |
| The largest text line that the text-oriented POSIX.2 utilities can |
| support. (If you are using the GNU versions of these utilities, |
| then there is no actual limit except that imposed by the available |
| virtual memory, but there is no way that the library can tell you |
| this.) |
| |
| -- Macro: int EQUIV_CLASS_MAX |
| The maximum number of weights that can be assigned to an entry of |
| the `LC_COLLATE' category `order' keyword in a locale definition. |
| The GNU C Library does not presently support locale definitions. |
| |
| |
| File: libc.info, Node: Utility Minimums, Next: String Parameters, Prev: Utility Limits, Up: System Configuration |
| |
| 32.11 Minimum Values for Utility Limits |
| ======================================= |
| |
| `_POSIX2_BC_BASE_MAX' |
| The most restrictive limit permitted by POSIX.2 for the maximum |
| value of `obase' in the `bc' utility. Its value is `99'. |
| |
| `_POSIX2_BC_DIM_MAX' |
| The most restrictive limit permitted by POSIX.2 for the maximum |
| size of an array in the `bc' utility. Its value is `2048'. |
| |
| `_POSIX2_BC_SCALE_MAX' |
| The most restrictive limit permitted by POSIX.2 for the maximum |
| value of `scale' in the `bc' utility. Its value is `99'. |
| |
| `_POSIX2_BC_STRING_MAX' |
| The most restrictive limit permitted by POSIX.2 for the maximum |
| size of a string constant in the `bc' utility. Its value is |
| `1000'. |
| |
| `_POSIX2_COLL_WEIGHTS_MAX' |
| The most restrictive limit permitted by POSIX.2 for the maximum |
| number of weights that can necessarily be used in defining the |
| collating sequence for a locale. Its value is `2'. |
| |
| `_POSIX2_EXPR_NEST_MAX' |
| The most restrictive limit permitted by POSIX.2 for the maximum |
| number of expressions nested within parenthesis when using the |
| `expr' utility. Its value is `32'. |
| |
| `_POSIX2_LINE_MAX' |
| The most restrictive limit permitted by POSIX.2 for the maximum |
| size of a text line that the text utilities can handle. Its value |
| is `2048'. |
| |
| `_POSIX2_EQUIV_CLASS_MAX' |
| The most restrictive limit permitted by POSIX.2 for the maximum |
| number of weights that can be assigned to an entry of the |
| `LC_COLLATE' category `order' keyword in a locale definition. Its |
| value is `2'. The GNU C Library does not presently support locale |
| definitions. |
| |
| |
| File: libc.info, Node: String Parameters, Prev: Utility Minimums, Up: System Configuration |
| |
| 32.12 String-Valued Parameters |
| ============================== |
| |
| POSIX.2 defines a way to get string-valued parameters from the operating |
| system with the function `confstr': |
| |
| -- Function: size_t confstr (int PARAMETER, char *BUF, size_t LEN) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function reads the value of a string-valued system parameter, |
| storing the string into LEN bytes of memory space starting at BUF. |
| The PARAMETER argument should be one of the `_CS_' symbols listed |
| below. |
| |
| The normal return value from `confstr' is the length of the string |
| value that you asked for. If you supply a null pointer for BUF, |
| then `confstr' does not try to store the string; it just returns |
| its length. A value of `0' indicates an error. |
| |
| If the string you asked for is too long for the buffer (that is, |
| longer than `LEN - 1'), then `confstr' stores just that much |
| (leaving room for the terminating null character). You can tell |
| that this has happened because `confstr' returns a value greater |
| than or equal to LEN. |
| |
| The following `errno' error conditions are defined for this |
| function: |
| |
| `EINVAL' |
| The value of the PARAMETER is invalid. |
| |
| Currently there is just one parameter you can read with `confstr': |
| |
| `_CS_PATH' |
| This parameter's value is the recommended default path for |
| searching for executable files. This is the path that a user has |
| by default just after logging in. |
| |
| `_CS_LFS_CFLAGS' |
| The returned string specifies which additional flags must be given |
| to the C compiler if a source is compiled using the |
| `_LARGEFILE_SOURCE' feature select macro; *note Feature Test |
| Macros::. |
| |
| `_CS_LFS_LDFLAGS' |
| The returned string specifies which additional flags must be given |
| to the linker if a source is compiled using the |
| `_LARGEFILE_SOURCE' feature select macro; *note Feature Test |
| Macros::. |
| |
| `_CS_LFS_LIBS' |
| The returned string specifies which additional libraries must be |
| linked to the application if a source is compiled using the |
| `_LARGEFILE_SOURCE' feature select macro; *note Feature Test |
| Macros::. |
| |
| `_CS_LFS_LINTFLAGS' |
| The returned string specifies which additional flags must be given |
| to the lint tool if a source is compiled using the |
| `_LARGEFILE_SOURCE' feature select macro; *note Feature Test |
| Macros::. |
| |
| `_CS_LFS64_CFLAGS' |
| The returned string specifies which additional flags must be given |
| to the C compiler if a source is compiled using the |
| `_LARGEFILE64_SOURCE' feature select macro; *note Feature Test |
| Macros::. |
| |
| `_CS_LFS64_LDFLAGS' |
| The returned string specifies which additional flags must be given |
| to the linker if a source is compiled using the |
| `_LARGEFILE64_SOURCE' feature select macro; *note Feature Test |
| Macros::. |
| |
| `_CS_LFS64_LIBS' |
| The returned string specifies which additional libraries must be |
| linked to the application if a source is compiled using the |
| `_LARGEFILE64_SOURCE' feature select macro; *note Feature Test |
| Macros::. |
| |
| `_CS_LFS64_LINTFLAGS' |
| The returned string specifies which additional flags must be given |
| to the lint tool if a source is compiled using the |
| `_LARGEFILE64_SOURCE' feature select macro; *note Feature Test |
| Macros::. |
| |
| The way to use `confstr' without any arbitrary limit on string size |
| is to call it twice: first call it to get the length, allocate the |
| buffer accordingly, and then call `confstr' again to fill the buffer, |
| like this: |
| |
| char * |
| get_default_path (void) |
| { |
| size_t len = confstr (_CS_PATH, NULL, 0); |
| char *buffer = (char *) xmalloc (len); |
| |
| if (confstr (_CS_PATH, buf, len + 1) == 0) |
| { |
| free (buffer); |
| return NULL; |
| } |
| |
| return buffer; |
| } |
| |
| |
| File: libc.info, Node: Cryptographic Functions, Next: Debugging Support, Prev: System Configuration, Up: Top |
| |
| 33 Cryptographic Functions |
| ************************** |
| |
| The GNU C Library includes only a few special-purpose cryptographic |
| functions: one-way hash functions for passphrase storage, and access to |
| a cryptographic randomness source, if one is provided by the operating |
| system. Programs that need general-purpose cryptography should use a |
| dedicated cryptography library, such as libgcrypt. |
| |
| Many countries place legal restrictions on the import, export, |
| possession, or use of cryptographic software. We deplore these |
| restrictions, but we must still warn you that the GNU C Library may be |
| subject to them, even if you do not use the functions in this chapter |
| yourself. The restrictions vary from place to place and are changed |
| often, so we cannot give any more specific advice than this warning. |
| |
| * Menu: |
| |
| * Passphrase Storage:: One-way hashing for passphrases. |
| * Unpredictable Bytes:: Randomness for cryptographic purposes. |
| |
| |
| File: libc.info, Node: Passphrase Storage, Next: Unpredictable Bytes, Up: Cryptographic Functions |
| |
| 33.1 Passphrase Storage |
| ======================= |
| |
| Sometimes it is necessary to be sure that a user is authorized to use |
| some service a machine provides--for instance, to log in as a |
| particular user id (*note Users and Groups::). One traditional way of |
| doing this is for each user to choose a secret "passphrase"; then, the |
| system can ask someone claiming to be a user what the user's passphrase |
| is, and if the person gives the correct passphrase then the system can |
| grant the appropriate privileges. (Traditionally, these were called |
| "passwords," but nowadays a single word is too easy to guess.) |
| |
| Programs that handle passphrases must take special care not to reveal |
| them to anyone, no matter what. It is not enough to keep them in a |
| file that is only accessible with special privileges. The file might |
| be "leaked" via a bug or misconfiguration, and system administrators |
| shouldn't learn everyone's passphrase even if they have to edit that |
| file for some reason. To avoid this, passphrases should also be |
| converted into "one-way hashes", using a "one-way function", before |
| they are stored. |
| |
| A one-way function is easy to compute, but there is no known way to |
| compute its inverse. This means the system can easily check |
| passphrases, by hashing them and comparing the result with the stored |
| hash. But an attacker who discovers someone's passphrase hash can only |
| discover the passphrase it corresponds to by guessing and checking. |
| The one-way functions are designed to make this process impractically |
| slow, for all but the most obvious guesses. (Do not use a word from |
| the dictionary as your passphrase.) |
| |
| The GNU C Library provides an interface to four one-way functions, |
| based on the SHA-2-512, SHA-2-256, MD5, and DES cryptographic |
| primitives. New passphrases should be hashed with either of the |
| SHA-based functions. The others are too weak for newly set |
| passphrases, but we continue to support them for verifying old |
| passphrases. The DES-based hash is especially weak, because it ignores |
| all but the first eight characters of its input. |
| |
| -- Function: char * crypt (const char *PHRASE, const char *SALT) |
| Preliminary: | MT-Unsafe race:crypt | AS-Unsafe corrupt lock heap |
| dlopen | AC-Unsafe lock mem | *Note POSIX Safety Concepts::. |
| |
| The function `crypt' converts a passphrase string, PHRASE, into a |
| one-way hash suitable for storage in the user database. The |
| string that it returns will consist entirely of printable ASCII |
| characters. It will not contain whitespace, nor any of the |
| characters `:', `;', `*', `!', or `\'. |
| |
| The SALT parameter controls which one-way function is used, and it |
| also ensures that the output of the one-way function is different |
| for every user, even if they have the same passphrase. This makes |
| it harder to guess passphrases from a large user database. |
| Without salt, the attacker could make a guess, run `crypt' on it |
| once, and compare the result with all the hashes. Salt forces the |
| attacker to make separate calls to `crypt' for each user. |
| |
| To verify a passphrase, pass the previously hashed passphrase as |
| the SALT. To hash a new passphrase for storage, set SALT to a |
| string consisting of a prefix plus a sequence of randomly chosen |
| characters, according to this table: |
| |
| One-way Prefix Random sequence |
| function |
| ------------------------------------------- |
| SHA-2-512 `$6$' 16 characters |
| SHA-2-256 `$5$' 16 characters |
| MD5 `$1$' 8 characters |
| DES `' 2 characters |
| |
| In all cases, the random characters should be chosen from the |
| alphabet `./0-9A-Za-z'. |
| |
| With all of the hash functions _except_ DES, PHRASE can be |
| arbitrarily long, and all eight bits of each byte are significant. |
| With DES, only the first eight characters of PHRASE affect the |
| output, and the eighth bit of each byte is also ignored. |
| |
| `crypt' can fail. Some implementations return `NULL' on failure, |
| and others return an _invalid_ hashed passphrase, which will begin |
| with a `*' and will not be the same as SALT. In either case, |
| `errno' will be set to indicate the problem. Some of the possible |
| error codes are: |
| |
| `EINVAL' |
| SALT is invalid; neither a previously hashed passphrase, nor a |
| well-formed new salt for any of the supported hash functions. |
| |
| `EPERM' |
| The system configuration forbids use of the hash function |
| selected by SALT. |
| |
| `ENOMEM' |
| Failed to allocate internal scratch storage. |
| |
| `ENOSYS' |
| `EOPNOTSUPP' |
| Hashing passphrases is not supported at all, or the hash |
| function selected by SALT is not supported. The GNU C |
| Library does not use these error codes, but they may be |
| encountered on other operating systems. |
| |
| `crypt' uses static storage for both internal scratchwork and the |
| string it returns. It is not safe to call `crypt' from multiple |
| threads simultaneously, and the string it returns will be |
| overwritten by any subsequent call to `crypt'. |
| |
| `crypt' is specified in the X/Open Portability Guide and is |
| present on nearly all historical Unix systems. However, the XPG |
| does not specify any one-way functions. |
| |
| `crypt' is declared in `unistd.h'. The GNU C Library also |
| declares this function in `crypt.h'. |
| |
| -- Function: char * crypt_r (const char *PHRASE, const char *SALT, |
| struct crypt_data *DATA) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt lock heap dlopen | |
| AC-Unsafe lock mem | *Note POSIX Safety Concepts::. |
| |
| The function `crypt_r' is a thread-safe version of `crypt'. |
| Instead of static storage, it uses the memory pointed to by its |
| DATA argument for both scratchwork and the string it returns. It |
| can safely be used from multiple threads, as long as different |
| DATA objects are used in each thread. The string it returns will |
| still be overwritten by another call with the same DATA. |
| |
| DATA must point to a `struct crypt_data' object allocated by the |
| caller. All of the fields of `struct crypt_data' are private, but |
| before one of these objects is used for the first time, it must be |
| initialized to all zeroes, using `memset' or similar. After that, |
| it can be reused for many calls to `crypt_r' without erasing it |
| again. `struct crypt_data' is very large, so it is best to |
| allocate it with `malloc' rather than as a local variable. *Note |
| Memory Allocation::. |
| |
| `crypt_r' is a GNU extension. It is declared in `crypt.h', as is |
| `struct crypt_data'. |
| |
| The following program shows how to use `crypt' the first time a |
| passphrase is entered. It uses `getentropy' to make the salt as |
| unpredictable as possible; *note Unpredictable Bytes::. |
| |
| |
| #include <stdio.h> |
| #include <unistd.h> |
| #include <crypt.h> |
| |
| int |
| main(void) |
| { |
| unsigned char ubytes[16]; |
| char salt[20]; |
| const char *const saltchars = |
| "./0123456789ABCDEFGHIJKLMNOPQRST" |
| "UVWXYZabcdefghijklmnopqrstuvwxyz"; |
| char *hash; |
| int i; |
| |
| /* Retrieve 16 unpredictable bytes from the operating system. */ |
| if (getentropy (ubytes, sizeof ubytes)) |
| { |
| perror ("getentropy"); |
| return 1; |
| } |
| |
| /* Use them to fill in the salt string. */ |
| salt[0] = '$'; |
| salt[1] = '5'; /* SHA-256 */ |
| salt[2] = '$'; |
| for (i = 0; i < 16; i++) |
| salt[3+i] = saltchars[ubytes[i] & 0x3f]; |
| salt[3+i] = '\0'; |
| |
| /* Read in the user's passphrase and hash it. */ |
| hash = crypt (getpass ("Enter new passphrase: "), salt); |
| if (!hash || hash[0] == '*') |
| { |
| perror ("crypt"); |
| return 1; |
| } |
| |
| /* Print the results. */ |
| puts (hash); |
| return 0; |
| } |
| |
| The next program demonstrates how to verify a passphrase. It checks |
| a hash hardcoded into the program, because looking up real users' hashed |
| passphrases may require special privileges (*note User Database::). It |
| also shows that different one-way functions produce different hashes |
| for the same passphrase. |
| |
| |
| #include <stdio.h> |
| #include <string.h> |
| #include <unistd.h> |
| #include <crypt.h> |
| |
| /* `GNU's Not Unix' hashed using SHA-256, MD5, and DES. */ |
| static const char hash_sha[] = |
| "$5$DQ2z5NHf1jNJnChB$kV3ZTR0aUaosujPhLzR84Llo3BsspNSe4/tsp7VoEn6"; |
| static const char hash_md5[] = "$1$A3TxDv41$rtXVTUXl2LkeSV0UU5xxs1"; |
| static const char hash_des[] = "FgkTuF98w5DaI"; |
| |
| int |
| main(void) |
| { |
| char *phrase; |
| int status = 0; |
| |
| /* Prompt for a passphrase. */ |
| phrase = getpass ("Enter passphrase: "); |
| |
| /* Compare against the stored hashes. Any input that begins with |
| `GNU's No' will match the DES hash, but the other two will |
| only match `GNU's Not Unix'. */ |
| |
| if (strcmp (crypt (phrase, hash_sha), hash_sha)) |
| { |
| puts ("SHA: not ok"); |
| status = 1; |
| } |
| else |
| puts ("SHA: ok"); |
| |
| if (strcmp (crypt (phrase, hash_md5), hash_md5)) |
| { |
| puts ("MD5: not ok"); |
| status = 1; |
| } |
| else |
| puts ("MD5: ok"); |
| |
| if (strcmp (crypt (phrase, hash_des), hash_des)) |
| { |
| puts ("DES: not ok"); |
| status = 1; |
| } |
| else |
| puts ("DES: ok"); |
| |
| return status; |
| } |
| |
| |
| File: libc.info, Node: Unpredictable Bytes, Prev: Passphrase Storage, Up: Cryptographic Functions |
| |
| 33.2 Generating Unpredictable Bytes |
| =================================== |
| |
| Cryptographic applications often need some random data that will be as |
| difficult as possible for a hostile eavesdropper to guess. For |
| instance, encryption keys should be chosen at random, and the "salt" |
| strings used by `crypt' (*note Passphrase Storage::) should also be |
| chosen at random. |
| |
| Some pseudo-random number generators do not provide |
| unpredictable-enough output for cryptographic applications; *note |
| Pseudo-Random Numbers::. Such applications need to use a |
| "cryptographic random number generator" (CRNG), also sometimes called a |
| "cryptographically strong pseudo-random number generator" (CSPRNG) or |
| "deterministic random bit generator" (DRBG). |
| |
| Currently, the GNU C Library does not provide a cryptographic random |
| number generator, but it does provide functions that read random data |
| from a "randomness source" supplied by the operating system. The |
| randomness source is a CRNG at heart, but it also continually |
| "re-seeds" itself from physical sources of randomness, such as |
| electronic noise and clock jitter. This means applications do not need |
| to do anything to ensure that the random numbers it produces are |
| different on each run. |
| |
| The catch, however, is that these functions will only produce |
| relatively short random strings in any one call. Often this is not a |
| problem, but applications that need more than a few kilobytes of |
| cryptographically strong random data should call these functions once |
| and use their output to seed a CRNG. |
| |
| Most applications should use `getentropy'. The `getrandom' function |
| is intended for low-level applications which need additional control |
| over blocking behavior. |
| |
| -- Function: int getentropy (void *BUFFER, size_t LENGTH) |
| | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety Concepts::. |
| |
| This function writes exactly LENGTH bytes of random data to the |
| array starting at BUFFER. LENGTH can be no more than 256. On |
| success, it returns zero. On failure, it returns -1, and `errno' |
| is set to indicate the problem. Some of the possible errors are |
| listed below. |
| |
| `ENOSYS' |
| The operating system does not implement a randomness source, |
| or does not support this way of accessing it. (For instance, |
| the system call used by this function was added to the Linux |
| kernel in version 3.17.) |
| |
| `EFAULT' |
| The combination of BUFFER and LENGTH arguments specifies an |
| invalid memory range. |
| |
| `EIO' |
| LENGTH is larger than 256, or the kernel entropy pool has |
| suffered a catastrophic failure. |
| |
| A call to `getentropy' can only block when the system has just |
| booted and the randomness source has not yet been initialized. |
| However, if it does block, it cannot be interrupted by signals or |
| thread cancellation. Programs intended to run in very early |
| stages of the boot process may need to use `getrandom' in |
| non-blocking mode instead, and be prepared to cope with random |
| data not being available at all. |
| |
| The `getentropy' function is declared in the header file |
| `sys/random.h'. It is derived from OpenBSD. |
| |
| -- Function: ssize_t getrandom (void *BUFFER, size_t LENGTH, unsigned |
| int FLAGS) |
| | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety Concepts::. |
| |
| This function writes up to LENGTH bytes of random data to the |
| array starting at BUFFER. The FLAGS argument should be either |
| zero, or the bitwise OR of some of the following flags: |
| |
| `GRND_RANDOM' |
| Use the `/dev/random' (blocking) source instead of the |
| `/dev/urandom' (non-blocking) source to obtain randomness. |
| |
| If this flag is specified, the call may block, potentially |
| for quite some time, even after the randomness source has |
| been initialized. If it is not specified, the call can only |
| block when the system has just booted and the randomness |
| source has not yet been initialized. |
| |
| `GRND_NONBLOCK' |
| Instead of blocking, return to the caller immediately if no |
| data is available. |
| |
| Unlike `getentropy', the `getrandom' function is a cancellation |
| point, and if it blocks, it can be interrupted by signals. |
| |
| On success, `getrandom' returns the number of bytes which have |
| been written to the buffer, which may be less than LENGTH. On |
| error, it returns -1, and `errno' is set to indicate the problem. |
| Some of the possible errors are: |
| |
| `ENOSYS' |
| The operating system does not implement a randomness source, |
| or does not support this way of accessing it. (For instance, |
| the system call used by this function was added to the Linux |
| kernel in version 3.17.) |
| |
| `EAGAIN' |
| No random data was available and `GRND_NONBLOCK' was |
| specified in FLAGS. |
| |
| `EFAULT' |
| The combination of BUFFER and LENGTH arguments specifies an |
| invalid memory range. |
| |
| `EINTR' |
| The system call was interrupted. During the system boot |
| process, before the kernel randomness pool is initialized, |
| this can happen even if FLAGS is zero. |
| |
| `EINVAL' |
| The FLAGS argument contains an invalid combination of flags. |
| |
| The `getrandom' function is declared in the header file |
| `sys/random.h'. It is a GNU extension. |
| |
| |
| |
| File: libc.info, Node: Debugging Support, Next: Threads, Prev: Cryptographic Functions, Up: Top |
| |
| 34 Debugging support |
| ******************** |
| |
| Applications are usually debugged using dedicated debugger programs. |
| But sometimes this is not possible and, in any case, it is useful to |
| provide the developer with as much information as possible at the time |
| the problems are experienced. For this reason a few functions are |
| provided which a program can use to help the developer more easily |
| locate the problem. |
| |
| * Menu: |
| |
| * Backtraces:: Obtaining and printing a back trace of the |
| current stack. |
| |
| |
| File: libc.info, Node: Backtraces, Up: Debugging Support |
| |
| 34.1 Backtraces |
| =============== |
| |
| A "backtrace" is a list of the function calls that are currently active |
| in a thread. The usual way to inspect a backtrace of a program is to |
| use an external debugger such as gdb. However, sometimes it is useful |
| to obtain a backtrace programmatically from within a program, e.g., for |
| the purposes of logging or diagnostics. |
| |
| The header file `execinfo.h' declares three functions that obtain |
| and manipulate backtraces of the current thread. |
| |
| -- Function: int backtrace (void **BUFFER, int SIZE) |
| Preliminary: | MT-Safe | AS-Unsafe init heap dlopen plugin lock | |
| AC-Unsafe init mem lock fd | *Note POSIX Safety Concepts::. |
| |
| The `backtrace' function obtains a backtrace for the current |
| thread, as a list of pointers, and places the information into |
| BUFFER. The argument SIZE should be the number of `void *' |
| elements that will fit into BUFFER. The return value is the |
| actual number of entries of BUFFER that are obtained, and is at |
| most SIZE. |
| |
| The pointers placed in BUFFER are actually return addresses |
| obtained by inspecting the stack, one return address per stack |
| frame. |
| |
| Note that certain compiler optimizations may interfere with |
| obtaining a valid backtrace. Function inlining causes the inlined |
| function to not have a stack frame; tail call optimization |
| replaces one stack frame with another; frame pointer elimination |
| will stop `backtrace' from interpreting the stack contents |
| correctly. |
| |
| -- Function: char ** backtrace_symbols (void *const *BUFFER, int SIZE) |
| Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem lock | |
| *Note POSIX Safety Concepts::. |
| |
| The `backtrace_symbols' function translates the information |
| obtained from the `backtrace' function into an array of strings. |
| The argument BUFFER should be a pointer to an array of addresses |
| obtained via the `backtrace' function, and SIZE is the number of |
| entries in that array (the return value of `backtrace'). |
| |
| The return value is a pointer to an array of strings, which has |
| SIZE entries just like the array BUFFER. Each string contains a |
| printable representation of the corresponding element of BUFFER. |
| It includes the function name (if this can be determined), an |
| offset into the function, and the actual return address (in |
| hexadecimal). |
| |
| Currently, the function name and offset can only be obtained on |
| systems that use the ELF binary format for programs and libraries. |
| On other systems, only the hexadecimal return address will be |
| present. Also, you may need to pass additional flags to the |
| linker to make the function names available to the program. (For |
| example, on systems using GNU ld, you must pass `-rdynamic'.) |
| |
| The return value of `backtrace_symbols' is a pointer obtained via |
| the `malloc' function, and it is the responsibility of the caller |
| to `free' that pointer. Note that only the return value need be |
| freed, not the individual strings. |
| |
| The return value is `NULL' if sufficient memory for the strings |
| cannot be obtained. |
| |
| -- Function: void backtrace_symbols_fd (void *const *BUFFER, int SIZE, |
| int FD) |
| Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX |
| Safety Concepts::. |
| |
| The `backtrace_symbols_fd' function performs the same translation |
| as the function `backtrace_symbols' function. Instead of returning |
| the strings to the caller, it writes the strings to the file |
| descriptor FD, one per line. It does not use the `malloc' |
| function, and can therefore be used in situations where that |
| function might fail. |
| |
| The following program illustrates the use of these functions. Note |
| that the array to contain the return addresses returned by `backtrace' |
| is allocated on the stack. Therefore code like this can be used in |
| situations where the memory handling via `malloc' does not work anymore |
| (in which case the `backtrace_symbols' has to be replaced by a |
| `backtrace_symbols_fd' call as well). The number of return addresses |
| is normally not very large. Even complicated programs rather seldom |
| have a nesting level of more than, say, 50 and with 200 possible |
| entries probably all programs should be covered. |
| |
| |
| #include <execinfo.h> |
| #include <stdio.h> |
| #include <stdlib.h> |
| |
| /* Obtain a backtrace and print it to `stdout'. */ |
| void |
| print_trace (void) |
| { |
| void *array[10]; |
| size_t size; |
| char **strings; |
| size_t i; |
| |
| size = backtrace (array, 10); |
| strings = backtrace_symbols (array, size); |
| |
| printf ("Obtained %zd stack frames.\n", size); |
| |
| for (i = 0; i < size; i++) |
| printf ("%s\n", strings[i]); |
| |
| free (strings); |
| } |
| |
| /* A dummy function to make the backtrace more interesting. */ |
| void |
| dummy_function (void) |
| { |
| print_trace (); |
| } |
| |
| int |
| main (void) |
| { |
| dummy_function (); |
| return 0; |
| } |
| |
| |
| File: libc.info, Node: Threads, Next: Internal Probes, Prev: Debugging Support, Up: Top |
| |
| 35 Threads |
| ********** |
| |
| This chapter describes functions used for managing threads. The GNU C |
| Library provides two threading implementations: ISO C threads and POSIX |
| threads. |
| |
| * Menu: |
| |
| * ISO C Threads:: Threads based on the ISO C specification. |
| * POSIX Threads:: Threads based on the POSIX specification. |
| |
| |
| File: libc.info, Node: ISO C Threads, Next: POSIX Threads, Up: Threads |
| |
| 35.1 ISO C Threads |
| ================== |
| |
| This section describes the GNU C Library ISO C threads implementation. |
| To have a deeper understanding of this API, it is strongly recommended |
| to read ISO/IEC 9899:2011, section 7.26, in which ISO C threads were |
| originally specified. All types and function prototypes are declared |
| in the header file `threads.h'. |
| |
| * Menu: |
| |
| * ISO C Threads Return Values:: Symbolic constants that represent a |
| function's return value. |
| * ISO C Thread Management:: Support for basic threading. |
| * Call Once:: Single-call functions and macros. |
| * ISO C Mutexes:: A low-level mechanism for mutual exclusion. |
| * ISO C Condition Variables:: High-level objects for thread synchronization. |
| * ISO C Thread-local Storage:: Functions to support thread-local storage. |
| |
| |
| File: libc.info, Node: ISO C Threads Return Values, Next: ISO C Thread Management, Up: ISO C Threads |
| |
| 35.1.1 Return Values |
| -------------------- |
| |
| The ISO C thread specification provides the following enumeration |
| constants for return values from functions in the API: |
| |
| `thrd_timedout' |
| A specified time was reached without acquiring the requested |
| resource, usually a mutex or condition variable. |
| |
| `thrd_success' |
| The requested operation succeeded. |
| |
| `thrd_busy' |
| The requested operation failed because a requested resource is |
| already in use. |
| |
| `thrd_error' |
| The requested operation failed. |
| |
| `thrd_nomem' |
| The requested operation failed because it was unable to allocate |
| enough memory. |
| |
| |
| File: libc.info, Node: ISO C Thread Management, Next: Call Once, Prev: ISO C Threads Return Values, Up: ISO C Threads |
| |
| 35.1.2 Creation and Control |
| --------------------------- |
| |
| The GNU C Library implements a set of functions that allow the user to |
| easily create and use threads. Additional functionality is provided to |
| control the behavior of threads. |
| |
| The following data types are defined for managing threads: |
| |
| -- Data Type: thrd_t |
| A unique object that identifies a thread. |
| |
| -- Data Type: thrd_start_t |
| This data type is an `int (*) (void *)' typedef that is passed to |
| `thrd_create' when creating a new thread. It should point to the |
| first function that thread will run. |
| |
| The following functions are used for working with threads: |
| |
| -- Function: int thrd_create (thrd_t *THR, thrd_start_t FUNC, void |
| *ARG) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `thrd_create' creates a new thread that will execute the function |
| FUNC. The object pointed to by ARG will be used as the argument |
| to FUNC. If successful, THR is set to the new thread identifier. |
| |
| This function may return `thrd_success', `thrd_nomem', or |
| `thrd_error'. |
| |
| -- Function: thrd_t thrd_current (void) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function returns the identifier of the calling thread. |
| |
| -- Function: int thrd_equal (thrd_t LHS, thrd_t RHS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `thrd_equal' checks whether LHS and RHS refer to the same thread. |
| If LHS and RHS are different threads, this function returns 0; |
| otherwise, the return value is non-zero. |
| |
| -- Function: int thrd_sleep (const struct timespec *TIME_POINT, struct |
| timespec *REMAINING) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `thrd_sleep' blocks the execution of the current thread for at |
| least until the elapsed time pointed to by TIME_POINT has been |
| reached. This function does not take an absolute time, but a |
| duration that the thread is required to be blocked. *Note Time |
| Basics::, and *note Elapsed Time::. |
| |
| The thread may wake early if a signal that is not ignored is |
| received. In such a case, if `remaining' is not NULL, the |
| remaining time duration is stored in the object pointed to by |
| REMAINING. |
| |
| `thrd_sleep' returns 0 if it blocked for at least the amount of |
| time in `time_point', -1 if it was interrupted by a signal, or a |
| negative number on failure. |
| |
| -- Function: void thrd_yield (void) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `thrd_yield' provides a hint to the implementation to reschedule |
| the execution of the current thread, allowing other threads to run. |
| |
| -- Function: _Noreturn void thrd_exit (int RES) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `thrd_exit' terminates execution of the calling thread and sets |
| its result code to RES. |
| |
| If this function is called from a single-threaded process, the |
| call is equivalent to calling `exit' with `EXIT_SUCCESS' (*note |
| Normal Termination::). Also note that returning from a function |
| that started a thread is equivalent to calling `thrd_exit'. |
| |
| -- Function: int thrd_detach (thrd_t THR) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `thrd_detach' detaches the thread identified by `thr' from the |
| current control thread. The resources held by the detached thread |
| will be freed automatically once the thread exits. The parent |
| thread will never be notified by any THR signal. |
| |
| Calling `thrd_detach' on a thread that was previously detached or |
| joined by another thread results in undefined behavior. |
| |
| This function returns either `thrd_success' or `thrd_error'. |
| |
| -- Function: int thrd_join (thrd_t THR, int *RES) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `thrd_join' blocks the current thread until the thread identified |
| by `thr' finishes execution. If `res' is not NULL, the result |
| code of the thread is put into the location pointed to by RES. |
| The termination of the thread "synchronizes-with" the completion |
| of this function, meaning both threads have arrived at a common |
| point in their execution. |
| |
| Calling `thrd_join' on a thread that was previously detached or |
| joined by another thread results in undefined behavior. |
| |
| This function returns either `thrd_success' or `thrd_error'. |
| |
| |
| File: libc.info, Node: Call Once, Next: ISO C Mutexes, Prev: ISO C Thread Management, Up: ISO C Threads |
| |
| 35.1.3 Call Once |
| ---------------- |
| |
| In order to guarantee single access to a function, the GNU C Library |
| implements a "call once function" to ensure a function is only called |
| once in the presence of multiple, potentially calling threads. |
| |
| -- Data Type: once_flag |
| A complete object type capable of holding a flag used by |
| `call_once'. |
| |
| -- Macro: ONCE_FLAG_INIT |
| This value is used to initialize an object of type `once_flag'. |
| |
| -- Function: void call_once (once_flag *FLAG, void (*FUNC) (void)) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `call_once' calls function FUNC exactly once, even if invoked from |
| several threads. The completion of the function FUNC |
| synchronizes-with all previous or subsequent calls to `call_once' |
| with the same `flag' variable. |
| |
| |
| File: libc.info, Node: ISO C Mutexes, Next: ISO C Condition Variables, Prev: Call Once, Up: ISO C Threads |
| |
| 35.1.4 Mutexes |
| -------------- |
| |
| To have better control of resources and how threads access them, the |
| GNU C Library implements a "mutex" object, which can help avoid race |
| conditions and other concurrency issues. The term "mutex" refers to |
| mutual exclusion. |
| |
| The fundamental data type for a mutex is the `mtx_t': |
| |
| -- Data Type: mtx_t |
| The `mtx_t' data type uniquely identifies a mutex object. |
| |
| The ISO C standard defines several types of mutexes. They are |
| represented by the following symbolic constants: |
| |
| `mtx_plain' |
| A mutex that does not support timeout, or test and return. |
| |
| `mtx_recursive' |
| A mutex that supports recursive locking, which means that the |
| owning thread can lock it more than once without causing deadlock. |
| |
| `mtx_timed' |
| A mutex that supports timeout. |
| |
| The following functions are used for working with mutexes: |
| |
| -- Function: int mtx_init (mtx_t *MUTEX, int TYPE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `mtx_init' creates a new mutex object with type TYPE. The object |
| pointed to by MUTEX is set to the identifier of the newly created |
| mutex. |
| |
| Not all combinations of mutex types are valid for the `type' |
| argument. Valid uses of mutex types for the `type' argument are: |
| |
| `mtx_plain' |
| A non-recursive mutex that does not support timeout. |
| |
| `mtx_timed' |
| A non-recursive mutex that does support timeout. |
| |
| `mtx_plain | mtx_recursive' |
| A recursive mutex that does not support timeout. |
| |
| `mtx_timed | mtx_recursive' |
| A recursive mutex that does support timeout. |
| |
| This function returns either `thrd_success' or `thrd_error'. |
| |
| -- Function: int mtx_lock (mtx_t *MUTEX) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| `mtx_lock' blocks the current thread until the mutex pointed to by |
| MUTEX is locked. The behavior is undefined if the current thread |
| has already locked the mutex and the mutex is not recursive. |
| |
| Prior calls to `mtx_unlock' on the same mutex synchronize-with |
| this operation (if this operation succeeds), and all lock/unlock |
| operations on any given mutex form a single total order (similar to |
| the modification order of an atomic). |
| |
| This function returns either `thrd_success' or `thrd_error'. |
| |
| -- Function: int mtx_timedlock (mtx_t *restrict MUTEX, const struct |
| timespec *restrict TIME_POINT) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| `mtx_timedlock' blocks the current thread until the mutex pointed |
| to by MUTEX is locked or until the calendar time pointed to by |
| TIME_POINT has been reached. Since this function takes an |
| absolute time, if a duration is required, the calendar time must be |
| calculated manually. *Note Time Basics::, and *note Calendar |
| Time::. |
| |
| If the current thread has already locked the mutex and the mutex is |
| not recursive, or if the mutex does not support timeout, the |
| behavior of this function is undefined. |
| |
| Prior calls to `mtx_unlock' on the same mutex synchronize-with |
| this operation (if this operation succeeds), and all lock/unlock |
| operations on any given mutex form a single total order (similar to |
| the modification order of an atomic). |
| |
| This function returns either `thrd_success' or `thrd_error'. |
| |
| -- Function: int mtx_trylock (mtx_t *MUTEX) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| `mtx_trylock' tries to lock the mutex pointed to by MUTEX without |
| blocking. It returns immediately if the mutex is already locked. |
| |
| Prior calls to `mtx_unlock' on the same mutex synchronize-with |
| this operation (if this operation succeeds), and all lock/unlock |
| operations on any given mutex form a single total order (similar to |
| the modification order of an atomic). |
| |
| This function returns `thrd_success' if the lock was obtained, |
| `thrd_busy' if the mutex is already locked, and `thrd_error' on |
| failure. |
| |
| -- Function: int mtx_unlock (mtx_t *MUTEX) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `mtx_unlock' unlocks the mutex pointed to by MUTEX. The behavior |
| is undefined if the mutex is not locked by the calling thread. |
| |
| This function synchronizes-with subsequent `mtx_lock', |
| `mtx_trylock', and `mtx_timedlock' calls on the same mutex. All |
| lock/unlock operations on any given mutex form a single total |
| order (similar to the modification order of an atomic). |
| |
| This function returns either `thrd_success' or `thrd_error'. |
| |
| -- Function: void mtx_destroy (mtx_t *MUTEX) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `mtx_destroy' destroys the mutex pointed to by MUTEX. If there |
| are any threads waiting on the mutex, the behavior is undefined. |
| |
| |
| File: libc.info, Node: ISO C Condition Variables, Next: ISO C Thread-local Storage, Prev: ISO C Mutexes, Up: ISO C Threads |
| |
| 35.1.5 Condition Variables |
| -------------------------- |
| |
| Mutexes are not the only synchronization mechanisms available. For |
| some more complex tasks, the GNU C Library also implements "condition |
| variables", which allow the programmer to think at a higher level when |
| solving complex synchronization problems. They are used to synchronize |
| threads waiting on a certain condition to happen. |
| |
| The fundamental data type for condition variables is the `cnd_t': |
| |
| -- Data Type: cnd_t |
| The `cnd_t' uniquely identifies a condition variable object. |
| |
| The following functions are used for working with condition |
| variables: |
| |
| -- Function: int cnd_init (cnd_t *COND) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `cnd_init' initializes a new condition variable, identified by |
| COND. |
| |
| This function may return `thrd_success', `thrd_nomem', or |
| `thrd_error'. |
| |
| -- Function: int cnd_signal (cnd_t *COND) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `cnd_signal' unblocks one thread that is currently waiting on the |
| condition variable pointed to by COND. If a thread is |
| successfully unblocked, this function returns `thrd_success'. If |
| no threads are blocked, this function does nothing and returns |
| `thrd_success'. Otherwise, this function returns `thrd_error'. |
| |
| -- Function: int cnd_broadcast (cnd_t *COND) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `cnd_broadcast' unblocks all the threads that are currently |
| waiting on the condition variable pointed to by COND. This |
| function returns `thrd_success' on success. If no threads are |
| blocked, this function does nothing and returns `thrd_success'. |
| Otherwise, this function returns `thrd_error'. |
| |
| -- Function: int cnd_wait (cnd_t *COND, mtx_t *MUTEX) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| `cnd_wait' atomically unlocks the mutex pointed to by MUTEX and |
| blocks on the condition variable pointed to by COND until the |
| thread is signaled by `cnd_signal' or `cnd_broadcast'. The mutex |
| is locked again before the function returns. |
| |
| This function returns either `thrd_success' or `thrd_error'. |
| |
| -- Function: int cnd_timedwait (cnd_t *restrict COND, mtx_t *restrict |
| MUTEX, const struct timespec *restrict TIME_POINT) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| `cnd_timedwait' atomically unlocks the mutex pointed to by MUTEX |
| and blocks on the condition variable pointed to by COND until the |
| thread is signaled by `cnd_signal' or `cnd_broadcast', or until |
| the calendar time pointed to by TIME_POINT has been reached. The |
| mutex is locked again before the function returns. |
| |
| As for `mtx_timedlock', since this function takes an absolute |
| time, if a duration is required, the calendar time must be |
| calculated manually. *Note Time Basics::, and *note Calendar |
| Time::. |
| |
| This function may return `thrd_success', `thrd_nomem', or |
| `thrd_error'. |
| |
| -- Function: void cnd_destroy (cnd_t *COND) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `cnd_destroy' destroys the condition variable pointed to by COND. |
| If there are threads waiting on COND, the behavior is undefined. |
| |
| |
| File: libc.info, Node: ISO C Thread-local Storage, Prev: ISO C Condition Variables, Up: ISO C Threads |
| |
| 35.1.6 Thread-local Storage |
| --------------------------- |
| |
| The GNU C Library implements functions to provide "thread-local |
| storage", a mechanism by which variables can be defined to have unique |
| per-thread storage, lifetimes that match the thread lifetime, and |
| destructors that cleanup the unique per-thread storage. |
| |
| Several data types and macros exist for working with thread-local |
| storage: |
| |
| -- Data Type: tss_t |
| The `tss_t' data type identifies a thread-specific storage object. |
| Even if shared, every thread will have its own instance of the |
| variable, with different values. |
| |
| -- Data Type: tss_dtor_t |
| The `tss_dtor_t' is a function pointer of type `void (*) (void |
| *)', to be used as a thread-specific storage destructor. The |
| function will be called when the current thread calls `thrd_exit' |
| (but never when calling `tss_delete' or `exit'). |
| |
| -- Macro: thread_local |
| `thread_local' is used to mark a variable with thread storage |
| duration, which means it is created when the thread starts and |
| cleaned up when the thread ends. |
| |
| _Note:_ For C++, C++11 or later is required to use the |
| `thread_local' keyword. |
| |
| -- Macro: TSS_DTOR_ITERATIONS |
| `TSS_DTOR_ITERATIONS' is an integer constant expression |
| representing the maximum number of iterations over all thread-local |
| destructors at the time of thread termination. This value |
| provides a bounded limit to the destruction of thread-local |
| storage; e.g., consider a destructor that creates more |
| thread-local storage. |
| |
| The following functions are used to manage thread-local storage: |
| |
| -- Function: int tss_create (tss_t *TSS_KEY, tss_dtor_t DESTRUCTOR) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `tss_create' creates a new thread-specific storage key and stores |
| it in the object pointed to by TSS_KEY. Although the same key |
| value may be used by different threads, the values bound to the |
| key by `tss_set' are maintained on a per-thread basis and persist |
| for the life of the calling thread. |
| |
| If `destructor' is not NULL, a destructor function will be set, |
| and called when the thread finishes its execution by calling |
| `thrd_exit'. |
| |
| This function returns `thrd_success' if `tss_key' is successfully |
| set to a unique value for the thread; otherwise, `thrd_error' is |
| returned and the value of `tss_key' is undefined. |
| |
| -- Function: int tss_set (tss_t TSS_KEY, void *VAL) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `tss_set' sets the value of the thread-specific storage identified |
| by TSS_KEY for the current thread to VAL. Different threads may |
| set different values to the same key. |
| |
| This function returns either `thrd_success' or `thrd_error'. |
| |
| -- Function: void * tss_get (tss_t TSS_KEY) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `tss_get' returns the value identified by TSS_KEY held in |
| thread-specific storage for the current thread. Different threads |
| may get different values identified by the same key. On failure, |
| `tss_get' returns zero. |
| |
| -- Function: void tss_delete (tss_t TSS_KEY) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `tss_delete' destroys the thread-specific storage identified by |
| TSS_KEY. |
| |
| |
| File: libc.info, Node: POSIX Threads, Prev: ISO C Threads, Up: Threads |
| |
| 35.2 POSIX Threads |
| ================== |
| |
| This section describes the GNU C Library POSIX Threads implementation. |
| |
| * Menu: |
| |
| * Thread-specific Data:: Support for creating and |
| managing thread-specific data |
| * Non-POSIX Extensions:: Additional functions to extend |
| POSIX Thread functionality |
| |
| |
| File: libc.info, Node: Thread-specific Data, Next: Non-POSIX Extensions, Up: POSIX Threads |
| |
| 35.2.1 Thread-specific Data |
| --------------------------- |
| |
| The GNU C Library implements functions to allow users to create and |
| manage data specific to a thread. Such data may be destroyed at thread |
| exit, if a destructor is provided. The following functions are defined: |
| |
| -- Function: int pthread_key_create (pthread_key_t *KEY, void |
| (*DESTRUCTOR)(void*)) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Create a thread-specific data key for the calling thread, |
| referenced by KEY. |
| |
| Objects declared with the C++11 `thread_local' keyword are |
| destroyed before thread-specific data, so they should not be used |
| in thread-specific data destructors or even as members of the |
| thread-specific data, since the latter is passed as an argument to |
| the destructor function. |
| |
| -- Function: int pthread_key_delete (pthread_key_t KEY) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Destroy the thread-specific data KEY in the calling thread. The |
| destructor for the thread-specific data is not called during |
| destruction, nor is it called during thread exit. |
| |
| -- Function: void *pthread_getspecific (pthread_key_t KEY) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Return the thread-specific data associated with KEY in the calling |
| thread. |
| |
| -- Function: int pthread_setspecific (pthread_key_t KEY, const void |
| *VALUE) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt heap | AC-Unsafe |
| corrupt mem | *Note POSIX Safety Concepts::. |
| |
| Associate the thread-specific VALUE with KEY in the calling thread. |
| |
| |
| File: libc.info, Node: Non-POSIX Extensions, Prev: Thread-specific Data, Up: POSIX Threads |
| |
| 35.2.2 Non-POSIX Extensions |
| --------------------------- |
| |
| In addition to implementing the POSIX API for threads, the GNU C |
| Library provides additional functions and interfaces to provide |
| functionality not specified in the standard. |
| |
| * Menu: |
| |
| * Default Thread Attributes:: Setting default attributes for |
| threads in a process. |
| |
| |
| File: libc.info, Node: Default Thread Attributes, Up: Non-POSIX Extensions |
| |
| 35.2.2.1 Setting Process-wide defaults for thread attributes |
| ............................................................ |
| |
| The GNU C Library provides non-standard API functions to set and get |
| the default attributes used in the creation of threads in a process. |
| |
| -- Function: int pthread_getattr_default_np (pthread_attr_t *ATTR) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| Get the default attribute values and set ATTR to match. This |
| function returns 0 on success and a non-zero error code on failure. |
| |
| -- Function: int pthread_setattr_default_np (pthread_attr_t *ATTR) |
| Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock mem |
| | *Note POSIX Safety Concepts::. |
| |
| Set the default attribute values to match the values in ATTR. The |
| function returns 0 on success and a non-zero error code on failure. |
| The following error codes are defined for this function: |
| |
| `EINVAL' |
| At least one of the values in ATTR does not qualify as valid |
| for the attributes or the stack address is set in the |
| attribute. |
| |
| `ENOMEM' |
| The system does not have sufficient memory. |
| |
| -- Function: int sem_clockwait (sem_t *SEM, clockid_t CLOCKID, |
| const struct timespec *ABSTIME) Behaves like `sem_timedwait' |
| except the time ABSTIME is measured against the clock specified by |
| CLOCKID rather than `CLOCK_REALTIME'. Currently, CLOCKID must be |
| either `CLOCK_MONOTONIC' or `CLOCK_REALTIME'. |
| |
| -- Function: int pthread_cond_clockwait (pthread_cond_t *COND, |
| pthread_mutex_t *MUTEX, |
| clockid_t CLOCKID, const struct timespec *ABSTIME) Preliminary: | |
| MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note POSIX Safety |
| Concepts::. |
| |
| Behaves like `pthread_cond_timedwait' except the time ABSTIME is |
| measured against the clock specified by CLOCKID rather than the |
| clock specified or defaulted when `pthread_cond_init' was called. |
| Currently, CLOCKID must be either `CLOCK_MONOTONIC' or |
| `CLOCK_REALTIME'. |
| |
| -- Function: int pthread_rwlock_clockrdlock (pthread_rwlock_t *RWLOCK, |
| clockid_t CLOCKID, |
| const struct timespec *ABSTIME) |
| |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| Behaves like `pthread_rwlock_timedrdlock' except the time ABSTIME |
| is measured against the clock specified by CLOCKID rather than |
| `CLOCK_REALTIME'. Currently, CLOCKID must be either |
| `CLOCK_MONOTONIC' or `CLOCK_REALTIME', otherwise `EINVAL' is |
| returned. |
| |
| -- Function: int pthread_rwlock_clockwrlock (pthread_rwlock_t *RWLOCK, |
| clockid_t CLOCKID, |
| const struct timespec *ABSTIME) |
| |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| Behaves like `pthread_rwlock_timedwrlock' except the time ABSTIME |
| is measured against the clock specified by CLOCKID rather than |
| `CLOCK_REALTIME'. Currently, CLOCKID must be either |
| `CLOCK_MONOTONIC' or `CLOCK_REALTIME', otherwise `EINVAL' is |
| returned. |
| |
| |
| File: libc.info, Node: Internal Probes, Next: Tunables, Prev: Threads, Up: Top |
| |
| 36 Internal probes |
| ****************** |
| |
| In order to aid in debugging and monitoring internal behavior, the GNU |
| C Library exposes nearly-zero-overhead SystemTap probes marked with the |
| `libc' provider. |
| |
| These probes are not part of the GNU C Library stable ABI, and they |
| are subject to change or removal across releases. Our only promise with |
| regard to them is that, if we find a need to remove or modify the |
| arguments of a probe, the modified probe will have a different name, so |
| that program monitors relying on the old probe will not get unexpected |
| arguments. |
| |
| * Menu: |
| |
| * Memory Allocation Probes:: Probes in the memory allocation subsystem |
| * Mathematical Function Probes:: Probes in mathematical functions |
| * Non-local Goto Probes:: Probes in setjmp and longjmp |
| |
| |
| File: libc.info, Node: Memory Allocation Probes, Next: Mathematical Function Probes, Up: Internal Probes |
| |
| 36.1 Memory Allocation Probes |
| ============================= |
| |
| These probes are designed to signal relatively unusual situations within |
| the virtual memory subsystem of the GNU C Library. |
| |
| -- Probe: memory_sbrk_more (void *$ARG1, size_t $ARG2) |
| This probe is triggered after the main arena is extended by calling |
| `sbrk'. Argument $ARG1 is the additional size requested to |
| `sbrk', and $ARG2 is the pointer that marks the end of the `sbrk' |
| area, returned in response to the request. |
| |
| -- Probe: memory_sbrk_less (void *$ARG1, size_t $ARG2) |
| This probe is triggered after the size of the main arena is |
| decreased by calling `sbrk'. Argument $ARG1 is the size released |
| by `sbrk' (the positive value, rather than the negative value |
| passed to `sbrk'), and $ARG2 is the pointer that marks the end of |
| the `sbrk' area, returned in response to the request. |
| |
| -- Probe: memory_heap_new (void *$ARG1, size_t $ARG2) |
| This probe is triggered after a new heap is `mmap'ed. Argument |
| $ARG1 is a pointer to the base of the memory area, where the |
| `heap_info' data structure is held, and $ARG2 is the size of the |
| heap. |
| |
| -- Probe: memory_heap_free (void *$ARG1, size_t $ARG2) |
| This probe is triggered _before_ (unlike the other sbrk and heap |
| probes) a heap is completely removed via `munmap'. Argument $ARG1 |
| is a pointer to the heap, and $ARG2 is the size of the heap. |
| |
| -- Probe: memory_heap_more (void *$ARG1, size_t $ARG2) |
| This probe is triggered after a trailing portion of an `mmap'ed |
| heap is extended. Argument $ARG1 is a pointer to the heap, and |
| $ARG2 is the new size of the heap. |
| |
| -- Probe: memory_heap_less (void *$ARG1, size_t $ARG2) |
| This probe is triggered after a trailing portion of an `mmap'ed |
| heap is released. Argument $ARG1 is a pointer to the heap, and |
| $ARG2 is the new size of the heap. |
| |
| -- Probe: memory_malloc_retry (size_t $ARG1) |
| -- Probe: memory_realloc_retry (size_t $ARG1, void *$ARG2) |
| -- Probe: memory_memalign_retry (size_t $ARG1, size_t $ARG2) |
| -- Probe: memory_calloc_retry (size_t $ARG1) |
| These probes are triggered when the corresponding functions fail to |
| obtain the requested amount of memory from the arena in use, |
| before they call `arena_get_retry' to select an alternate arena in |
| which to retry the allocation. Argument $ARG1 is the amount of |
| memory requested by the user; in the `calloc' case, that is the |
| total size computed from both function arguments. In the |
| `realloc' case, $ARG2 is the pointer to the memory area being |
| resized. In the `memalign' case, $ARG2 is the alignment to be |
| used for the request, which may be stricter than the value passed |
| to the `memalign' function. A `memalign' probe is also used by |
| functions `posix_memalign, valloc' and `pvalloc'. |
| |
| Note that the argument order does _not_ match that of the |
| corresponding two-argument functions, so that in all of these |
| probes the user-requested allocation size is in $ARG1. |
| |
| -- Probe: memory_arena_retry (size_t $ARG1, void *$ARG2) |
| This probe is triggered within `arena_get_retry' (the function |
| called to select the alternate arena in which to retry an |
| allocation that failed on the first attempt), before the selection |
| of an alternate arena. This probe is redundant, but much easier |
| to use when it's not important to determine which of the various |
| memory allocation functions is failing to allocate on the first |
| try. Argument $ARG1 is the same as in the function-specific |
| probes, except for extra room for padding introduced by functions |
| that have to ensure stricter alignment. Argument $ARG2 is the |
| arena in which allocation failed. |
| |
| -- Probe: memory_arena_new (void *$ARG1, size_t $ARG2) |
| This probe is triggered when `malloc' allocates and initializes an |
| additional arena (not the main arena), but before the arena is |
| assigned to the running thread or inserted into the internal |
| linked list of arenas. The arena's `malloc_state' internal data |
| structure is located at $ARG1, within a newly-allocated heap big |
| enough to hold at least $ARG2 bytes. |
| |
| -- Probe: memory_arena_reuse (void *$ARG1, void *$ARG2) |
| This probe is triggered when `malloc' has just selected an existing |
| arena to reuse, and (temporarily) reserved it for exclusive use. |
| Argument $ARG1 is a pointer to the newly-selected arena, and $ARG2 |
| is a pointer to the arena previously used by that thread. |
| |
| This occurs within `reused_arena', right after the mutex mentioned |
| in probe `memory_arena_reuse_wait' is acquired; argument $ARG1 will |
| point to the same arena. In this configuration, this will usually |
| only occur once per thread. The exception is when a thread first |
| selected the main arena, but a subsequent allocation from it |
| fails: then, and only then, may we switch to another arena to |
| retry that allocation, and for further allocations within that |
| thread. |
| |
| -- Probe: memory_arena_reuse_wait (void *$ARG1, void *$ARG2, void |
| *$ARG3) |
| This probe is triggered when `malloc' is about to wait for an arena |
| to become available for reuse. Argument $ARG1 holds a pointer to |
| the mutex the thread is going to wait on, $ARG2 is a pointer to a |
| newly-chosen arena to be reused, and $ARG3 is a pointer to the |
| arena previously used by that thread. |
| |
| This occurs within `reused_arena', when a thread first tries to |
| allocate memory or needs a retry after a failure to allocate from |
| the main arena, there isn't any free arena, the maximum number of |
| arenas has been reached, and an existing arena was chosen for |
| reuse, but its mutex could not be immediately acquired. The mutex |
| in $ARG1 is the mutex of the selected arena. |
| |
| -- Probe: memory_arena_reuse_free_list (void *$ARG1) |
| This probe is triggered when `malloc' has chosen an arena that is |
| in the free list for use by a thread, within the `get_free_list' |
| function. The argument $ARG1 holds a pointer to the selected |
| arena. |
| |
| -- Probe: memory_mallopt (int $ARG1, int $ARG2) |
| This probe is triggered when function `mallopt' is called to change |
| `malloc' internal configuration parameters, before any change to |
| the parameters is made. The arguments $ARG1 and $ARG2 are the |
| ones passed to the `mallopt' function. |
| |
| -- Probe: memory_mallopt_mxfast (int $ARG1, int $ARG2) |
| This probe is triggered shortly after the `memory_mallopt' probe, |
| when the parameter to be changed is `M_MXFAST', and the requested |
| value is in an acceptable range. Argument $ARG1 is the requested |
| value, and $ARG2 is the previous value of this `malloc' parameter. |
| |
| -- Probe: memory_mallopt_trim_threshold (int $ARG1, int $ARG2, int |
| $ARG3) |
| This probe is triggered shortly after the `memory_mallopt' probe, |
| when the parameter to be changed is `M_TRIM_THRESHOLD'. Argument |
| $ARG1 is the requested value, $ARG2 is the previous value of this |
| `malloc' parameter, and $ARG3 is nonzero if dynamic threshold |
| adjustment was already disabled. |
| |
| -- Probe: memory_mallopt_top_pad (int $ARG1, int $ARG2, int $ARG3) |
| This probe is triggered shortly after the `memory_mallopt' probe, |
| when the parameter to be changed is `M_TOP_PAD'. Argument $ARG1 |
| is the requested value, $ARG2 is the previous value of this |
| `malloc' parameter, and $ARG3 is nonzero if dynamic threshold |
| adjustment was already disabled. |
| |
| -- Probe: memory_mallopt_mmap_threshold (int $ARG1, int $ARG2, int |
| $ARG3) |
| This probe is triggered shortly after the `memory_mallopt' probe, |
| when the parameter to be changed is `M_MMAP_THRESHOLD', and the |
| requested value is in an acceptable range. Argument $ARG1 is the |
| requested value, $ARG2 is the previous value of this `malloc' |
| parameter, and $ARG3 is nonzero if dynamic threshold adjustment |
| was already disabled. |
| |
| -- Probe: memory_mallopt_mmap_max (int $ARG1, int $ARG2, int $ARG3) |
| This probe is triggered shortly after the `memory_mallopt' probe, |
| when the parameter to be changed is `M_MMAP_MAX'. Argument $ARG1 |
| is the requested value, $ARG2 is the previous value of this |
| `malloc' parameter, and $ARG3 is nonzero if dynamic threshold |
| adjustment was already disabled. |
| |
| -- Probe: memory_mallopt_perturb (int $ARG1, int $ARG2) |
| This probe is triggered shortly after the `memory_mallopt' probe, |
| when the parameter to be changed is `M_PERTURB'. Argument $ARG1 |
| is the requested value, and $ARG2 is the previous value of this |
| `malloc' parameter. |
| |
| -- Probe: memory_mallopt_arena_test (int $ARG1, int $ARG2) |
| This probe is triggered shortly after the `memory_mallopt' probe, |
| when the parameter to be changed is `M_ARENA_TEST', and the |
| requested value is in an acceptable range. Argument $ARG1 is the |
| requested value, and $ARG2 is the previous value of this `malloc' |
| parameter. |
| |
| -- Probe: memory_mallopt_arena_max (int $ARG1, int $ARG2) |
| This probe is triggered shortly after the `memory_mallopt' probe, |
| when the parameter to be changed is `M_ARENA_MAX', and the |
| requested value is in an acceptable range. Argument $ARG1 is the |
| requested value, and $ARG2 is the previous value of this `malloc' |
| parameter. |
| |
| -- Probe: memory_mallopt_free_dyn_thresholds (int $ARG1, int $ARG2) |
| This probe is triggered when function `free' decides to adjust the |
| dynamic brk/mmap thresholds. Argument $ARG1 and $ARG2 are the |
| adjusted mmap and trim thresholds, respectively. |
| |
| -- Probe: memory_tunable_tcache_max_bytes (int $ARG1, int $ARG2) |
| This probe is triggered when the `glibc.malloc.tcache_max' tunable |
| is set. Argument $ARG1 is the requested value, and $ARG2 is the |
| previous value of this tunable. |
| |
| -- Probe: memory_tunable_tcache_count (int $ARG1, int $ARG2) |
| This probe is triggered when the `glibc.malloc.tcache_count' |
| tunable is set. Argument $ARG1 is the requested value, and $ARG2 |
| is the previous value of this tunable. |
| |
| -- Probe: memory_tunable_tcache_unsorted_limit (int $ARG1, int $ARG2) |
| This probe is triggered when the |
| `glibc.malloc.tcache_unsorted_limit' tunable is set. Argument |
| $ARG1 is the requested value, and $ARG2 is the previous value of |
| this tunable. |
| |
| -- Probe: memory_tcache_double_free (void *$ARG1, int $ARG2) |
| This probe is triggered when `free' determines that the memory |
| being freed has probably already been freed, and resides in the |
| per-thread cache. Note that there is an extremely unlikely chance |
| that this probe will trigger due to random payload data remaining |
| in the allocated memory matching the key used to detect double |
| frees. This probe actually indicates that an expensive linear |
| search of the tcache, looking for a double free, has happened. |
| Argument $ARG1 is the memory location as passed to `free', |
| Argument $ARG2 is the tcache bin it resides in. |
| |
| |
| File: libc.info, Node: Mathematical Function Probes, Next: Non-local Goto Probes, Prev: Memory Allocation Probes, Up: Internal Probes |
| |
| 36.2 Mathematical Function Probes |
| ================================= |
| |
| Some mathematical functions fall back to multiple precision arithmetic |
| for some inputs to get last bit precision for their return values. |
| This multiple precision fallback is much slower than the default |
| algorithms and may have a significant impact on application |
| performance. The systemtap probe markers described in this section may |
| help you determine if your application calls mathematical functions |
| with inputs that may result in multiple-precision arithmetic. |
| |
| Unless explicitly mentioned otherwise, a precision of 1 implies 24 |
| bits of precision in the mantissa of the multiple precision number. |
| Hence, a precision level of 32 implies 768 bits of precision in the |
| mantissa. |
| |
| -- Probe: slowatan2 (int $ARG1, double $ARG2, double $ARG3, double |
| $ARG4) |
| This probe is triggered when the `atan2' function is called with |
| an input that results in multiple precision computation. Argument |
| $ARG1 is the precision with which computation succeeded. |
| Arguments $ARG2 and $ARG3 are inputs to the `atan2' function and |
| $ARG4 is the computed result. |
| |
| -- Probe: slowatan2_inexact (int $ARG1, double $ARG2, double $ARG3, |
| double $ARG4) |
| This probe is triggered when the `atan' function is called with an |
| input that results in multiple precision computation and none of |
| the multiple precision computations result in an accurate result. |
| Argument $ARG1 is the maximum precision with which computations |
| were performed. Arguments $ARG2 and $ARG3 are inputs to the |
| `atan2' function and $ARG4 is the computed result. |
| |
| -- Probe: slowatan (int $ARG1, double $ARG2, double $ARG3) |
| This probe is triggered when the `atan' function is called with an |
| input that results in multiple precision computation. Argument |
| $ARG1 is the precision with which computation succeeded. Argument |
| $ARG2 is the input to the `atan' function and $ARG3 is the |
| computed result. |
| |
| -- Probe: slowatan_inexact (int $ARG1, double $ARG2, double $ARG3) |
| This probe is triggered when the `atan' function is called with an |
| input that results in multiple precision computation and none of |
| the multiple precision computations result in an accurate result. |
| Argument $ARG1 is the maximum precision with which computations |
| were performed. Argument $ARG2 is the input to the `atan' |
| function and $ARG3 is the computed result. |
| |
| -- Probe: slowtan (double $ARG1, double $ARG2) |
| This probe is triggered when the `tan' function is called with an |
| input that results in multiple precision computation with precision |
| 32. Argument $ARG1 is the input to the function and $ARG2 is the |
| computed result. |
| |
| -- Probe: slowasin (double $ARG1, double $ARG2) |
| This probe is triggered when the `asin' function is called with an |
| input that results in multiple precision computation with precision |
| 32. Argument $ARG1 is the input to the function and $ARG2 is the |
| computed result. |
| |
| -- Probe: slowacos (double $ARG1, double $ARG2) |
| This probe is triggered when the `acos' function is called with an |
| input that results in multiple precision computation with precision |
| 32. Argument $ARG1 is the input to the function and $ARG2 is the |
| computed result. |
| |
| -- Probe: slowsin (double $ARG1, double $ARG2) |
| This probe is triggered when the `sin' function is called with an |
| input that results in multiple precision computation with precision |
| 32. Argument $ARG1 is the input to the function and $ARG2 is the |
| computed result. |
| |
| -- Probe: slowcos (double $ARG1, double $ARG2) |
| This probe is triggered when the `cos' function is called with an |
| input that results in multiple precision computation with precision |
| 32. Argument $ARG1 is the input to the function and $ARG2 is the |
| computed result. |
| |
| -- Probe: slowsin_dx (double $ARG1, double $ARG2, double $ARG3) |
| This probe is triggered when the `sin' function is called with an |
| input that results in multiple precision computation with precision |
| 32. Argument $ARG1 is the input to the function, $ARG2 is the |
| error bound of $ARG1 and $ARG3 is the computed result. |
| |
| -- Probe: slowcos_dx (double $ARG1, double $ARG2, double $ARG3) |
| This probe is triggered when the `cos' function is called with an |
| input that results in multiple precision computation with precision |
| 32. Argument $ARG1 is the input to the function, $ARG2 is the |
| error bound of $ARG1 and $ARG3 is the computed result. |
| |
| |
| File: libc.info, Node: Non-local Goto Probes, Prev: Mathematical Function Probes, Up: Internal Probes |
| |
| 36.3 Non-local Goto Probes |
| ========================== |
| |
| These probes are used to signal calls to `setjmp', `sigsetjmp', |
| `longjmp' or `siglongjmp'. |
| |
| -- Probe: setjmp (void *$ARG1, int $ARG2, void *$ARG3) |
| This probe is triggered whenever `setjmp' or `sigsetjmp' is |
| called. Argument $ARG1 is a pointer to the `jmp_buf' passed as |
| the first argument of `setjmp' or `sigsetjmp', $ARG2 is the second |
| argument of `sigsetjmp' or zero if this is a call to `setjmp' and |
| $ARG3 is a pointer to the return address that will be stored in |
| the `jmp_buf'. |
| |
| -- Probe: longjmp (void *$ARG1, int $ARG2, void *$ARG3) |
| This probe is triggered whenever `longjmp' or `siglongjmp' is |
| called. Argument $ARG1 is a pointer to the `jmp_buf' passed as |
| the first argument of `longjmp' or `siglongjmp', $ARG2 is the |
| return value passed as the second argument of `longjmp' or |
| `siglongjmp' and $ARG3 is a pointer to the return address |
| `longjmp' or `siglongjmp' will return to. |
| |
| The `longjmp' probe is triggered at a point where the registers |
| have not yet been restored to the values in the `jmp_buf' and |
| unwinding will show a call stack including the caller of `longjmp' |
| or `siglongjmp'. |
| |
| -- Probe: longjmp_target (void *$ARG1, int $ARG2, void *$ARG3) |
| This probe is triggered under the same conditions and with the same |
| arguments as the `longjmp' probe. |
| |
| The `longjmp_target' probe is triggered at a point where the |
| registers have been restored to the values in the `jmp_buf' and |
| unwinding will show a call stack including the caller of `setjmp' |
| or `sigsetjmp'. |
| |
| |
| File: libc.info, Node: Tunables, Next: Language Features, Prev: Internal Probes, Up: Top |
| |
| 37 Tunables |
| *********** |
| |
| "Tunables" are a feature in the GNU C Library that allows application |
| authors and distribution maintainers to alter the runtime library |
| behavior to match their workload. These are implemented as a set of |
| switches that may be modified in different ways. The current default |
| method to do this is via the `GLIBC_TUNABLES' environment variable by |
| setting it to a string of colon-separated NAME=VALUE pairs. For |
| example, the following example enables malloc checking and sets the |
| malloc trim threshold to 128 bytes: |
| |
| GLIBC_TUNABLES=glibc.malloc.trim_threshold=128:glibc.malloc.check=3 |
| export GLIBC_TUNABLES |
| |
| Tunables are not part of the GNU C Library stable ABI, and they are |
| subject to change or removal across releases. Additionally, the method |
| to modify tunable values may change between releases and across |
| distributions. It is possible to implement multiple `frontends' for |
| the tunables allowing distributions to choose their preferred method at |
| build time. |
| |
| Finally, the set of tunables available may vary between |
| distributions as the tunables feature allows distributions to add their |
| own tunables under their own namespace. |
| |
| * Menu: |
| |
| * Tunable names:: The structure of a tunable name |
| * Memory Allocation Tunables:: Tunables in the memory allocation subsystem |
| * Elision Tunables:: Tunables in elision subsystem |
| * POSIX Thread Tunables:: Tunables in the POSIX thread subsystem |
| * Hardware Capability Tunables:: Tunables that modify the hardware |
| capabilities seen by the GNU C Library |
| |
| |
| File: libc.info, Node: Tunable names, Next: Memory Allocation Tunables, Up: Tunables |
| |
| 37.1 Tunable names |
| ================== |
| |
| A tunable name is split into three components, a top namespace, a |
| tunable namespace and the tunable name. The top namespace for tunables |
| implemented in the GNU C Library is `glibc'. Distributions that choose |
| to add custom tunables in their maintained versions of the GNU C |
| Library may choose to do so under their own top namespace. |
| |
| The tunable namespace is a logical grouping of tunables in a single |
| module. This currently holds no special significance, although that may |
| change in the future. |
| |
| The tunable name is the actual name of the tunable. It is possible |
| that different tunable namespaces may have tunables within them that |
| have the same name, likewise for top namespaces. Hence, we only support |
| identification of tunables by their full name, i.e. with the top |
| namespace, tunable namespace and tunable name, separated by periods. |
| |
| |
| |
| Local Variables: |
| coding: utf-8 |
| End: |
