| This is |
| /usr/local/google/home/jnewlin/src/uclibc/buildroot/output/build/glibc-2.19/build/manual/libc.info, |
| produced by makeinfo version 4.13 from libc.texinfo. |
| |
| INFO-DIR-SECTION Software libraries |
| START-INFO-DIR-ENTRY |
| * Libc: (libc). C library. |
| END-INFO-DIR-ENTRY |
| |
| INFO-DIR-SECTION GNU C library functions and macros |
| START-INFO-DIR-ENTRY |
| * ALTWERASE: (libc)Local Modes. |
| * ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions. |
| * ARG_MAX: (libc)General Limits. |
| * BC_BASE_MAX: (libc)Utility Limits. |
| * BC_DIM_MAX: (libc)Utility Limits. |
| * BC_SCALE_MAX: (libc)Utility Limits. |
| * BC_STRING_MAX: (libc)Utility Limits. |
| * BRKINT: (libc)Input Modes. |
| * BUFSIZ: (libc)Controlling Buffering. |
| * CCTS_OFLOW: (libc)Control Modes. |
| * CHILD_MAX: (libc)General Limits. |
| * CIGNORE: (libc)Control Modes. |
| * CLK_TCK: (libc)Processor Time. |
| * CLOCAL: (libc)Control Modes. |
| * CLOCKS_PER_SEC: (libc)CPU Time. |
| * COLL_WEIGHTS_MAX: (libc)Utility Limits. |
| * CPU_CLR: (libc)CPU Affinity. |
| * CPU_ISSET: (libc)CPU Affinity. |
| * CPU_SET: (libc)CPU Affinity. |
| * CPU_SETSIZE: (libc)CPU Affinity. |
| * CPU_ZERO: (libc)CPU Affinity. |
| * CREAD: (libc)Control Modes. |
| * CRTS_IFLOW: (libc)Control Modes. |
| * CS5: (libc)Control Modes. |
| * CS6: (libc)Control Modes. |
| * CS7: (libc)Control Modes. |
| * CS8: (libc)Control Modes. |
| * CSIZE: (libc)Control Modes. |
| * CSTOPB: (libc)Control Modes. |
| * DES_FAILED: (libc)DES Encryption. |
| * DTTOIF: (libc)Directory Entries. |
| * E2BIG: (libc)Error Codes. |
| * EACCES: (libc)Error Codes. |
| * EADDRINUSE: (libc)Error Codes. |
| * EADDRNOTAVAIL: (libc)Error Codes. |
| * EADV: (libc)Error Codes. |
| * EAFNOSUPPORT: (libc)Error Codes. |
| * EAGAIN: (libc)Error Codes. |
| * EALREADY: (libc)Error Codes. |
| * EAUTH: (libc)Error Codes. |
| * EBACKGROUND: (libc)Error Codes. |
| * EBADE: (libc)Error Codes. |
| * EBADF: (libc)Error Codes. |
| * EBADFD: (libc)Error Codes. |
| * EBADMSG: (libc)Error Codes. |
| * EBADR: (libc)Error Codes. |
| * EBADRPC: (libc)Error Codes. |
| * EBADRQC: (libc)Error Codes. |
| * EBADSLT: (libc)Error Codes. |
| * EBFONT: (libc)Error Codes. |
| * EBUSY: (libc)Error Codes. |
| * ECANCELED: (libc)Error Codes. |
| * ECHILD: (libc)Error Codes. |
| * ECHO: (libc)Local Modes. |
| * ECHOCTL: (libc)Local Modes. |
| * ECHOE: (libc)Local Modes. |
| * ECHOK: (libc)Local Modes. |
| * ECHOKE: (libc)Local Modes. |
| * ECHONL: (libc)Local Modes. |
| * ECHOPRT: (libc)Local Modes. |
| * ECHRNG: (libc)Error Codes. |
| * ECOMM: (libc)Error Codes. |
| * ECONNABORTED: (libc)Error Codes. |
| * ECONNREFUSED: (libc)Error Codes. |
| * ECONNRESET: (libc)Error Codes. |
| * ED: (libc)Error Codes. |
| * EDEADLK: (libc)Error Codes. |
| * EDEADLOCK: (libc)Error Codes. |
| * EDESTADDRREQ: (libc)Error Codes. |
| * EDIED: (libc)Error Codes. |
| * EDOM: (libc)Error Codes. |
| * EDOTDOT: (libc)Error Codes. |
| * EDQUOT: (libc)Error Codes. |
| * EEXIST: (libc)Error Codes. |
| * EFAULT: (libc)Error Codes. |
| * EFBIG: (libc)Error Codes. |
| * EFTYPE: (libc)Error Codes. |
| * EGRATUITOUS: (libc)Error Codes. |
| * EGREGIOUS: (libc)Error Codes. |
| * EHOSTDOWN: (libc)Error Codes. |
| * EHOSTUNREACH: (libc)Error Codes. |
| * EHWPOISON: (libc)Error Codes. |
| * EIDRM: (libc)Error Codes. |
| * EIEIO: (libc)Error Codes. |
| * EILSEQ: (libc)Error Codes. |
| * EINPROGRESS: (libc)Error Codes. |
| * EINTR: (libc)Error Codes. |
| * EINVAL: (libc)Error Codes. |
| * EIO: (libc)Error Codes. |
| * EISCONN: (libc)Error Codes. |
| * EISDIR: (libc)Error Codes. |
| * EISNAM: (libc)Error Codes. |
| * EKEYEXPIRED: (libc)Error Codes. |
| * EKEYREJECTED: (libc)Error Codes. |
| * EKEYREVOKED: (libc)Error Codes. |
| * EL2HLT: (libc)Error Codes. |
| * EL2NSYNC: (libc)Error Codes. |
| * EL3HLT: (libc)Error Codes. |
| * EL3RST: (libc)Error Codes. |
| * ELIBACC: (libc)Error Codes. |
| * ELIBBAD: (libc)Error Codes. |
| * ELIBEXEC: (libc)Error Codes. |
| * ELIBMAX: (libc)Error Codes. |
| * ELIBSCN: (libc)Error Codes. |
| * ELNRNG: (libc)Error Codes. |
| * ELOOP: (libc)Error Codes. |
| * EMEDIUMTYPE: (libc)Error Codes. |
| * EMFILE: (libc)Error Codes. |
| * EMLINK: (libc)Error Codes. |
| * EMSGSIZE: (libc)Error Codes. |
| * EMULTIHOP: (libc)Error Codes. |
| * ENAMETOOLONG: (libc)Error Codes. |
| * ENAVAIL: (libc)Error Codes. |
| * ENEEDAUTH: (libc)Error Codes. |
| * ENETDOWN: (libc)Error Codes. |
| * ENETRESET: (libc)Error Codes. |
| * ENETUNREACH: (libc)Error Codes. |
| * ENFILE: (libc)Error Codes. |
| * ENOANO: (libc)Error Codes. |
| * ENOBUFS: (libc)Error Codes. |
| * ENOCSI: (libc)Error Codes. |
| * ENODATA: (libc)Error Codes. |
| * ENODEV: (libc)Error Codes. |
| * ENOENT: (libc)Error Codes. |
| * ENOEXEC: (libc)Error Codes. |
| * ENOKEY: (libc)Error Codes. |
| * ENOLCK: (libc)Error Codes. |
| * ENOLINK: (libc)Error Codes. |
| * ENOMEDIUM: (libc)Error Codes. |
| * ENOMEM: (libc)Error Codes. |
| * ENOMSG: (libc)Error Codes. |
| * ENONET: (libc)Error Codes. |
| * ENOPKG: (libc)Error Codes. |
| * ENOPROTOOPT: (libc)Error Codes. |
| * ENOSPC: (libc)Error Codes. |
| * ENOSR: (libc)Error Codes. |
| * ENOSTR: (libc)Error Codes. |
| * ENOSYS: (libc)Error Codes. |
| * ENOTBLK: (libc)Error Codes. |
| * ENOTCONN: (libc)Error Codes. |
| * ENOTDIR: (libc)Error Codes. |
| * ENOTEMPTY: (libc)Error Codes. |
| * ENOTNAM: (libc)Error Codes. |
| * ENOTRECOVERABLE: (libc)Error Codes. |
| * ENOTSOCK: (libc)Error Codes. |
| * ENOTSUP: (libc)Error Codes. |
| * ENOTTY: (libc)Error Codes. |
| * ENOTUNIQ: (libc)Error Codes. |
| * ENXIO: (libc)Error Codes. |
| * EOF: (libc)EOF and Errors. |
| * EOPNOTSUPP: (libc)Error Codes. |
| * EOVERFLOW: (libc)Error Codes. |
| * EOWNERDEAD: (libc)Error Codes. |
| * EPERM: (libc)Error Codes. |
| * EPFNOSUPPORT: (libc)Error Codes. |
| * EPIPE: (libc)Error Codes. |
| * EPROCLIM: (libc)Error Codes. |
| * EPROCUNAVAIL: (libc)Error Codes. |
| * EPROGMISMATCH: (libc)Error Codes. |
| * EPROGUNAVAIL: (libc)Error Codes. |
| * EPROTO: (libc)Error Codes. |
| * EPROTONOSUPPORT: (libc)Error Codes. |
| * EPROTOTYPE: (libc)Error Codes. |
| * EQUIV_CLASS_MAX: (libc)Utility Limits. |
| * ERANGE: (libc)Error Codes. |
| * EREMCHG: (libc)Error Codes. |
| * EREMOTE: (libc)Error Codes. |
| * EREMOTEIO: (libc)Error Codes. |
| * ERESTART: (libc)Error Codes. |
| * ERFKILL: (libc)Error Codes. |
| * EROFS: (libc)Error Codes. |
| * ERPCMISMATCH: (libc)Error Codes. |
| * ESHUTDOWN: (libc)Error Codes. |
| * ESOCKTNOSUPPORT: (libc)Error Codes. |
| * ESPIPE: (libc)Error Codes. |
| * ESRCH: (libc)Error Codes. |
| * ESRMNT: (libc)Error Codes. |
| * ESTALE: (libc)Error Codes. |
| * ESTRPIPE: (libc)Error Codes. |
| * ETIME: (libc)Error Codes. |
| * ETIMEDOUT: (libc)Error Codes. |
| * ETOOMANYREFS: (libc)Error Codes. |
| * ETXTBSY: (libc)Error Codes. |
| * EUCLEAN: (libc)Error Codes. |
| * EUNATCH: (libc)Error Codes. |
| * EUSERS: (libc)Error Codes. |
| * EWOULDBLOCK: (libc)Error Codes. |
| * EXDEV: (libc)Error Codes. |
| * EXFULL: (libc)Error Codes. |
| * EXIT_FAILURE: (libc)Exit Status. |
| * EXIT_SUCCESS: (libc)Exit Status. |
| * EXPR_NEST_MAX: (libc)Utility Limits. |
| * FD_CLOEXEC: (libc)Descriptor Flags. |
| * FD_CLR: (libc)Waiting for I/O. |
| * FD_ISSET: (libc)Waiting for I/O. |
| * FD_SET: (libc)Waiting for I/O. |
| * FD_SETSIZE: (libc)Waiting for I/O. |
| * FD_ZERO: (libc)Waiting for I/O. |
| * FILENAME_MAX: (libc)Limits for Files. |
| * FLUSHO: (libc)Local Modes. |
| * FOPEN_MAX: (libc)Opening Streams. |
| * FP_ILOGB0: (libc)Exponents and Logarithms. |
| * FP_ILOGBNAN: (libc)Exponents and Logarithms. |
| * F_DUPFD: (libc)Duplicating Descriptors. |
| * F_GETFD: (libc)Descriptor Flags. |
| * F_GETFL: (libc)Getting File Status Flags. |
| * F_GETLK: (libc)File Locks. |
| * F_GETOWN: (libc)Interrupt Input. |
| * F_OK: (libc)Testing File Access. |
| * F_SETFD: (libc)Descriptor Flags. |
| * F_SETFL: (libc)Getting File Status Flags. |
| * F_SETLK: (libc)File Locks. |
| * F_SETLKW: (libc)File Locks. |
| * F_SETOWN: (libc)Interrupt Input. |
| * HUGE_VAL: (libc)Math Error Reporting. |
| * HUGE_VALF: (libc)Math Error Reporting. |
| * HUGE_VALL: (libc)Math Error Reporting. |
| * HUPCL: (libc)Control Modes. |
| * I: (libc)Complex Numbers. |
| * ICANON: (libc)Local Modes. |
| * ICRNL: (libc)Input Modes. |
| * IEXTEN: (libc)Local Modes. |
| * IFNAMSIZ: (libc)Interface Naming. |
| * IFTODT: (libc)Directory Entries. |
| * IGNBRK: (libc)Input Modes. |
| * IGNCR: (libc)Input Modes. |
| * IGNPAR: (libc)Input Modes. |
| * IMAXBEL: (libc)Input Modes. |
| * INADDR_ANY: (libc)Host Address Data Type. |
| * INADDR_BROADCAST: (libc)Host Address Data Type. |
| * INADDR_LOOPBACK: (libc)Host Address Data Type. |
| * INADDR_NONE: (libc)Host Address Data Type. |
| * INFINITY: (libc)Infinity and NaN. |
| * INLCR: (libc)Input Modes. |
| * INPCK: (libc)Input Modes. |
| * IPPORT_RESERVED: (libc)Ports. |
| * IPPORT_USERRESERVED: (libc)Ports. |
| * ISIG: (libc)Local Modes. |
| * ISTRIP: (libc)Input Modes. |
| * IXANY: (libc)Input Modes. |
| * IXOFF: (libc)Input Modes. |
| * IXON: (libc)Input Modes. |
| * LINE_MAX: (libc)Utility Limits. |
| * LINK_MAX: (libc)Limits for Files. |
| * L_ctermid: (libc)Identifying the Terminal. |
| * L_cuserid: (libc)Who Logged In. |
| * L_tmpnam: (libc)Temporary Files. |
| * MAXNAMLEN: (libc)Limits for Files. |
| * MAXSYMLINKS: (libc)Symbolic Links. |
| * MAX_CANON: (libc)Limits for Files. |
| * MAX_INPUT: (libc)Limits for Files. |
| * MB_CUR_MAX: (libc)Selecting the Conversion. |
| * MB_LEN_MAX: (libc)Selecting the Conversion. |
| * MDMBUF: (libc)Control Modes. |
| * MSG_DONTROUTE: (libc)Socket Data Options. |
| * MSG_OOB: (libc)Socket Data Options. |
| * MSG_PEEK: (libc)Socket Data Options. |
| * NAME_MAX: (libc)Limits for Files. |
| * NAN: (libc)Infinity and NaN. |
| * NCCS: (libc)Mode Data Types. |
| * NGROUPS_MAX: (libc)General Limits. |
| * NOFLSH: (libc)Local Modes. |
| * NOKERNINFO: (libc)Local Modes. |
| * NSIG: (libc)Standard Signals. |
| * NULL: (libc)Null Pointer Constant. |
| * ONLCR: (libc)Output Modes. |
| * ONOEOT: (libc)Output Modes. |
| * OPEN_MAX: (libc)General Limits. |
| * OPOST: (libc)Output Modes. |
| * OXTABS: (libc)Output Modes. |
| * O_ACCMODE: (libc)Access Modes. |
| * O_APPEND: (libc)Operating Modes. |
| * O_ASYNC: (libc)Operating Modes. |
| * O_CREAT: (libc)Open-time Flags. |
| * O_EXCL: (libc)Open-time Flags. |
| * O_EXEC: (libc)Access Modes. |
| * O_EXLOCK: (libc)Open-time Flags. |
| * O_FSYNC: (libc)Operating Modes. |
| * O_IGNORE_CTTY: (libc)Open-time Flags. |
| * O_NDELAY: (libc)Operating Modes. |
| * O_NOATIME: (libc)Operating Modes. |
| * O_NOCTTY: (libc)Open-time Flags. |
| * O_NOLINK: (libc)Open-time Flags. |
| * O_NONBLOCK: (libc)Open-time Flags. |
| * O_NONBLOCK: (libc)Operating Modes. |
| * O_NOTRANS: (libc)Open-time Flags. |
| * O_RDONLY: (libc)Access Modes. |
| * O_RDWR: (libc)Access Modes. |
| * O_READ: (libc)Access Modes. |
| * O_SHLOCK: (libc)Open-time Flags. |
| * O_SYNC: (libc)Operating Modes. |
| * O_TRUNC: (libc)Open-time Flags. |
| * O_WRITE: (libc)Access Modes. |
| * O_WRONLY: (libc)Access Modes. |
| * PARENB: (libc)Control Modes. |
| * PARMRK: (libc)Input Modes. |
| * PARODD: (libc)Control Modes. |
| * PATH_MAX: (libc)Limits for Files. |
| * PA_FLAG_MASK: (libc)Parsing a Template String. |
| * PENDIN: (libc)Local Modes. |
| * PF_FILE: (libc)Local Namespace Details. |
| * PF_INET6: (libc)Internet Namespace. |
| * PF_INET: (libc)Internet Namespace. |
| * PF_LOCAL: (libc)Local Namespace Details. |
| * PF_UNIX: (libc)Local Namespace Details. |
| * PIPE_BUF: (libc)Limits for Files. |
| * P_tmpdir: (libc)Temporary Files. |
| * RAND_MAX: (libc)ISO Random. |
| * RE_DUP_MAX: (libc)General Limits. |
| * RLIM_INFINITY: (libc)Limits on Resources. |
| * R_OK: (libc)Testing File Access. |
| * SA_NOCLDSTOP: (libc)Flags for Sigaction. |
| * SA_ONSTACK: (libc)Flags for Sigaction. |
| * SA_RESTART: (libc)Flags for Sigaction. |
| * SEEK_CUR: (libc)File Positioning. |
| * SEEK_END: (libc)File Positioning. |
| * SEEK_SET: (libc)File Positioning. |
| * SIGABRT: (libc)Program Error Signals. |
| * SIGALRM: (libc)Alarm Signals. |
| * SIGBUS: (libc)Program Error Signals. |
| * SIGCHLD: (libc)Job Control Signals. |
| * SIGCLD: (libc)Job Control Signals. |
| * SIGCONT: (libc)Job Control Signals. |
| * SIGEMT: (libc)Program Error Signals. |
| * SIGFPE: (libc)Program Error Signals. |
| * SIGHUP: (libc)Termination Signals. |
| * SIGILL: (libc)Program Error Signals. |
| * SIGINFO: (libc)Miscellaneous Signals. |
| * SIGINT: (libc)Termination Signals. |
| * SIGIO: (libc)Asynchronous I/O Signals. |
| * SIGIOT: (libc)Program Error Signals. |
| * SIGKILL: (libc)Termination Signals. |
| * SIGLOST: (libc)Operation Error Signals. |
| * SIGPIPE: (libc)Operation Error Signals. |
| * SIGPOLL: (libc)Asynchronous I/O Signals. |
| * SIGPROF: (libc)Alarm Signals. |
| * SIGQUIT: (libc)Termination Signals. |
| * SIGSEGV: (libc)Program Error Signals. |
| * SIGSTOP: (libc)Job Control Signals. |
| * SIGSYS: (libc)Program Error Signals. |
| * SIGTERM: (libc)Termination Signals. |
| * SIGTRAP: (libc)Program Error Signals. |
| * SIGTSTP: (libc)Job Control Signals. |
| * SIGTTIN: (libc)Job Control Signals. |
| * SIGTTOU: (libc)Job Control Signals. |
| * SIGURG: (libc)Asynchronous I/O Signals. |
| * SIGUSR1: (libc)Miscellaneous Signals. |
| * SIGUSR2: (libc)Miscellaneous Signals. |
| * SIGVTALRM: (libc)Alarm Signals. |
| * SIGWINCH: (libc)Miscellaneous Signals. |
| * SIGXCPU: (libc)Operation Error Signals. |
| * SIGXFSZ: (libc)Operation Error Signals. |
| * SIG_ERR: (libc)Basic Signal Handling. |
| * SOCK_DGRAM: (libc)Communication Styles. |
| * SOCK_RAW: (libc)Communication Styles. |
| * SOCK_RDM: (libc)Communication Styles. |
| * SOCK_SEQPACKET: (libc)Communication Styles. |
| * SOCK_STREAM: (libc)Communication Styles. |
| * SOL_SOCKET: (libc)Socket-Level Options. |
| * SSIZE_MAX: (libc)General Limits. |
| * STREAM_MAX: (libc)General Limits. |
| * SUN_LEN: (libc)Local Namespace Details. |
| * SV_INTERRUPT: (libc)BSD Handler. |
| * SV_ONSTACK: (libc)BSD Handler. |
| * SV_RESETHAND: (libc)BSD Handler. |
| * S_IFMT: (libc)Testing File Type. |
| * S_ISBLK: (libc)Testing File Type. |
| * S_ISCHR: (libc)Testing File Type. |
| * S_ISDIR: (libc)Testing File Type. |
| * S_ISFIFO: (libc)Testing File Type. |
| * S_ISLNK: (libc)Testing File Type. |
| * S_ISREG: (libc)Testing File Type. |
| * S_ISSOCK: (libc)Testing File Type. |
| * S_TYPEISMQ: (libc)Testing File Type. |
| * S_TYPEISSEM: (libc)Testing File Type. |
| * S_TYPEISSHM: (libc)Testing File Type. |
| * TMP_MAX: (libc)Temporary Files. |
| * TOSTOP: (libc)Local Modes. |
| * TZNAME_MAX: (libc)General Limits. |
| * VDISCARD: (libc)Other Special. |
| * VDSUSP: (libc)Signal Characters. |
| * VEOF: (libc)Editing Characters. |
| * VEOL2: (libc)Editing Characters. |
| * VEOL: (libc)Editing Characters. |
| * VERASE: (libc)Editing Characters. |
| * VINTR: (libc)Signal Characters. |
| * VKILL: (libc)Editing Characters. |
| * VLNEXT: (libc)Other Special. |
| * VMIN: (libc)Noncanonical Input. |
| * VQUIT: (libc)Signal Characters. |
| * VREPRINT: (libc)Editing Characters. |
| * VSTART: (libc)Start/Stop Characters. |
| * VSTATUS: (libc)Other Special. |
| * VSTOP: (libc)Start/Stop Characters. |
| * VSUSP: (libc)Signal Characters. |
| * VTIME: (libc)Noncanonical Input. |
| * VWERASE: (libc)Editing Characters. |
| * WCHAR_MAX: (libc)Extended Char Intro. |
| * WCHAR_MIN: (libc)Extended Char Intro. |
| * WCOREDUMP: (libc)Process Completion Status. |
| * WEOF: (libc)EOF and Errors. |
| * WEOF: (libc)Extended Char Intro. |
| * WEXITSTATUS: (libc)Process Completion Status. |
| * WIFEXITED: (libc)Process Completion Status. |
| * WIFSIGNALED: (libc)Process Completion Status. |
| * WIFSTOPPED: (libc)Process Completion Status. |
| * WSTOPSIG: (libc)Process Completion Status. |
| * WTERMSIG: (libc)Process Completion Status. |
| * W_OK: (libc)Testing File Access. |
| * X_OK: (libc)Testing File Access. |
| * _Complex_I: (libc)Complex Numbers. |
| * _Exit: (libc)Termination Internals. |
| * _IOFBF: (libc)Controlling Buffering. |
| * _IOLBF: (libc)Controlling Buffering. |
| * _IONBF: (libc)Controlling Buffering. |
| * _Imaginary_I: (libc)Complex Numbers. |
| * _PATH_UTMP: (libc)Manipulating the Database. |
| * _PATH_WTMP: (libc)Manipulating the Database. |
| * _POSIX2_C_DEV: (libc)System Options. |
| * _POSIX2_C_VERSION: (libc)Version Supported. |
| * _POSIX2_FORT_DEV: (libc)System Options. |
| * _POSIX2_FORT_RUN: (libc)System Options. |
| * _POSIX2_LOCALEDEF: (libc)System Options. |
| * _POSIX2_SW_DEV: (libc)System Options. |
| * _POSIX_CHOWN_RESTRICTED: (libc)Options for Files. |
| * _POSIX_JOB_CONTROL: (libc)System Options. |
| * _POSIX_NO_TRUNC: (libc)Options for Files. |
| * _POSIX_SAVED_IDS: (libc)System Options. |
| * _POSIX_VDISABLE: (libc)Options for Files. |
| * _POSIX_VERSION: (libc)Version Supported. |
| * __fbufsize: (libc)Controlling Buffering. |
| * __flbf: (libc)Controlling Buffering. |
| * __fpending: (libc)Controlling Buffering. |
| * __fpurge: (libc)Flushing Buffers. |
| * __freadable: (libc)Opening Streams. |
| * __freading: (libc)Opening Streams. |
| * __fsetlocking: (libc)Streams and Threads. |
| * __fwritable: (libc)Opening Streams. |
| * __fwriting: (libc)Opening Streams. |
| * __gconv_end_fct: (libc)glibc iconv Implementation. |
| * __gconv_fct: (libc)glibc iconv Implementation. |
| * __gconv_init_fct: (libc)glibc iconv Implementation. |
| * __ppc_get_timebase: (libc)PowerPC. |
| * __ppc_get_timebase_freq: (libc)PowerPC. |
| * __ppc_mdoio: (libc)PowerPC. |
| * __ppc_mdoom: (libc)PowerPC. |
| * __ppc_set_ppr_low: (libc)PowerPC. |
| * __ppc_set_ppr_med: (libc)PowerPC. |
| * __ppc_set_ppr_med_low: (libc)PowerPC. |
| * __ppc_yield: (libc)PowerPC. |
| * __va_copy: (libc)Argument Macros. |
| * _exit: (libc)Termination Internals. |
| * _flushlbf: (libc)Flushing Buffers. |
| * _tolower: (libc)Case Conversion. |
| * _toupper: (libc)Case Conversion. |
| * a64l: (libc)Encode Binary Data. |
| * abort: (libc)Aborting a Program. |
| * abs: (libc)Absolute Value. |
| * accept: (libc)Accepting Connections. |
| * access: (libc)Testing File Access. |
| * acos: (libc)Inverse Trig Functions. |
| * acosf: (libc)Inverse Trig Functions. |
| * acosh: (libc)Hyperbolic Functions. |
| * acoshf: (libc)Hyperbolic Functions. |
| * acoshl: (libc)Hyperbolic Functions. |
| * acosl: (libc)Inverse Trig Functions. |
| * addmntent: (libc)mtab. |
| * addseverity: (libc)Adding Severity Classes. |
| * adjtime: (libc)High-Resolution Calendar. |
| * adjtimex: (libc)High-Resolution Calendar. |
| * aio_cancel64: (libc)Cancel AIO Operations. |
| * aio_cancel: (libc)Cancel AIO Operations. |
| * aio_error64: (libc)Status of AIO Operations. |
| * aio_error: (libc)Status of AIO Operations. |
| * aio_fsync64: (libc)Synchronizing AIO Operations. |
| * aio_fsync: (libc)Synchronizing AIO Operations. |
| * aio_init: (libc)Configuration of AIO. |
| * aio_read64: (libc)Asynchronous Reads/Writes. |
| * aio_read: (libc)Asynchronous Reads/Writes. |
| * aio_return64: (libc)Status of AIO Operations. |
| * aio_return: (libc)Status of AIO Operations. |
| * aio_suspend64: (libc)Synchronizing AIO Operations. |
| * aio_suspend: (libc)Synchronizing AIO Operations. |
| * aio_write64: (libc)Asynchronous Reads/Writes. |
| * aio_write: (libc)Asynchronous Reads/Writes. |
| * alarm: (libc)Setting an Alarm. |
| * aligned_alloc: (libc)Aligned Memory Blocks. |
| * alloca: (libc)Variable Size Automatic. |
| * alphasort64: (libc)Scanning Directory Content. |
| * alphasort: (libc)Scanning Directory Content. |
| * argp_error: (libc)Argp Helper Functions. |
| * argp_failure: (libc)Argp Helper Functions. |
| * argp_help: (libc)Argp Help. |
| * argp_parse: (libc)Argp. |
| * argp_state_help: (libc)Argp Helper Functions. |
| * argp_usage: (libc)Argp Helper Functions. |
| * argz_add: (libc)Argz Functions. |
| * argz_add_sep: (libc)Argz Functions. |
| * argz_append: (libc)Argz Functions. |
| * argz_count: (libc)Argz Functions. |
| * argz_create: (libc)Argz Functions. |
| * argz_create_sep: (libc)Argz Functions. |
| * argz_delete: (libc)Argz Functions. |
| * argz_extract: (libc)Argz Functions. |
| * argz_insert: (libc)Argz Functions. |
| * argz_next: (libc)Argz Functions. |
| * argz_replace: (libc)Argz Functions. |
| * argz_stringify: (libc)Argz Functions. |
| * asctime: (libc)Formatting Calendar Time. |
| * asctime_r: (libc)Formatting Calendar Time. |
| * asin: (libc)Inverse Trig Functions. |
| * asinf: (libc)Inverse Trig Functions. |
| * asinh: (libc)Hyperbolic Functions. |
| * asinhf: (libc)Hyperbolic Functions. |
| * asinhl: (libc)Hyperbolic Functions. |
| * asinl: (libc)Inverse Trig Functions. |
| * asprintf: (libc)Dynamic Output. |
| * assert: (libc)Consistency Checking. |
| * assert_perror: (libc)Consistency Checking. |
| * atan2: (libc)Inverse Trig Functions. |
| * atan2f: (libc)Inverse Trig Functions. |
| * atan2l: (libc)Inverse Trig Functions. |
| * atan: (libc)Inverse Trig Functions. |
| * atanf: (libc)Inverse Trig Functions. |
| * atanh: (libc)Hyperbolic Functions. |
| * atanhf: (libc)Hyperbolic Functions. |
| * atanhl: (libc)Hyperbolic Functions. |
| * atanl: (libc)Inverse Trig Functions. |
| * atexit: (libc)Cleanups on Exit. |
| * atof: (libc)Parsing of Floats. |
| * atoi: (libc)Parsing of Integers. |
| * atol: (libc)Parsing of Integers. |
| * atoll: (libc)Parsing of Integers. |
| * backtrace: (libc)Backtraces. |
| * backtrace_symbols: (libc)Backtraces. |
| * backtrace_symbols_fd: (libc)Backtraces. |
| * basename: (libc)Finding Tokens in a String. |
| * basename: (libc)Finding Tokens in a String. |
| * bcmp: (libc)String/Array Comparison. |
| * bcopy: (libc)Copying and Concatenation. |
| * bind: (libc)Setting Address. |
| * bind_textdomain_codeset: (libc)Charset conversion in gettext. |
| * bindtextdomain: (libc)Locating gettext catalog. |
| * brk: (libc)Resizing the Data Segment. |
| * bsearch: (libc)Array Search Function. |
| * btowc: (libc)Converting a Character. |
| * bzero: (libc)Copying and Concatenation. |
| * cabs: (libc)Absolute Value. |
| * cabsf: (libc)Absolute Value. |
| * cabsl: (libc)Absolute Value. |
| * cacos: (libc)Inverse Trig Functions. |
| * cacosf: (libc)Inverse Trig Functions. |
| * cacosh: (libc)Hyperbolic Functions. |
| * cacoshf: (libc)Hyperbolic Functions. |
| * cacoshl: (libc)Hyperbolic Functions. |
| * cacosl: (libc)Inverse Trig Functions. |
| * calloc: (libc)Allocating Cleared Space. |
| * canonicalize_file_name: (libc)Symbolic Links. |
| * carg: (libc)Operations on Complex. |
| * cargf: (libc)Operations on Complex. |
| * cargl: (libc)Operations on Complex. |
| * casin: (libc)Inverse Trig Functions. |
| * casinf: (libc)Inverse Trig Functions. |
| * casinh: (libc)Hyperbolic Functions. |
| * casinhf: (libc)Hyperbolic Functions. |
| * casinhl: (libc)Hyperbolic Functions. |
| * casinl: (libc)Inverse Trig Functions. |
| * catan: (libc)Inverse Trig Functions. |
| * catanf: (libc)Inverse Trig Functions. |
| * catanh: (libc)Hyperbolic Functions. |
| * catanhf: (libc)Hyperbolic Functions. |
| * catanhl: (libc)Hyperbolic Functions. |
| * catanl: (libc)Inverse Trig Functions. |
| * catclose: (libc)The catgets Functions. |
| * catgets: (libc)The catgets Functions. |
| * catopen: (libc)The catgets Functions. |
| * cbc_crypt: (libc)DES Encryption. |
| * cbrt: (libc)Exponents and Logarithms. |
| * cbrtf: (libc)Exponents and Logarithms. |
| * cbrtl: (libc)Exponents and Logarithms. |
| * ccos: (libc)Trig Functions. |
| * ccosf: (libc)Trig Functions. |
| * ccosh: (libc)Hyperbolic Functions. |
| * ccoshf: (libc)Hyperbolic Functions. |
| * ccoshl: (libc)Hyperbolic Functions. |
| * ccosl: (libc)Trig Functions. |
| * ceil: (libc)Rounding Functions. |
| * ceilf: (libc)Rounding Functions. |
| * ceill: (libc)Rounding Functions. |
| * cexp: (libc)Exponents and Logarithms. |
| * cexpf: (libc)Exponents and Logarithms. |
| * cexpl: (libc)Exponents and Logarithms. |
| * cfgetispeed: (libc)Line Speed. |
| * cfgetospeed: (libc)Line Speed. |
| * cfmakeraw: (libc)Noncanonical Input. |
| * cfree: (libc)Freeing after Malloc. |
| * cfsetispeed: (libc)Line Speed. |
| * cfsetospeed: (libc)Line Speed. |
| * cfsetspeed: (libc)Line Speed. |
| * chdir: (libc)Working Directory. |
| * chmod: (libc)Setting Permissions. |
| * chown: (libc)File Owner. |
| * cimag: (libc)Operations on Complex. |
| * cimagf: (libc)Operations on Complex. |
| * cimagl: (libc)Operations on Complex. |
| * clearenv: (libc)Environment Access. |
| * clearerr: (libc)Error Recovery. |
| * clearerr_unlocked: (libc)Error Recovery. |
| * clock: (libc)CPU Time. |
| * clog10: (libc)Exponents and Logarithms. |
| * clog10f: (libc)Exponents and Logarithms. |
| * clog10l: (libc)Exponents and Logarithms. |
| * clog: (libc)Exponents and Logarithms. |
| * clogf: (libc)Exponents and Logarithms. |
| * clogl: (libc)Exponents and Logarithms. |
| * close: (libc)Opening and Closing Files. |
| * closedir: (libc)Reading/Closing Directory. |
| * closelog: (libc)closelog. |
| * confstr: (libc)String Parameters. |
| * conj: (libc)Operations on Complex. |
| * conjf: (libc)Operations on Complex. |
| * conjl: (libc)Operations on Complex. |
| * connect: (libc)Connecting. |
| * copysign: (libc)FP Bit Twiddling. |
| * copysignf: (libc)FP Bit Twiddling. |
| * copysignl: (libc)FP Bit Twiddling. |
| * cos: (libc)Trig Functions. |
| * cosf: (libc)Trig Functions. |
| * cosh: (libc)Hyperbolic Functions. |
| * coshf: (libc)Hyperbolic Functions. |
| * coshl: (libc)Hyperbolic Functions. |
| * cosl: (libc)Trig Functions. |
| * cpow: (libc)Exponents and Logarithms. |
| * cpowf: (libc)Exponents and Logarithms. |
| * cpowl: (libc)Exponents and Logarithms. |
| * cproj: (libc)Operations on Complex. |
| * cprojf: (libc)Operations on Complex. |
| * cprojl: (libc)Operations on Complex. |
| * creal: (libc)Operations on Complex. |
| * crealf: (libc)Operations on Complex. |
| * creall: (libc)Operations on Complex. |
| * creat64: (libc)Opening and Closing Files. |
| * creat: (libc)Opening and Closing Files. |
| * crypt: (libc)crypt. |
| * crypt_r: (libc)crypt. |
| * csin: (libc)Trig Functions. |
| * csinf: (libc)Trig Functions. |
| * csinh: (libc)Hyperbolic Functions. |
| * csinhf: (libc)Hyperbolic Functions. |
| * csinhl: (libc)Hyperbolic Functions. |
| * csinl: (libc)Trig Functions. |
| * csqrt: (libc)Exponents and Logarithms. |
| * csqrtf: (libc)Exponents and Logarithms. |
| * csqrtl: (libc)Exponents and Logarithms. |
| * ctan: (libc)Trig Functions. |
| * ctanf: (libc)Trig Functions. |
| * ctanh: (libc)Hyperbolic Functions. |
| * ctanhf: (libc)Hyperbolic Functions. |
| * ctanhl: (libc)Hyperbolic Functions. |
| * ctanl: (libc)Trig Functions. |
| * ctermid: (libc)Identifying the Terminal. |
| * ctime: (libc)Formatting Calendar Time. |
| * ctime_r: (libc)Formatting Calendar Time. |
| * cuserid: (libc)Who Logged In. |
| * dcgettext: (libc)Translation with gettext. |
| * dcngettext: (libc)Advanced gettext functions. |
| * des_setparity: (libc)DES Encryption. |
| * dgettext: (libc)Translation with gettext. |
| * difftime: (libc)Elapsed Time. |
| * dirfd: (libc)Opening a Directory. |
| * dirname: (libc)Finding Tokens in a String. |
| * div: (libc)Integer Division. |
| * dngettext: (libc)Advanced gettext functions. |
| * drand48: (libc)SVID Random. |
| * drand48_r: (libc)SVID Random. |
| * drem: (libc)Remainder Functions. |
| * dremf: (libc)Remainder Functions. |
| * dreml: (libc)Remainder Functions. |
| * dup2: (libc)Duplicating Descriptors. |
| * dup: (libc)Duplicating Descriptors. |
| * ecb_crypt: (libc)DES Encryption. |
| * ecvt: (libc)System V Number Conversion. |
| * ecvt_r: (libc)System V Number Conversion. |
| * encrypt: (libc)DES Encryption. |
| * encrypt_r: (libc)DES Encryption. |
| * endfsent: (libc)fstab. |
| * endgrent: (libc)Scanning All Groups. |
| * endhostent: (libc)Host Names. |
| * endmntent: (libc)mtab. |
| * endnetent: (libc)Networks Database. |
| * endnetgrent: (libc)Lookup Netgroup. |
| * endprotoent: (libc)Protocols Database. |
| * endpwent: (libc)Scanning All Users. |
| * endservent: (libc)Services Database. |
| * endutent: (libc)Manipulating the Database. |
| * endutxent: (libc)XPG Functions. |
| * envz_add: (libc)Envz Functions. |
| * envz_entry: (libc)Envz Functions. |
| * envz_get: (libc)Envz Functions. |
| * envz_merge: (libc)Envz Functions. |
| * envz_strip: (libc)Envz Functions. |
| * erand48: (libc)SVID Random. |
| * erand48_r: (libc)SVID Random. |
| * erf: (libc)Special Functions. |
| * erfc: (libc)Special Functions. |
| * erfcf: (libc)Special Functions. |
| * erfcl: (libc)Special Functions. |
| * erff: (libc)Special Functions. |
| * erfl: (libc)Special Functions. |
| * err: (libc)Error Messages. |
| * errno: (libc)Checking for Errors. |
| * error: (libc)Error Messages. |
| * error_at_line: (libc)Error Messages. |
| * errx: (libc)Error Messages. |
| * execl: (libc)Executing a File. |
| * execle: (libc)Executing a File. |
| * execlp: (libc)Executing a File. |
| * execv: (libc)Executing a File. |
| * execve: (libc)Executing a File. |
| * execvp: (libc)Executing a File. |
| * exit: (libc)Normal Termination. |
| * exp10: (libc)Exponents and Logarithms. |
| * exp10f: (libc)Exponents and Logarithms. |
| * exp10l: (libc)Exponents and Logarithms. |
| * exp2: (libc)Exponents and Logarithms. |
| * exp2f: (libc)Exponents and Logarithms. |
| * exp2l: (libc)Exponents and Logarithms. |
| * exp: (libc)Exponents and Logarithms. |
| * expf: (libc)Exponents and Logarithms. |
| * expl: (libc)Exponents and Logarithms. |
| * expm1: (libc)Exponents and Logarithms. |
| * expm1f: (libc)Exponents and Logarithms. |
| * expm1l: (libc)Exponents and Logarithms. |
| * fabs: (libc)Absolute Value. |
| * fabsf: (libc)Absolute Value. |
| * fabsl: (libc)Absolute Value. |
| * fchdir: (libc)Working Directory. |
| * fchmod: (libc)Setting Permissions. |
| * fchown: (libc)File Owner. |
| * fclose: (libc)Closing Streams. |
| * fcloseall: (libc)Closing Streams. |
| * fcntl: (libc)Control Operations. |
| * fcvt: (libc)System V Number Conversion. |
| * fcvt_r: (libc)System V Number Conversion. |
| * fdatasync: (libc)Synchronizing I/O. |
| * fdim: (libc)Misc FP Arithmetic. |
| * fdimf: (libc)Misc FP Arithmetic. |
| * fdiml: (libc)Misc FP Arithmetic. |
| * fdopen: (libc)Descriptors and Streams. |
| * fdopendir: (libc)Opening a Directory. |
| * feclearexcept: (libc)Status bit operations. |
| * fedisableexcept: (libc)Control Functions. |
| * feenableexcept: (libc)Control Functions. |
| * fegetenv: (libc)Control Functions. |
| * fegetexcept: (libc)Control Functions. |
| * fegetexceptflag: (libc)Status bit operations. |
| * fegetround: (libc)Rounding. |
| * feholdexcept: (libc)Control Functions. |
| * feof: (libc)EOF and Errors. |
| * feof_unlocked: (libc)EOF and Errors. |
| * feraiseexcept: (libc)Status bit operations. |
| * ferror: (libc)EOF and Errors. |
| * ferror_unlocked: (libc)EOF and Errors. |
| * fesetenv: (libc)Control Functions. |
| * fesetexceptflag: (libc)Status bit operations. |
| * fesetround: (libc)Rounding. |
| * fetestexcept: (libc)Status bit operations. |
| * feupdateenv: (libc)Control Functions. |
| * fflush: (libc)Flushing Buffers. |
| * fflush_unlocked: (libc)Flushing Buffers. |
| * fgetc: (libc)Character Input. |
| * fgetc_unlocked: (libc)Character Input. |
| * fgetgrent: (libc)Scanning All Groups. |
| * fgetgrent_r: (libc)Scanning All Groups. |
| * fgetpos64: (libc)Portable Positioning. |
| * fgetpos: (libc)Portable Positioning. |
| * fgetpwent: (libc)Scanning All Users. |
| * fgetpwent_r: (libc)Scanning All Users. |
| * fgets: (libc)Line Input. |
| * fgets_unlocked: (libc)Line Input. |
| * fgetwc: (libc)Character Input. |
| * fgetwc_unlocked: (libc)Character Input. |
| * fgetws: (libc)Line Input. |
| * fgetws_unlocked: (libc)Line Input. |
| * fileno: (libc)Descriptors and Streams. |
| * fileno_unlocked: (libc)Descriptors and Streams. |
| * finite: (libc)Floating Point Classes. |
| * finitef: (libc)Floating Point Classes. |
| * finitel: (libc)Floating Point Classes. |
| * flockfile: (libc)Streams and Threads. |
| * floor: (libc)Rounding Functions. |
| * floorf: (libc)Rounding Functions. |
| * floorl: (libc)Rounding Functions. |
| * fma: (libc)Misc FP Arithmetic. |
| * fmaf: (libc)Misc FP Arithmetic. |
| * fmal: (libc)Misc FP Arithmetic. |
| * fmax: (libc)Misc FP Arithmetic. |
| * fmaxf: (libc)Misc FP Arithmetic. |
| * fmaxl: (libc)Misc FP Arithmetic. |
| * fmemopen: (libc)String Streams. |
| * fmin: (libc)Misc FP Arithmetic. |
| * fminf: (libc)Misc FP Arithmetic. |
| * fminl: (libc)Misc FP Arithmetic. |
| * fmod: (libc)Remainder Functions. |
| * fmodf: (libc)Remainder Functions. |
| * fmodl: (libc)Remainder Functions. |
| * fmtmsg: (libc)Printing Formatted Messages. |
| * fnmatch: (libc)Wildcard Matching. |
| * fopen64: (libc)Opening Streams. |
| * fopen: (libc)Opening Streams. |
| * fopencookie: (libc)Streams and Cookies. |
| * fork: (libc)Creating a Process. |
| * forkpty: (libc)Pseudo-Terminal Pairs. |
| * fpathconf: (libc)Pathconf. |
| * fpclassify: (libc)Floating Point Classes. |
| * fprintf: (libc)Formatted Output Functions. |
| * fputc: (libc)Simple Output. |
| * fputc_unlocked: (libc)Simple Output. |
| * fputs: (libc)Simple Output. |
| * fputs_unlocked: (libc)Simple Output. |
| * fputwc: (libc)Simple Output. |
| * fputwc_unlocked: (libc)Simple Output. |
| * fputws: (libc)Simple Output. |
| * fputws_unlocked: (libc)Simple Output. |
| * fread: (libc)Block Input/Output. |
| * fread_unlocked: (libc)Block Input/Output. |
| * free: (libc)Freeing after Malloc. |
| * freopen64: (libc)Opening Streams. |
| * freopen: (libc)Opening Streams. |
| * frexp: (libc)Normalization Functions. |
| * frexpf: (libc)Normalization Functions. |
| * frexpl: (libc)Normalization Functions. |
| * fscanf: (libc)Formatted Input Functions. |
| * fseek: (libc)File Positioning. |
| * fseeko64: (libc)File Positioning. |
| * fseeko: (libc)File Positioning. |
| * fsetpos64: (libc)Portable Positioning. |
| * fsetpos: (libc)Portable Positioning. |
| * fstat64: (libc)Reading Attributes. |
| * fstat: (libc)Reading Attributes. |
| * fsync: (libc)Synchronizing I/O. |
| * ftell: (libc)File Positioning. |
| * ftello64: (libc)File Positioning. |
| * ftello: (libc)File Positioning. |
| * ftruncate64: (libc)File Size. |
| * ftruncate: (libc)File Size. |
| * ftrylockfile: (libc)Streams and Threads. |
| * ftw64: (libc)Working with Directory Trees. |
| * ftw: (libc)Working with Directory Trees. |
| * funlockfile: (libc)Streams and Threads. |
| * futimes: (libc)File Times. |
| * fwide: (libc)Streams and I18N. |
| * fwprintf: (libc)Formatted Output Functions. |
| * fwrite: (libc)Block Input/Output. |
| * fwrite_unlocked: (libc)Block Input/Output. |
| * fwscanf: (libc)Formatted Input Functions. |
| * gamma: (libc)Special Functions. |
| * gammaf: (libc)Special Functions. |
| * gammal: (libc)Special Functions. |
| * gcvt: (libc)System V Number Conversion. |
| * get_avphys_pages: (libc)Query Memory Parameters. |
| * get_current_dir_name: (libc)Working Directory. |
| * get_nprocs: (libc)Processor Resources. |
| * get_nprocs_conf: (libc)Processor Resources. |
| * get_phys_pages: (libc)Query Memory Parameters. |
| * getauxval: (libc)Auxiliary Vector. |
| * getc: (libc)Character Input. |
| * getc_unlocked: (libc)Character Input. |
| * getchar: (libc)Character Input. |
| * getchar_unlocked: (libc)Character Input. |
| * getcontext: (libc)System V contexts. |
| * getcwd: (libc)Working Directory. |
| * getdate: (libc)General Time String Parsing. |
| * getdate_r: (libc)General Time String Parsing. |
| * getdelim: (libc)Line Input. |
| * getdomainnname: (libc)Host Identification. |
| * getegid: (libc)Reading Persona. |
| * getenv: (libc)Environment Access. |
| * geteuid: (libc)Reading Persona. |
| * getfsent: (libc)fstab. |
| * getfsfile: (libc)fstab. |
| * getfsspec: (libc)fstab. |
| * getgid: (libc)Reading Persona. |
| * getgrent: (libc)Scanning All Groups. |
| * getgrent_r: (libc)Scanning All Groups. |
| * getgrgid: (libc)Lookup Group. |
| * getgrgid_r: (libc)Lookup Group. |
| * getgrnam: (libc)Lookup Group. |
| * getgrnam_r: (libc)Lookup Group. |
| * getgrouplist: (libc)Setting Groups. |
| * getgroups: (libc)Reading Persona. |
| * gethostbyaddr: (libc)Host Names. |
| * gethostbyaddr_r: (libc)Host Names. |
| * gethostbyname2: (libc)Host Names. |
| * gethostbyname2_r: (libc)Host Names. |
| * gethostbyname: (libc)Host Names. |
| * gethostbyname_r: (libc)Host Names. |
| * gethostent: (libc)Host Names. |
| * gethostid: (libc)Host Identification. |
| * gethostname: (libc)Host Identification. |
| * getitimer: (libc)Setting an Alarm. |
| * getline: (libc)Line Input. |
| * getloadavg: (libc)Processor Resources. |
| * getlogin: (libc)Who Logged In. |
| * getmntent: (libc)mtab. |
| * getmntent_r: (libc)mtab. |
| * getnetbyaddr: (libc)Networks Database. |
| * getnetbyname: (libc)Networks Database. |
| * getnetent: (libc)Networks Database. |
| * getnetgrent: (libc)Lookup Netgroup. |
| * getnetgrent_r: (libc)Lookup Netgroup. |
| * getopt: (libc)Using Getopt. |
| * getopt_long: (libc)Getopt Long Options. |
| * getopt_long_only: (libc)Getopt Long Options. |
| * getpagesize: (libc)Query Memory Parameters. |
| * getpass: (libc)getpass. |
| * getpeername: (libc)Who is Connected. |
| * getpgid: (libc)Process Group Functions. |
| * getpgrp: (libc)Process Group Functions. |
| * getpid: (libc)Process Identification. |
| * getppid: (libc)Process Identification. |
| * getpriority: (libc)Traditional Scheduling Functions. |
| * getprotobyname: (libc)Protocols Database. |
| * getprotobynumber: (libc)Protocols Database. |
| * getprotoent: (libc)Protocols Database. |
| * getpt: (libc)Allocation. |
| * getpwent: (libc)Scanning All Users. |
| * getpwent_r: (libc)Scanning All Users. |
| * getpwnam: (libc)Lookup User. |
| * getpwnam_r: (libc)Lookup User. |
| * getpwuid: (libc)Lookup User. |
| * getpwuid_r: (libc)Lookup User. |
| * getrlimit64: (libc)Limits on Resources. |
| * getrlimit: (libc)Limits on Resources. |
| * getrusage: (libc)Resource Usage. |
| * gets: (libc)Line Input. |
| * getservbyname: (libc)Services Database. |
| * getservbyport: (libc)Services Database. |
| * getservent: (libc)Services Database. |
| * getsid: (libc)Process Group Functions. |
| * getsockname: (libc)Reading Address. |
| * getsockopt: (libc)Socket Option Functions. |
| * getsubopt: (libc)Suboptions. |
| * gettext: (libc)Translation with gettext. |
| * gettimeofday: (libc)High-Resolution Calendar. |
| * getuid: (libc)Reading Persona. |
| * getumask: (libc)Setting Permissions. |
| * getutent: (libc)Manipulating the Database. |
| * getutent_r: (libc)Manipulating the Database. |
| * getutid: (libc)Manipulating the Database. |
| * getutid_r: (libc)Manipulating the Database. |
| * getutline: (libc)Manipulating the Database. |
| * getutline_r: (libc)Manipulating the Database. |
| * getutmp: (libc)XPG Functions. |
| * getutmpx: (libc)XPG Functions. |
| * getutxent: (libc)XPG Functions. |
| * getutxid: (libc)XPG Functions. |
| * getutxline: (libc)XPG Functions. |
| * getw: (libc)Character Input. |
| * getwc: (libc)Character Input. |
| * getwc_unlocked: (libc)Character Input. |
| * getwchar: (libc)Character Input. |
| * getwchar_unlocked: (libc)Character Input. |
| * getwd: (libc)Working Directory. |
| * glob64: (libc)Calling Glob. |
| * glob: (libc)Calling Glob. |
| * globfree64: (libc)More Flags for Globbing. |
| * globfree: (libc)More Flags for Globbing. |
| * gmtime: (libc)Broken-down Time. |
| * gmtime_r: (libc)Broken-down Time. |
| * grantpt: (libc)Allocation. |
| * gsignal: (libc)Signaling Yourself. |
| * gtty: (libc)BSD Terminal Modes. |
| * hasmntopt: (libc)mtab. |
| * hcreate: (libc)Hash Search Function. |
| * hcreate_r: (libc)Hash Search Function. |
| * hdestroy: (libc)Hash Search Function. |
| * hdestroy_r: (libc)Hash Search Function. |
| * hsearch: (libc)Hash Search Function. |
| * hsearch_r: (libc)Hash Search Function. |
| * htonl: (libc)Byte Order. |
| * htons: (libc)Byte Order. |
| * hypot: (libc)Exponents and Logarithms. |
| * hypotf: (libc)Exponents and Logarithms. |
| * hypotl: (libc)Exponents and Logarithms. |
| * iconv: (libc)Generic Conversion Interface. |
| * iconv_close: (libc)Generic Conversion Interface. |
| * iconv_open: (libc)Generic Conversion Interface. |
| * if_freenameindex: (libc)Interface Naming. |
| * if_indextoname: (libc)Interface Naming. |
| * if_nameindex: (libc)Interface Naming. |
| * if_nametoindex: (libc)Interface Naming. |
| * ilogb: (libc)Exponents and Logarithms. |
| * ilogbf: (libc)Exponents and Logarithms. |
| * ilogbl: (libc)Exponents and Logarithms. |
| * imaxabs: (libc)Absolute Value. |
| * imaxdiv: (libc)Integer Division. |
| * in6addr_any: (libc)Host Address Data Type. |
| * in6addr_loopback: (libc)Host Address Data Type. |
| * index: (libc)Search Functions. |
| * inet_addr: (libc)Host Address Functions. |
| * inet_aton: (libc)Host Address Functions. |
| * inet_lnaof: (libc)Host Address Functions. |
| * inet_makeaddr: (libc)Host Address Functions. |
| * inet_netof: (libc)Host Address Functions. |
| * inet_network: (libc)Host Address Functions. |
| * inet_ntoa: (libc)Host Address Functions. |
| * inet_ntop: (libc)Host Address Functions. |
| * inet_pton: (libc)Host Address Functions. |
| * initgroups: (libc)Setting Groups. |
| * initstate: (libc)BSD Random. |
| * initstate_r: (libc)BSD Random. |
| * innetgr: (libc)Netgroup Membership. |
| * ioctl: (libc)IOCTLs. |
| * isalnum: (libc)Classification of Characters. |
| * isalpha: (libc)Classification of Characters. |
| * isascii: (libc)Classification of Characters. |
| * isatty: (libc)Is It a Terminal. |
| * isblank: (libc)Classification of Characters. |
| * iscntrl: (libc)Classification of Characters. |
| * isdigit: (libc)Classification of Characters. |
| * isfinite: (libc)Floating Point Classes. |
| * isgraph: (libc)Classification of Characters. |
| * isgreater: (libc)FP Comparison Functions. |
| * isgreaterequal: (libc)FP Comparison Functions. |
| * isinf: (libc)Floating Point Classes. |
| * isinff: (libc)Floating Point Classes. |
| * isinfl: (libc)Floating Point Classes. |
| * isless: (libc)FP Comparison Functions. |
| * islessequal: (libc)FP Comparison Functions. |
| * islessgreater: (libc)FP Comparison Functions. |
| * islower: (libc)Classification of Characters. |
| * isnan: (libc)Floating Point Classes. |
| * isnan: (libc)Floating Point Classes. |
| * isnanf: (libc)Floating Point Classes. |
| * isnanl: (libc)Floating Point Classes. |
| * isnormal: (libc)Floating Point Classes. |
| * isprint: (libc)Classification of Characters. |
| * ispunct: (libc)Classification of Characters. |
| * issignaling: (libc)Floating Point Classes. |
| * isspace: (libc)Classification of Characters. |
| * isunordered: (libc)FP Comparison Functions. |
| * isupper: (libc)Classification of Characters. |
| * iswalnum: (libc)Classification of Wide Characters. |
| * iswalpha: (libc)Classification of Wide Characters. |
| * iswblank: (libc)Classification of Wide Characters. |
| * iswcntrl: (libc)Classification of Wide Characters. |
| * iswctype: (libc)Classification of Wide Characters. |
| * iswdigit: (libc)Classification of Wide Characters. |
| * iswgraph: (libc)Classification of Wide Characters. |
| * iswlower: (libc)Classification of Wide Characters. |
| * iswprint: (libc)Classification of Wide Characters. |
| * iswpunct: (libc)Classification of Wide Characters. |
| * iswspace: (libc)Classification of Wide Characters. |
| * iswupper: (libc)Classification of Wide Characters. |
| * iswxdigit: (libc)Classification of Wide Characters. |
| * isxdigit: (libc)Classification of Characters. |
| * j0: (libc)Special Functions. |
| * j0f: (libc)Special Functions. |
| * j0l: (libc)Special Functions. |
| * j1: (libc)Special Functions. |
| * j1f: (libc)Special Functions. |
| * j1l: (libc)Special Functions. |
| * jn: (libc)Special Functions. |
| * jnf: (libc)Special Functions. |
| * jnl: (libc)Special Functions. |
| * jrand48: (libc)SVID Random. |
| * jrand48_r: (libc)SVID Random. |
| * kill: (libc)Signaling Another Process. |
| * killpg: (libc)Signaling Another Process. |
| * l64a: (libc)Encode Binary Data. |
| * labs: (libc)Absolute Value. |
| * lcong48: (libc)SVID Random. |
| * lcong48_r: (libc)SVID Random. |
| * ldexp: (libc)Normalization Functions. |
| * ldexpf: (libc)Normalization Functions. |
| * ldexpl: (libc)Normalization Functions. |
| * ldiv: (libc)Integer Division. |
| * lfind: (libc)Array Search Function. |
| * lgamma: (libc)Special Functions. |
| * lgamma_r: (libc)Special Functions. |
| * lgammaf: (libc)Special Functions. |
| * lgammaf_r: (libc)Special Functions. |
| * lgammal: (libc)Special Functions. |
| * lgammal_r: (libc)Special Functions. |
| * link: (libc)Hard Links. |
| * lio_listio64: (libc)Asynchronous Reads/Writes. |
| * lio_listio: (libc)Asynchronous Reads/Writes. |
| * listen: (libc)Listening. |
| * llabs: (libc)Absolute Value. |
| * lldiv: (libc)Integer Division. |
| * llrint: (libc)Rounding Functions. |
| * llrintf: (libc)Rounding Functions. |
| * llrintl: (libc)Rounding Functions. |
| * llround: (libc)Rounding Functions. |
| * llroundf: (libc)Rounding Functions. |
| * llroundl: (libc)Rounding Functions. |
| * localeconv: (libc)The Lame Way to Locale Data. |
| * localtime: (libc)Broken-down Time. |
| * localtime_r: (libc)Broken-down Time. |
| * log10: (libc)Exponents and Logarithms. |
| * log10f: (libc)Exponents and Logarithms. |
| * log10l: (libc)Exponents and Logarithms. |
| * log1p: (libc)Exponents and Logarithms. |
| * log1pf: (libc)Exponents and Logarithms. |
| * log1pl: (libc)Exponents and Logarithms. |
| * log2: (libc)Exponents and Logarithms. |
| * log2f: (libc)Exponents and Logarithms. |
| * log2l: (libc)Exponents and Logarithms. |
| * log: (libc)Exponents and Logarithms. |
| * logb: (libc)Exponents and Logarithms. |
| * logbf: (libc)Exponents and Logarithms. |
| * logbl: (libc)Exponents and Logarithms. |
| * logf: (libc)Exponents and Logarithms. |
| * login: (libc)Logging In and Out. |
| * login_tty: (libc)Logging In and Out. |
| * logl: (libc)Exponents and Logarithms. |
| * logout: (libc)Logging In and Out. |
| * logwtmp: (libc)Logging In and Out. |
| * longjmp: (libc)Non-Local Details. |
| * lrand48: (libc)SVID Random. |
| * lrand48_r: (libc)SVID Random. |
| * lrint: (libc)Rounding Functions. |
| * lrintf: (libc)Rounding Functions. |
| * lrintl: (libc)Rounding Functions. |
| * lround: (libc)Rounding Functions. |
| * lroundf: (libc)Rounding Functions. |
| * lroundl: (libc)Rounding Functions. |
| * lsearch: (libc)Array Search Function. |
| * lseek64: (libc)File Position Primitive. |
| * lseek: (libc)File Position Primitive. |
| * lstat64: (libc)Reading Attributes. |
| * lstat: (libc)Reading Attributes. |
| * lutimes: (libc)File Times. |
| * madvise: (libc)Memory-mapped I/O. |
| * makecontext: (libc)System V contexts. |
| * mallinfo: (libc)Statistics of Malloc. |
| * malloc: (libc)Basic Allocation. |
| * mallopt: (libc)Malloc Tunable Parameters. |
| * mblen: (libc)Non-reentrant Character Conversion. |
| * mbrlen: (libc)Converting a Character. |
| * mbrtowc: (libc)Converting a Character. |
| * mbsinit: (libc)Keeping the state. |
| * mbsnrtowcs: (libc)Converting Strings. |
| * mbsrtowcs: (libc)Converting Strings. |
| * mbstowcs: (libc)Non-reentrant String Conversion. |
| * mbtowc: (libc)Non-reentrant Character Conversion. |
| * mcheck: (libc)Heap Consistency Checking. |
| * memalign: (libc)Aligned Memory Blocks. |
| * memccpy: (libc)Copying and Concatenation. |
| * memchr: (libc)Search Functions. |
| * memcmp: (libc)String/Array Comparison. |
| * memcpy: (libc)Copying and Concatenation. |
| * memfrob: (libc)Trivial Encryption. |
| * memmem: (libc)Search Functions. |
| * memmove: (libc)Copying and Concatenation. |
| * mempcpy: (libc)Copying and Concatenation. |
| * memrchr: (libc)Search Functions. |
| * memset: (libc)Copying and Concatenation. |
| * mkdir: (libc)Creating Directories. |
| * mkdtemp: (libc)Temporary Files. |
| * mkfifo: (libc)FIFO Special Files. |
| * mknod: (libc)Making Special Files. |
| * mkstemp: (libc)Temporary Files. |
| * mktemp: (libc)Temporary Files. |
| * mktime: (libc)Broken-down Time. |
| * mlock: (libc)Page Lock Functions. |
| * mlockall: (libc)Page Lock Functions. |
| * mmap64: (libc)Memory-mapped I/O. |
| * mmap: (libc)Memory-mapped I/O. |
| * modf: (libc)Rounding Functions. |
| * modff: (libc)Rounding Functions. |
| * modfl: (libc)Rounding Functions. |
| * mount: (libc)Mount-Unmount-Remount. |
| * mprobe: (libc)Heap Consistency Checking. |
| * mrand48: (libc)SVID Random. |
| * mrand48_r: (libc)SVID Random. |
| * mremap: (libc)Memory-mapped I/O. |
| * msync: (libc)Memory-mapped I/O. |
| * mtrace: (libc)Tracing malloc. |
| * munlock: (libc)Page Lock Functions. |
| * munlockall: (libc)Page Lock Functions. |
| * munmap: (libc)Memory-mapped I/O. |
| * muntrace: (libc)Tracing malloc. |
| * nan: (libc)FP Bit Twiddling. |
| * nanf: (libc)FP Bit Twiddling. |
| * nanl: (libc)FP Bit Twiddling. |
| * nanosleep: (libc)Sleeping. |
| * nearbyint: (libc)Rounding Functions. |
| * nearbyintf: (libc)Rounding Functions. |
| * nearbyintl: (libc)Rounding Functions. |
| * nextafter: (libc)FP Bit Twiddling. |
| * nextafterf: (libc)FP Bit Twiddling. |
| * nextafterl: (libc)FP Bit Twiddling. |
| * nexttoward: (libc)FP Bit Twiddling. |
| * nexttowardf: (libc)FP Bit Twiddling. |
| * nexttowardl: (libc)FP Bit Twiddling. |
| * nftw64: (libc)Working with Directory Trees. |
| * nftw: (libc)Working with Directory Trees. |
| * ngettext: (libc)Advanced gettext functions. |
| * nice: (libc)Traditional Scheduling Functions. |
| * nl_langinfo: (libc)The Elegant and Fast Way. |
| * nrand48: (libc)SVID Random. |
| * nrand48_r: (libc)SVID Random. |
| * ntohl: (libc)Byte Order. |
| * ntohs: (libc)Byte Order. |
| * ntp_adjtime: (libc)High Accuracy Clock. |
| * ntp_gettime: (libc)High Accuracy Clock. |
| * obstack_1grow: (libc)Growing Objects. |
| * obstack_1grow_fast: (libc)Extra Fast Growing. |
| * obstack_alignment_mask: (libc)Obstacks Data Alignment. |
| * obstack_alloc: (libc)Allocation in an Obstack. |
| * obstack_base: (libc)Status of an Obstack. |
| * obstack_blank: (libc)Growing Objects. |
| * obstack_blank_fast: (libc)Extra Fast Growing. |
| * obstack_chunk_size: (libc)Obstack Chunks. |
| * obstack_copy0: (libc)Allocation in an Obstack. |
| * obstack_copy: (libc)Allocation in an Obstack. |
| * obstack_finish: (libc)Growing Objects. |
| * obstack_free: (libc)Freeing Obstack Objects. |
| * obstack_grow0: (libc)Growing Objects. |
| * obstack_grow: (libc)Growing Objects. |
| * obstack_init: (libc)Preparing for Obstacks. |
| * obstack_int_grow: (libc)Growing Objects. |
| * obstack_int_grow_fast: (libc)Extra Fast Growing. |
| * obstack_next_free: (libc)Status of an Obstack. |
| * obstack_object_size: (libc)Growing Objects. |
| * obstack_object_size: (libc)Status of an Obstack. |
| * obstack_printf: (libc)Dynamic Output. |
| * obstack_ptr_grow: (libc)Growing Objects. |
| * obstack_ptr_grow_fast: (libc)Extra Fast Growing. |
| * obstack_room: (libc)Extra Fast Growing. |
| * obstack_vprintf: (libc)Variable Arguments Output. |
| * offsetof: (libc)Structure Measurement. |
| * on_exit: (libc)Cleanups on Exit. |
| * open64: (libc)Opening and Closing Files. |
| * open: (libc)Opening and Closing Files. |
| * open_memstream: (libc)String Streams. |
| * opendir: (libc)Opening a Directory. |
| * openlog: (libc)openlog. |
| * openpty: (libc)Pseudo-Terminal Pairs. |
| * parse_printf_format: (libc)Parsing a Template String. |
| * pathconf: (libc)Pathconf. |
| * pause: (libc)Using Pause. |
| * pclose: (libc)Pipe to a Subprocess. |
| * perror: (libc)Error Messages. |
| * pipe: (libc)Creating a Pipe. |
| * popen: (libc)Pipe to a Subprocess. |
| * posix_memalign: (libc)Aligned Memory Blocks. |
| * pow10: (libc)Exponents and Logarithms. |
| * pow10f: (libc)Exponents and Logarithms. |
| * pow10l: (libc)Exponents and Logarithms. |
| * pow: (libc)Exponents and Logarithms. |
| * powf: (libc)Exponents and Logarithms. |
| * powl: (libc)Exponents and Logarithms. |
| * pread64: (libc)I/O Primitives. |
| * pread: (libc)I/O Primitives. |
| * printf: (libc)Formatted Output Functions. |
| * printf_size: (libc)Predefined Printf Handlers. |
| * printf_size_info: (libc)Predefined Printf Handlers. |
| * psignal: (libc)Signal Messages. |
| * pthread_getattr_default_np: (libc)Default Thread Attributes. |
| * pthread_getspecific: (libc)Thread-specific Data. |
| * pthread_key_create: (libc)Thread-specific Data. |
| * pthread_key_delete: (libc)Thread-specific Data. |
| * pthread_setattr_default_np: (libc)Default Thread Attributes. |
| * pthread_setspecific: (libc)Thread-specific Data. |
| * ptsname: (libc)Allocation. |
| * ptsname_r: (libc)Allocation. |
| * putc: (libc)Simple Output. |
| * putc_unlocked: (libc)Simple Output. |
| * putchar: (libc)Simple Output. |
| * putchar_unlocked: (libc)Simple Output. |
| * putenv: (libc)Environment Access. |
| * putpwent: (libc)Writing a User Entry. |
| * puts: (libc)Simple Output. |
| * pututline: (libc)Manipulating the Database. |
| * pututxline: (libc)XPG Functions. |
| * putw: (libc)Simple Output. |
| * putwc: (libc)Simple Output. |
| * putwc_unlocked: (libc)Simple Output. |
| * putwchar: (libc)Simple Output. |
| * putwchar_unlocked: (libc)Simple Output. |
| * pwrite64: (libc)I/O Primitives. |
| * pwrite: (libc)I/O Primitives. |
| * qecvt: (libc)System V Number Conversion. |
| * qecvt_r: (libc)System V Number Conversion. |
| * qfcvt: (libc)System V Number Conversion. |
| * qfcvt_r: (libc)System V Number Conversion. |
| * qgcvt: (libc)System V Number Conversion. |
| * qsort: (libc)Array Sort Function. |
| * raise: (libc)Signaling Yourself. |
| * rand: (libc)ISO Random. |
| * rand_r: (libc)ISO Random. |
| * random: (libc)BSD Random. |
| * random_r: (libc)BSD Random. |
| * rawmemchr: (libc)Search Functions. |
| * read: (libc)I/O Primitives. |
| * readdir64: (libc)Reading/Closing Directory. |
| * readdir64_r: (libc)Reading/Closing Directory. |
| * readdir: (libc)Reading/Closing Directory. |
| * readdir_r: (libc)Reading/Closing Directory. |
| * readlink: (libc)Symbolic Links. |
| * readv: (libc)Scatter-Gather. |
| * realloc: (libc)Changing Block Size. |
| * realpath: (libc)Symbolic Links. |
| * recv: (libc)Receiving Data. |
| * recvfrom: (libc)Receiving Datagrams. |
| * recvmsg: (libc)Receiving Datagrams. |
| * regcomp: (libc)POSIX Regexp Compilation. |
| * regerror: (libc)Regexp Cleanup. |
| * regexec: (libc)Matching POSIX Regexps. |
| * regfree: (libc)Regexp Cleanup. |
| * register_printf_function: (libc)Registering New Conversions. |
| * remainder: (libc)Remainder Functions. |
| * remainderf: (libc)Remainder Functions. |
| * remainderl: (libc)Remainder Functions. |
| * remove: (libc)Deleting Files. |
| * rename: (libc)Renaming Files. |
| * rewind: (libc)File Positioning. |
| * rewinddir: (libc)Random Access Directory. |
| * rindex: (libc)Search Functions. |
| * rint: (libc)Rounding Functions. |
| * rintf: (libc)Rounding Functions. |
| * rintl: (libc)Rounding Functions. |
| * rmdir: (libc)Deleting Files. |
| * round: (libc)Rounding Functions. |
| * roundf: (libc)Rounding Functions. |
| * roundl: (libc)Rounding Functions. |
| * rpmatch: (libc)Yes-or-No Questions. |
| * sbrk: (libc)Resizing the Data Segment. |
| * scalb: (libc)Normalization Functions. |
| * scalbf: (libc)Normalization Functions. |
| * scalbl: (libc)Normalization Functions. |
| * scalbln: (libc)Normalization Functions. |
| * scalblnf: (libc)Normalization Functions. |
| * scalblnl: (libc)Normalization Functions. |
| * scalbn: (libc)Normalization Functions. |
| * scalbnf: (libc)Normalization Functions. |
| * scalbnl: (libc)Normalization Functions. |
| * scandir64: (libc)Scanning Directory Content. |
| * scandir: (libc)Scanning Directory Content. |
| * scanf: (libc)Formatted Input Functions. |
| * sched_get_priority_max: (libc)Basic Scheduling Functions. |
| * sched_get_priority_min: (libc)Basic Scheduling Functions. |
| * sched_getaffinity: (libc)CPU Affinity. |
| * sched_getparam: (libc)Basic Scheduling Functions. |
| * sched_getscheduler: (libc)Basic Scheduling Functions. |
| * sched_rr_get_interval: (libc)Basic Scheduling Functions. |
| * sched_setaffinity: (libc)CPU Affinity. |
| * sched_setparam: (libc)Basic Scheduling Functions. |
| * sched_setscheduler: (libc)Basic Scheduling Functions. |
| * sched_yield: (libc)Basic Scheduling Functions. |
| * secure_getenv: (libc)Environment Access. |
| * seed48: (libc)SVID Random. |
| * seed48_r: (libc)SVID Random. |
| * seekdir: (libc)Random Access Directory. |
| * select: (libc)Waiting for I/O. |
| * send: (libc)Sending Data. |
| * sendmsg: (libc)Receiving Datagrams. |
| * sendto: (libc)Sending Datagrams. |
| * setbuf: (libc)Controlling Buffering. |
| * setbuffer: (libc)Controlling Buffering. |
| * setcontext: (libc)System V contexts. |
| * setdomainname: (libc)Host Identification. |
| * setegid: (libc)Setting Groups. |
| * setenv: (libc)Environment Access. |
| * seteuid: (libc)Setting User ID. |
| * setfsent: (libc)fstab. |
| * setgid: (libc)Setting Groups. |
| * setgrent: (libc)Scanning All Groups. |
| * setgroups: (libc)Setting Groups. |
| * sethostent: (libc)Host Names. |
| * sethostid: (libc)Host Identification. |
| * sethostname: (libc)Host Identification. |
| * setitimer: (libc)Setting an Alarm. |
| * setjmp: (libc)Non-Local Details. |
| * setkey: (libc)DES Encryption. |
| * setkey_r: (libc)DES Encryption. |
| * setlinebuf: (libc)Controlling Buffering. |
| * setlocale: (libc)Setting the Locale. |
| * setlogmask: (libc)setlogmask. |
| * setmntent: (libc)mtab. |
| * setnetent: (libc)Networks Database. |
| * setnetgrent: (libc)Lookup Netgroup. |
| * setpgid: (libc)Process Group Functions. |
| * setpgrp: (libc)Process Group Functions. |
| * setpriority: (libc)Traditional Scheduling Functions. |
| * setprotoent: (libc)Protocols Database. |
| * setpwent: (libc)Scanning All Users. |
| * setregid: (libc)Setting Groups. |
| * setreuid: (libc)Setting User ID. |
| * setrlimit64: (libc)Limits on Resources. |
| * setrlimit: (libc)Limits on Resources. |
| * setservent: (libc)Services Database. |
| * setsid: (libc)Process Group Functions. |
| * setsockopt: (libc)Socket Option Functions. |
| * setstate: (libc)BSD Random. |
| * setstate_r: (libc)BSD Random. |
| * settimeofday: (libc)High-Resolution Calendar. |
| * setuid: (libc)Setting User ID. |
| * setutent: (libc)Manipulating the Database. |
| * setutxent: (libc)XPG Functions. |
| * setvbuf: (libc)Controlling Buffering. |
| * shm_open: (libc)Memory-mapped I/O. |
| * shm_unlink: (libc)Memory-mapped I/O. |
| * shutdown: (libc)Closing a Socket. |
| * sigaction: (libc)Advanced Signal Handling. |
| * sigaddset: (libc)Signal Sets. |
| * sigaltstack: (libc)Signal Stack. |
| * sigblock: (libc)Blocking in BSD. |
| * sigdelset: (libc)Signal Sets. |
| * sigemptyset: (libc)Signal Sets. |
| * sigfillset: (libc)Signal Sets. |
| * siginterrupt: (libc)BSD Handler. |
| * sigismember: (libc)Signal Sets. |
| * siglongjmp: (libc)Non-Local Exits and Signals. |
| * sigmask: (libc)Blocking in BSD. |
| * signal: (libc)Basic Signal Handling. |
| * signbit: (libc)FP Bit Twiddling. |
| * significand: (libc)Normalization Functions. |
| * significandf: (libc)Normalization Functions. |
| * significandl: (libc)Normalization Functions. |
| * sigpause: (libc)Blocking in BSD. |
| * sigpending: (libc)Checking for Pending Signals. |
| * sigprocmask: (libc)Process Signal Mask. |
| * sigsetjmp: (libc)Non-Local Exits and Signals. |
| * sigsetmask: (libc)Blocking in BSD. |
| * sigstack: (libc)Signal Stack. |
| * sigsuspend: (libc)Sigsuspend. |
| * sigvec: (libc)BSD Handler. |
| * sin: (libc)Trig Functions. |
| * sincos: (libc)Trig Functions. |
| * sincosf: (libc)Trig Functions. |
| * sincosl: (libc)Trig Functions. |
| * sinf: (libc)Trig Functions. |
| * sinh: (libc)Hyperbolic Functions. |
| * sinhf: (libc)Hyperbolic Functions. |
| * sinhl: (libc)Hyperbolic Functions. |
| * sinl: (libc)Trig Functions. |
| * sleep: (libc)Sleeping. |
| * snprintf: (libc)Formatted Output Functions. |
| * socket: (libc)Creating a Socket. |
| * socketpair: (libc)Socket Pairs. |
| * sprintf: (libc)Formatted Output Functions. |
| * sqrt: (libc)Exponents and Logarithms. |
| * sqrtf: (libc)Exponents and Logarithms. |
| * sqrtl: (libc)Exponents and Logarithms. |
| * srand48: (libc)SVID Random. |
| * srand48_r: (libc)SVID Random. |
| * srand: (libc)ISO Random. |
| * srandom: (libc)BSD Random. |
| * srandom_r: (libc)BSD Random. |
| * sscanf: (libc)Formatted Input Functions. |
| * ssignal: (libc)Basic Signal Handling. |
| * stat64: (libc)Reading Attributes. |
| * stat: (libc)Reading Attributes. |
| * stime: (libc)Simple Calendar Time. |
| * stpcpy: (libc)Copying and Concatenation. |
| * stpncpy: (libc)Copying and Concatenation. |
| * strcasecmp: (libc)String/Array Comparison. |
| * strcasestr: (libc)Search Functions. |
| * strcat: (libc)Copying and Concatenation. |
| * strchr: (libc)Search Functions. |
| * strchrnul: (libc)Search Functions. |
| * strcmp: (libc)String/Array Comparison. |
| * strcoll: (libc)Collation Functions. |
| * strcpy: (libc)Copying and Concatenation. |
| * strcspn: (libc)Search Functions. |
| * strdup: (libc)Copying and Concatenation. |
| * strdupa: (libc)Copying and Concatenation. |
| * strerror: (libc)Error Messages. |
| * strerror_r: (libc)Error Messages. |
| * strfmon: (libc)Formatting Numbers. |
| * strfry: (libc)strfry. |
| * strftime: (libc)Formatting Calendar Time. |
| * strlen: (libc)String Length. |
| * strncasecmp: (libc)String/Array Comparison. |
| * strncat: (libc)Copying and Concatenation. |
| * strncmp: (libc)String/Array Comparison. |
| * strncpy: (libc)Copying and Concatenation. |
| * strndup: (libc)Copying and Concatenation. |
| * strndupa: (libc)Copying and Concatenation. |
| * strnlen: (libc)String Length. |
| * strpbrk: (libc)Search Functions. |
| * strptime: (libc)Low-Level Time String Parsing. |
| * strrchr: (libc)Search Functions. |
| * strsep: (libc)Finding Tokens in a String. |
| * strsignal: (libc)Signal Messages. |
| * strspn: (libc)Search Functions. |
| * strstr: (libc)Search Functions. |
| * strtod: (libc)Parsing of Floats. |
| * strtof: (libc)Parsing of Floats. |
| * strtoimax: (libc)Parsing of Integers. |
| * strtok: (libc)Finding Tokens in a String. |
| * strtok_r: (libc)Finding Tokens in a String. |
| * strtol: (libc)Parsing of Integers. |
| * strtold: (libc)Parsing of Floats. |
| * strtoll: (libc)Parsing of Integers. |
| * strtoq: (libc)Parsing of Integers. |
| * strtoul: (libc)Parsing of Integers. |
| * strtoull: (libc)Parsing of Integers. |
| * strtoumax: (libc)Parsing of Integers. |
| * strtouq: (libc)Parsing of Integers. |
| * strverscmp: (libc)String/Array Comparison. |
| * strxfrm: (libc)Collation Functions. |
| * stty: (libc)BSD Terminal Modes. |
| * swapcontext: (libc)System V contexts. |
| * swprintf: (libc)Formatted Output Functions. |
| * swscanf: (libc)Formatted Input Functions. |
| * symlink: (libc)Symbolic Links. |
| * sync: (libc)Synchronizing I/O. |
| * syscall: (libc)System Calls. |
| * sysconf: (libc)Sysconf Definition. |
| * sysctl: (libc)System Parameters. |
| * syslog: (libc)syslog; vsyslog. |
| * system: (libc)Running a Command. |
| * sysv_signal: (libc)Basic Signal Handling. |
| * tan: (libc)Trig Functions. |
| * tanf: (libc)Trig Functions. |
| * tanh: (libc)Hyperbolic Functions. |
| * tanhf: (libc)Hyperbolic Functions. |
| * tanhl: (libc)Hyperbolic Functions. |
| * tanl: (libc)Trig Functions. |
| * tcdrain: (libc)Line Control. |
| * tcflow: (libc)Line Control. |
| * tcflush: (libc)Line Control. |
| * tcgetattr: (libc)Mode Functions. |
| * tcgetpgrp: (libc)Terminal Access Functions. |
| * tcgetsid: (libc)Terminal Access Functions. |
| * tcsendbreak: (libc)Line Control. |
| * tcsetattr: (libc)Mode Functions. |
| * tcsetpgrp: (libc)Terminal Access Functions. |
| * tdelete: (libc)Tree Search Function. |
| * tdestroy: (libc)Tree Search Function. |
| * telldir: (libc)Random Access Directory. |
| * tempnam: (libc)Temporary Files. |
| * textdomain: (libc)Locating gettext catalog. |
| * tfind: (libc)Tree Search Function. |
| * tgamma: (libc)Special Functions. |
| * tgammaf: (libc)Special Functions. |
| * tgammal: (libc)Special Functions. |
| * time: (libc)Simple Calendar Time. |
| * timegm: (libc)Broken-down Time. |
| * timelocal: (libc)Broken-down Time. |
| * times: (libc)Processor Time. |
| * tmpfile64: (libc)Temporary Files. |
| * tmpfile: (libc)Temporary Files. |
| * tmpnam: (libc)Temporary Files. |
| * tmpnam_r: (libc)Temporary Files. |
| * toascii: (libc)Case Conversion. |
| * tolower: (libc)Case Conversion. |
| * toupper: (libc)Case Conversion. |
| * towctrans: (libc)Wide Character Case Conversion. |
| * towlower: (libc)Wide Character Case Conversion. |
| * towupper: (libc)Wide Character Case Conversion. |
| * trunc: (libc)Rounding Functions. |
| * truncate64: (libc)File Size. |
| * truncate: (libc)File Size. |
| * truncf: (libc)Rounding Functions. |
| * truncl: (libc)Rounding Functions. |
| * tsearch: (libc)Tree Search Function. |
| * ttyname: (libc)Is It a Terminal. |
| * ttyname_r: (libc)Is It a Terminal. |
| * twalk: (libc)Tree Search Function. |
| * tzset: (libc)Time Zone Functions. |
| * ulimit: (libc)Limits on Resources. |
| * umask: (libc)Setting Permissions. |
| * umount2: (libc)Mount-Unmount-Remount. |
| * umount: (libc)Mount-Unmount-Remount. |
| * uname: (libc)Platform Type. |
| * ungetc: (libc)How Unread. |
| * ungetwc: (libc)How Unread. |
| * unlink: (libc)Deleting Files. |
| * unlockpt: (libc)Allocation. |
| * unsetenv: (libc)Environment Access. |
| * updwtmp: (libc)Manipulating the Database. |
| * utime: (libc)File Times. |
| * utimes: (libc)File Times. |
| * utmpname: (libc)Manipulating the Database. |
| * utmpxname: (libc)XPG Functions. |
| * va_arg: (libc)Argument Macros. |
| * va_copy: (libc)Argument Macros. |
| * va_end: (libc)Argument Macros. |
| * va_start: (libc)Argument Macros. |
| * valloc: (libc)Aligned Memory Blocks. |
| * vasprintf: (libc)Variable Arguments Output. |
| * verr: (libc)Error Messages. |
| * verrx: (libc)Error Messages. |
| * versionsort64: (libc)Scanning Directory Content. |
| * versionsort: (libc)Scanning Directory Content. |
| * vfork: (libc)Creating a Process. |
| * vfprintf: (libc)Variable Arguments Output. |
| * vfscanf: (libc)Variable Arguments Input. |
| * vfwprintf: (libc)Variable Arguments Output. |
| * vfwscanf: (libc)Variable Arguments Input. |
| * vlimit: (libc)Limits on Resources. |
| * vprintf: (libc)Variable Arguments Output. |
| * vscanf: (libc)Variable Arguments Input. |
| * vsnprintf: (libc)Variable Arguments Output. |
| * vsprintf: (libc)Variable Arguments Output. |
| * vsscanf: (libc)Variable Arguments Input. |
| * vswprintf: (libc)Variable Arguments Output. |
| * vswscanf: (libc)Variable Arguments Input. |
| * vsyslog: (libc)syslog; vsyslog. |
| * vtimes: (libc)Resource Usage. |
| * vwarn: (libc)Error Messages. |
| * vwarnx: (libc)Error Messages. |
| * vwprintf: (libc)Variable Arguments Output. |
| * vwscanf: (libc)Variable Arguments Input. |
| * wait3: (libc)BSD Wait Functions. |
| * wait4: (libc)Process Completion. |
| * wait: (libc)Process Completion. |
| * waitpid: (libc)Process Completion. |
| * warn: (libc)Error Messages. |
| * warnx: (libc)Error Messages. |
| * wcpcpy: (libc)Copying and Concatenation. |
| * wcpncpy: (libc)Copying and Concatenation. |
| * wcrtomb: (libc)Converting a Character. |
| * wcscasecmp: (libc)String/Array Comparison. |
| * wcscat: (libc)Copying and Concatenation. |
| * wcschr: (libc)Search Functions. |
| * wcschrnul: (libc)Search Functions. |
| * wcscmp: (libc)String/Array Comparison. |
| * wcscoll: (libc)Collation Functions. |
| * wcscpy: (libc)Copying and Concatenation. |
| * wcscspn: (libc)Search Functions. |
| * wcsdup: (libc)Copying and Concatenation. |
| * wcsftime: (libc)Formatting Calendar Time. |
| * wcslen: (libc)String Length. |
| * wcsncasecmp: (libc)String/Array Comparison. |
| * wcsncat: (libc)Copying and Concatenation. |
| * wcsncmp: (libc)String/Array Comparison. |
| * wcsncpy: (libc)Copying and Concatenation. |
| * wcsnlen: (libc)String Length. |
| * wcsnrtombs: (libc)Converting Strings. |
| * wcspbrk: (libc)Search Functions. |
| * wcsrchr: (libc)Search Functions. |
| * wcsrtombs: (libc)Converting Strings. |
| * wcsspn: (libc)Search Functions. |
| * wcsstr: (libc)Search Functions. |
| * wcstod: (libc)Parsing of Floats. |
| * wcstof: (libc)Parsing of Floats. |
| * wcstoimax: (libc)Parsing of Integers. |
| * wcstok: (libc)Finding Tokens in a String. |
| * wcstol: (libc)Parsing of Integers. |
| * wcstold: (libc)Parsing of Floats. |
| * wcstoll: (libc)Parsing of Integers. |
| * wcstombs: (libc)Non-reentrant String Conversion. |
| * wcstoq: (libc)Parsing of Integers. |
| * wcstoul: (libc)Parsing of Integers. |
| * wcstoull: (libc)Parsing of Integers. |
| * wcstoumax: (libc)Parsing of Integers. |
| * wcstouq: (libc)Parsing of Integers. |
| * wcswcs: (libc)Search Functions. |
| * wcsxfrm: (libc)Collation Functions. |
| * wctob: (libc)Converting a Character. |
| * wctomb: (libc)Non-reentrant Character Conversion. |
| * wctrans: (libc)Wide Character Case Conversion. |
| * wctype: (libc)Classification of Wide Characters. |
| * wmemchr: (libc)Search Functions. |
| * wmemcmp: (libc)String/Array Comparison. |
| * wmemcpy: (libc)Copying and Concatenation. |
| * wmemmove: (libc)Copying and Concatenation. |
| * wmempcpy: (libc)Copying and Concatenation. |
| * wmemset: (libc)Copying and Concatenation. |
| * wordexp: (libc)Calling Wordexp. |
| * wordfree: (libc)Calling Wordexp. |
| * wprintf: (libc)Formatted Output Functions. |
| * write: (libc)I/O Primitives. |
| * writev: (libc)Scatter-Gather. |
| * wscanf: (libc)Formatted Input Functions. |
| * y0: (libc)Special Functions. |
| * y0f: (libc)Special Functions. |
| * y0l: (libc)Special Functions. |
| * y1: (libc)Special Functions. |
| * y1f: (libc)Special Functions. |
| * y1l: (libc)Special Functions. |
| * yn: (libc)Special Functions. |
| * ynf: (libc)Special Functions. |
| * ynl: (libc)Special Functions. |
| END-INFO-DIR-ENTRY |
| |
| This file documents the GNU C Library. |
| |
| This is `The GNU C Library Reference Manual', for version 2.19 |
| (Buildroot). |
| |
| Copyright (C) 1993-2014 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version |
| 1.3 or any later version published by the Free Software Foundation; |
| with the Invariant Sections being "Free Software Needs Free |
| Documentation" and "GNU Lesser General Public License", the Front-Cover |
| texts being "A GNU Manual", and with the Back-Cover Texts as in (a) |
| below. A copy of the license is included in the section entitled "GNU |
| Free Documentation License". |
| |
| (a) The FSF's Back-Cover Text is: "You have the freedom to copy and |
| modify this GNU manual. Buying copies from the FSF supports it in |
| developing GNU and promoting software freedom." |
| |
| |
| File: libc.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) |
| |
| Main Menu |
| ********* |
| |
| This is `The GNU C Library Reference Manual', for Version 2.19 |
| (Buildroot) of the GNU C Library. |
| |
| * Menu: |
| |
| * Introduction:: Purpose of the GNU C Library. |
| * Error Reporting:: How library functions report errors. |
| * Memory:: Allocating virtual memory and controlling |
| paging. |
| * Character Handling:: Character testing and conversion functions. |
| * String and Array Utilities:: Utilities for copying and comparing strings |
| and arrays. |
| * Character Set Handling:: Support for extended character sets. |
| * Locales:: The country and language can affect the |
| behavior of library functions. |
| * Message Translation:: How to make the program speak the user's |
| language. |
| * Searching and Sorting:: General searching and sorting functions. |
| * Pattern Matching:: Matching shell ``globs'' and regular |
| expressions. |
| * I/O Overview:: Introduction to the I/O facilities. |
| * I/O on Streams:: High-level, portable I/O facilities. |
| * Low-Level I/O:: Low-level, less portable I/O. |
| * File System Interface:: Functions for manipulating files. |
| * Pipes and FIFOs:: A simple interprocess communication |
| mechanism. |
| * Sockets:: A more complicated IPC mechanism, with |
| networking support. |
| * Low-Level Terminal Interface:: How to change the characteristics of a |
| terminal device. |
| * Syslog:: System logging and messaging. |
| * Mathematics:: Math functions, useful constants, random |
| numbers. |
| * Arithmetic:: Low level arithmetic functions. |
| * Date and Time:: Functions for getting the date and time and |
| formatting them nicely. |
| * Resource Usage And Limitation:: Functions for examining resource usage and |
| getting and setting limits. |
| * Non-Local Exits:: Jumping out of nested function calls. |
| * Signal Handling:: How to send, block, and handle signals. |
| * Program Basics:: Writing the beginning and end of your |
| program. |
| * Processes:: How to create processes and run other |
| programs. |
| * Job Control:: All about process groups and sessions. |
| * Name Service Switch:: Accessing system databases. |
| * Users and Groups:: How users are identified and classified. |
| * System Management:: Controlling the system and getting |
| information about it. |
| * System Configuration:: Parameters describing operating system |
| limits. |
| * Cryptographic Functions:: DES encryption and password handling. |
| * Debugging Support:: Functions to help debugging applications. |
| * POSIX Threads:: POSIX Threads. |
| * Internal Probes:: Probes to monitor libc internal behavior. |
| |
| Appendices |
| |
| * Language Features:: C language features provided by the library. |
| * Library Summary:: A summary showing the syntax, header file, |
| and derivation of each library feature. |
| * Installation:: How to install the GNU C Library. |
| * Maintenance:: How to enhance and port the GNU C Library. |
| * Platform:: Describe all platform-specific facilities |
| provided. |
| * Contributors:: Who wrote what parts of the GNU C Library. |
| * Free Manuals:: Free Software Needs Free Documentation. |
| * Copying:: The GNU Lesser General Public License says |
| how you can copy and share the GNU C Library. |
| * Documentation License:: This manual is under the GNU Free |
| Documentation License. |
| |
| Indices |
| |
| * Concept Index:: Index of concepts and names. |
| * Type Index:: Index of types and type qualifiers. |
| * Function Index:: Index of functions and function-like macros. |
| * Variable Index:: Index of variables and variable-like macros. |
| * File Index:: Index of programs and files. |
| |
| --- The Detailed Node Listing --- |
| |
| Introduction |
| |
| * Getting Started:: What this manual is for and how to use it. |
| * Standards and Portability:: Standards and sources upon which the GNU |
| C library is based. |
| * Using the Library:: Some practical uses for the library. |
| * Roadmap to the Manual:: Overview of the remaining chapters in |
| this manual. |
| |
| Standards and Portability |
| |
| * ISO C:: The international standard for the C |
| programming language. |
| * POSIX:: The ISO/IEC 9945 (aka IEEE 1003) standards |
| for operating systems. |
| * Berkeley Unix:: BSD and SunOS. |
| * SVID:: The System V Interface Description. |
| * XPG:: The X/Open Portability Guide. |
| |
| POSIX |
| |
| * POSIX Safety Concepts:: Safety concepts from POSIX. |
| * Unsafe Features:: Features that make functions unsafe. |
| * Conditionally Safe Features:: Features that make functions unsafe |
| in the absence of workarounds. |
| * Other Safety Remarks:: Additional safety features and remarks. |
| |
| Using the Library |
| |
| * Header Files:: How to include the header files in your |
| programs. |
| * Macro Definitions:: Some functions in the library may really |
| be implemented as macros. |
| * Reserved Names:: The C standard reserves some names for |
| the library, and some for users. |
| * Feature Test Macros:: How to control what names are defined. |
| |
| Error Reporting |
| |
| * Checking for Errors:: How errors are reported by library functions. |
| * Error Codes:: Error code macros; all of these expand |
| into integer constant values. |
| * Error Messages:: Mapping error codes onto error messages. |
| |
| Memory |
| |
| * Memory Concepts:: An introduction to concepts and terminology. |
| * Memory Allocation:: Allocating storage for your program data |
| * Resizing the Data Segment:: `brk', `sbrk' |
| * Locking Pages:: Preventing page faults |
| |
| Memory Allocation |
| |
| * Memory Allocation and C:: How to get different kinds of allocation in C. |
| * Unconstrained Allocation:: The `malloc' facility allows fully general |
| dynamic allocation. |
| * Allocation Debugging:: Finding memory leaks and not freed memory. |
| * Obstacks:: Obstacks are less general than malloc |
| but more efficient and convenient. |
| * Variable Size Automatic:: Allocation of variable-sized blocks |
| of automatic storage that are freed when the |
| calling function returns. |
| |
| Unconstrained Allocation |
| |
| * Basic Allocation:: Simple use of `malloc'. |
| * Malloc Examples:: Examples of `malloc'. `xmalloc'. |
| * Freeing after Malloc:: Use `free' to free a block you |
| got with `malloc'. |
| * Changing Block Size:: Use `realloc' to make a block |
| bigger or smaller. |
| * Allocating Cleared Space:: Use `calloc' to allocate a |
| block and clear it. |
| * Efficiency and Malloc:: Efficiency considerations in use of |
| these functions. |
| * Aligned Memory Blocks:: Allocating specially aligned memory. |
| * Malloc Tunable Parameters:: Use `mallopt' to adjust allocation |
| parameters. |
| * Heap Consistency Checking:: Automatic checking for errors. |
| * Hooks for Malloc:: You can use these hooks for debugging |
| programs that use `malloc'. |
| * Statistics of Malloc:: Getting information about how much |
| memory your program is using. |
| * Summary of Malloc:: Summary of `malloc' and related functions. |
| |
| Allocation Debugging |
| |
| * Tracing malloc:: How to install the tracing functionality. |
| * Using the Memory Debugger:: Example programs excerpts. |
| * Tips for the Memory Debugger:: Some more or less clever ideas. |
| * Interpreting the traces:: What do all these lines mean? |
| |
| Obstacks |
| |
| * Creating Obstacks:: How to declare an obstack in your program. |
| * Preparing for Obstacks:: Preparations needed before you can |
| use obstacks. |
| * Allocation in an Obstack:: Allocating objects in an obstack. |
| * Freeing Obstack Objects:: Freeing objects in an obstack. |
| * Obstack Functions:: The obstack functions are both |
| functions and macros. |
| * Growing Objects:: Making an object bigger by stages. |
| * Extra Fast Growing:: Extra-high-efficiency (though more |
| complicated) growing objects. |
| * Status of an Obstack:: Inquiries about the status of an obstack. |
| * Obstacks Data Alignment:: Controlling alignment of objects in obstacks. |
| * Obstack Chunks:: How obstacks obtain and release chunks; |
| efficiency considerations. |
| * Summary of Obstacks:: |
| |
| Variable Size Automatic |
| |
| * Alloca Example:: Example of using `alloca'. |
| * Advantages of Alloca:: Reasons to use `alloca'. |
| * Disadvantages of Alloca:: Reasons to avoid `alloca'. |
| * GNU C Variable-Size Arrays:: Only in GNU C, here is an alternative |
| method of allocating dynamically and |
| freeing automatically. |
| |
| Locking Pages |
| |
| * Why Lock Pages:: Reasons to read this section. |
| * Locked Memory Details:: Everything you need to know locked |
| memory |
| * Page Lock Functions:: Here's how to do it. |
| |
| Character Handling |
| |
| * Classification of Characters:: Testing whether characters are |
| letters, digits, punctuation, etc. |
| |
| * Case Conversion:: Case mapping, and the like. |
| * Classification of Wide Characters:: Character class determination for |
| wide characters. |
| * Using Wide Char Classes:: Notes on using the wide character |
| classes. |
| * Wide Character Case Conversion:: Mapping of wide characters. |
| |
| String and Array Utilities |
| |
| * Representation of Strings:: Introduction to basic concepts. |
| * String/Array Conventions:: Whether to use a string function or an |
| arbitrary array function. |
| * String Length:: Determining the length of a string. |
| * Copying and Concatenation:: Functions to copy the contents of strings |
| and arrays. |
| * String/Array Comparison:: Functions for byte-wise and character-wise |
| comparison. |
| * Collation Functions:: Functions for collating strings. |
| * Search Functions:: Searching for a specific element or substring. |
| * Finding Tokens in a String:: Splitting a string into tokens by looking |
| for delimiters. |
| * strfry:: Function for flash-cooking a string. |
| * Trivial Encryption:: Obscuring data. |
| * Encode Binary Data:: Encoding and Decoding of Binary Data. |
| * Argz and Envz Vectors:: Null-separated string vectors. |
| |
| Argz and Envz Vectors |
| |
| * Argz Functions:: Operations on argz vectors. |
| * Envz Functions:: Additional operations on environment vectors. |
| |
| Character Set Handling |
| |
| * Extended Char Intro:: Introduction to Extended Characters. |
| * Charset Function Overview:: Overview about Character Handling |
| Functions. |
| * Restartable multibyte conversion:: Restartable multibyte conversion |
| Functions. |
| * Non-reentrant Conversion:: Non-reentrant Conversion Function. |
| * Generic Charset Conversion:: Generic Charset Conversion. |
| |
| Restartable multibyte conversion |
| |
| * Selecting the Conversion:: Selecting the conversion and its properties. |
| * Keeping the state:: Representing the state of the conversion. |
| * Converting a Character:: Converting Single Characters. |
| * Converting Strings:: Converting Multibyte and Wide Character |
| Strings. |
| * Multibyte Conversion Example:: A Complete Multibyte Conversion Example. |
| |
| Non-reentrant Conversion |
| |
| * Non-reentrant Character Conversion:: Non-reentrant Conversion of Single |
| Characters. |
| * Non-reentrant String Conversion:: Non-reentrant Conversion of Strings. |
| * Shift State:: States in Non-reentrant Functions. |
| |
| Generic Charset Conversion |
| |
| * Generic Conversion Interface:: Generic Character Set Conversion Interface. |
| * iconv Examples:: A complete `iconv' example. |
| * Other iconv Implementations:: Some Details about other `iconv' |
| Implementations. |
| * glibc iconv Implementation:: The `iconv' Implementation in the GNU C |
| library. |
| |
| Locales |
| |
| * Effects of Locale:: Actions affected by the choice of |
| locale. |
| * Choosing Locale:: How the user specifies a locale. |
| * Locale Categories:: Different purposes for which you can |
| select a locale. |
| * Setting the Locale:: How a program specifies the locale |
| with library functions. |
| * Standard Locales:: Locale names available on all systems. |
| * Locale Information:: How to access the information for the locale. |
| * Formatting Numbers:: A dedicated function to format numbers. |
| * Yes-or-No Questions:: Check a Response against the locale. |
| |
| Locale Information |
| |
| * The Lame Way to Locale Data:: ISO C's `localeconv'. |
| * The Elegant and Fast Way:: X/Open's `nl_langinfo'. |
| |
| The Lame Way to Locale Data |
| |
| * General Numeric:: Parameters for formatting numbers and |
| currency amounts. |
| * Currency Symbol:: How to print the symbol that identifies an |
| amount of money (e.g. `$'). |
| * Sign of Money Amount:: How to print the (positive or negative) sign |
| for a monetary amount, if one exists. |
| |
| Message Translation |
| |
| * Message catalogs a la X/Open:: The `catgets' family of functions. |
| * The Uniforum approach:: The `gettext' family of functions. |
| |
| Message catalogs a la X/Open |
| |
| * The catgets Functions:: The `catgets' function family. |
| * The message catalog files:: Format of the message catalog files. |
| * The gencat program:: How to generate message catalogs files which |
| can be used by the functions. |
| * Common Usage:: How to use the `catgets' interface. |
| |
| The Uniforum approach |
| |
| * Message catalogs with gettext:: The `gettext' family of functions. |
| * Helper programs for gettext:: Programs to handle message catalogs |
| for `gettext'. |
| |
| Message catalogs with gettext |
| |
| * Translation with gettext:: What has to be done to translate a message. |
| * Locating gettext catalog:: How to determine which catalog to be used. |
| * Advanced gettext functions:: Additional functions for more complicated |
| situations. |
| * Charset conversion in gettext:: How to specify the output character set |
| `gettext' uses. |
| * GUI program problems:: How to use `gettext' in GUI programs. |
| * Using gettextized software:: The possibilities of the user to influence |
| the way `gettext' works. |
| |
| Searching and Sorting |
| |
| * Comparison Functions:: Defining how to compare two objects. |
| Since the sort and search facilities |
| are general, you have to specify the |
| ordering. |
| * Array Search Function:: The `bsearch' function. |
| * Array Sort Function:: The `qsort' function. |
| * Search/Sort Example:: An example program. |
| * Hash Search Function:: The `hsearch' function. |
| * Tree Search Function:: The `tsearch' function. |
| |
| Pattern Matching |
| |
| * Wildcard Matching:: Matching a wildcard pattern against a single string. |
| * Globbing:: Finding the files that match a wildcard pattern. |
| * Regular Expressions:: Matching regular expressions against strings. |
| * Word Expansion:: Expanding shell variables, nested commands, |
| arithmetic, and wildcards. |
| This is what the shell does with shell commands. |
| |
| Globbing |
| |
| * Calling Glob:: Basic use of `glob'. |
| * Flags for Globbing:: Flags that enable various options in `glob'. |
| * More Flags for Globbing:: GNU specific extensions to `glob'. |
| |
| Regular Expressions |
| |
| * POSIX Regexp Compilation:: Using `regcomp' to prepare to match. |
| * Flags for POSIX Regexps:: Syntax variations for `regcomp'. |
| * Matching POSIX Regexps:: Using `regexec' to match the compiled |
| pattern that you get from `regcomp'. |
| * Regexp Subexpressions:: Finding which parts of the string were matched. |
| * Subexpression Complications:: Find points of which parts were matched. |
| * Regexp Cleanup:: Freeing storage; reporting errors. |
| |
| Word Expansion |
| |
| * Expansion Stages:: What word expansion does to a string. |
| * Calling Wordexp:: How to call `wordexp'. |
| * Flags for Wordexp:: Options you can enable in `wordexp'. |
| * Wordexp Example:: A sample program that does word expansion. |
| * Tilde Expansion:: Details of how tilde expansion works. |
| * Variable Substitution:: Different types of variable substitution. |
| |
| I/O Overview |
| |
| * I/O Concepts:: Some basic information and terminology. |
| * File Names:: How to refer to a file. |
| |
| I/O Concepts |
| |
| * Streams and File Descriptors:: The GNU C Library provides two ways |
| to access the contents of files. |
| * File Position:: The number of bytes from the |
| beginning of the file. |
| |
| File Names |
| |
| * Directories:: Directories contain entries for files. |
| * File Name Resolution:: A file name specifies how to look up a file. |
| * File Name Errors:: Error conditions relating to file names. |
| * File Name Portability:: File name portability and syntax issues. |
| |
| I/O on Streams |
| |
| * Streams:: About the data type representing a stream. |
| * Standard Streams:: Streams to the standard input and output |
| devices are created for you. |
| * Opening Streams:: How to create a stream to talk to a file. |
| * Closing Streams:: Close a stream when you are finished with it. |
| * Streams and Threads:: Issues with streams in threaded programs. |
| * Streams and I18N:: Streams in internationalized applications. |
| * Simple Output:: Unformatted output by characters and lines. |
| * Character Input:: Unformatted input by characters and words. |
| * Line Input:: Reading a line or a record from a stream. |
| * Unreading:: Peeking ahead/pushing back input just read. |
| * Block Input/Output:: Input and output operations on blocks of data. |
| * Formatted Output:: `printf' and related functions. |
| * Customizing Printf:: You can define new conversion specifiers for |
| `printf' and friends. |
| * Formatted Input:: `scanf' and related functions. |
| * EOF and Errors:: How you can tell if an I/O error happens. |
| * Error Recovery:: What you can do about errors. |
| * Binary Streams:: Some systems distinguish between text files |
| and binary files. |
| * File Positioning:: About random-access streams. |
| * Portable Positioning:: Random access on peculiar ISO C systems. |
| * Stream Buffering:: How to control buffering of streams. |
| * Other Kinds of Streams:: Streams that do not necessarily correspond |
| to an open file. |
| * Formatted Messages:: Print strictly formatted messages. |
| |
| Unreading |
| |
| * Unreading Idea:: An explanation of unreading with pictures. |
| * How Unread:: How to call `ungetc' to do unreading. |
| |
| Formatted Output |
| |
| * Formatted Output Basics:: Some examples to get you started. |
| * Output Conversion Syntax:: General syntax of conversion |
| specifications. |
| * Table of Output Conversions:: Summary of output conversions and |
| what they do. |
| * Integer Conversions:: Details about formatting of integers. |
| * Floating-Point Conversions:: Details about formatting of |
| floating-point numbers. |
| * Other Output Conversions:: Details about formatting of strings, |
| characters, pointers, and the like. |
| * Formatted Output Functions:: Descriptions of the actual functions. |
| * Dynamic Output:: Functions that allocate memory for the output. |
| * Variable Arguments Output:: `vprintf' and friends. |
| * Parsing a Template String:: What kinds of args does a given template |
| call for? |
| * Example of Parsing:: Sample program using `parse_printf_format'. |
| |
| Customizing Printf |
| |
| * Registering New Conversions:: Using `register_printf_function' |
| to register a new output conversion. |
| * Conversion Specifier Options:: The handler must be able to get |
| the options specified in the |
| template when it is called. |
| * Defining the Output Handler:: Defining the handler and arginfo |
| functions that are passed as arguments |
| to `register_printf_function'. |
| * Printf Extension Example:: How to define a `printf' |
| handler function. |
| * Predefined Printf Handlers:: Predefined `printf' handlers. |
| |
| Formatted Input |
| |
| * Formatted Input Basics:: Some basics to get you started. |
| * Input Conversion Syntax:: Syntax of conversion specifications. |
| * Table of Input Conversions:: Summary of input conversions and what they do. |
| * Numeric Input Conversions:: Details of conversions for reading numbers. |
| * String Input Conversions:: Details of conversions for reading strings. |
| * Dynamic String Input:: String conversions that `malloc' the buffer. |
| * Other Input Conversions:: Details of miscellaneous other conversions. |
| * Formatted Input Functions:: Descriptions of the actual functions. |
| * Variable Arguments Input:: `vscanf' and friends. |
| |
| Stream Buffering |
| |
| * Buffering Concepts:: Terminology is defined here. |
| * Flushing Buffers:: How to ensure that output buffers are flushed. |
| * Controlling Buffering:: How to specify what kind of buffering to use. |
| |
| Other Kinds of Streams |
| |
| * String Streams:: Streams that get data from or put data in |
| a string or memory buffer. |
| * Custom Streams:: Defining your own streams with an arbitrary |
| input data source and/or output data sink. |
| |
| Custom Streams |
| |
| * Streams and Cookies:: The "cookie" records where to fetch or |
| store data that is read or written. |
| * Hook Functions:: How you should define the four "hook |
| functions" that a custom stream needs. |
| |
| Formatted Messages |
| |
| * Printing Formatted Messages:: The `fmtmsg' function. |
| * Adding Severity Classes:: Add more severity classes. |
| * Example:: How to use `fmtmsg' and `addseverity'. |
| |
| Low-Level I/O |
| |
| * Opening and Closing Files:: How to open and close file |
| descriptors. |
| * I/O Primitives:: Reading and writing data. |
| * File Position Primitive:: Setting a descriptor's file |
| position. |
| * Descriptors and Streams:: Converting descriptor to stream |
| or vice-versa. |
| * Stream/Descriptor Precautions:: Precautions needed if you use both |
| descriptors and streams. |
| * Scatter-Gather:: Fast I/O to discontinuous buffers. |
| * Memory-mapped I/O:: Using files like memory. |
| * Waiting for I/O:: How to check for input or output |
| on multiple file descriptors. |
| * Synchronizing I/O:: Making sure all I/O actions completed. |
| * Asynchronous I/O:: Perform I/O in parallel. |
| * Control Operations:: Various other operations on file |
| descriptors. |
| * Duplicating Descriptors:: Fcntl commands for duplicating |
| file descriptors. |
| * Descriptor Flags:: Fcntl commands for manipulating |
| flags associated with file |
| descriptors. |
| * File Status Flags:: Fcntl commands for manipulating |
| flags associated with open files. |
| * File Locks:: Fcntl commands for implementing |
| file locking. |
| * Interrupt Input:: Getting an asynchronous signal when |
| input arrives. |
| * IOCTLs:: Generic I/O Control operations. |
| |
| Stream/Descriptor Precautions |
| |
| * Linked Channels:: Dealing with channels sharing a file position. |
| * Independent Channels:: Dealing with separately opened, unlinked channels. |
| * Cleaning Streams:: Cleaning a stream makes it safe to use |
| another channel. |
| |
| Asynchronous I/O |
| |
| * Asynchronous Reads/Writes:: Asynchronous Read and Write Operations. |
| * Status of AIO Operations:: Getting the Status of AIO Operations. |
| * Synchronizing AIO Operations:: Getting into a consistent state. |
| * Cancel AIO Operations:: Cancellation of AIO Operations. |
| * Configuration of AIO:: How to optimize the AIO implementation. |
| |
| File Status Flags |
| |
| * Access Modes:: Whether the descriptor can read or write. |
| * Open-time Flags:: Details of `open'. |
| * Operating Modes:: Special modes to control I/O operations. |
| * Getting File Status Flags:: Fetching and changing these flags. |
| |
| File System Interface |
| |
| * Working Directory:: This is used to resolve relative |
| file names. |
| * Accessing Directories:: Finding out what files a directory |
| contains. |
| * Working with Directory Trees:: Apply actions to all files or a selectable |
| subset of a directory hierarchy. |
| * Hard Links:: Adding alternate names to a file. |
| * Symbolic Links:: A file that ``points to'' a file name. |
| * Deleting Files:: How to delete a file, and what that means. |
| * Renaming Files:: Changing a file's name. |
| * Creating Directories:: A system call just for creating a directory. |
| * File Attributes:: Attributes of individual files. |
| * Making Special Files:: How to create special files. |
| * Temporary Files:: Naming and creating temporary files. |
| |
| Accessing Directories |
| |
| * Directory Entries:: Format of one directory entry. |
| * Opening a Directory:: How to open a directory stream. |
| * Reading/Closing Directory:: How to read directory entries from the stream. |
| * Simple Directory Lister:: A very simple directory listing program. |
| * Random Access Directory:: Rereading part of the directory |
| already read with the same stream. |
| * Scanning Directory Content:: Get entries for user selected subset of |
| contents in given directory. |
| * Simple Directory Lister Mark II:: Revised version of the program. |
| |
| File Attributes |
| |
| * Attribute Meanings:: The names of the file attributes, |
| and what their values mean. |
| * Reading Attributes:: How to read the attributes of a file. |
| * Testing File Type:: Distinguishing ordinary files, |
| directories, links... |
| * File Owner:: How ownership for new files is determined, |
| and how to change it. |
| * Permission Bits:: How information about a file's access |
| mode is stored. |
| * Access Permission:: How the system decides who can access a file. |
| * Setting Permissions:: How permissions for new files are assigned, |
| and how to change them. |
| * Testing File Access:: How to find out if your process can |
| access a file. |
| * File Times:: About the time attributes of a file. |
| * File Size:: Manually changing the size of a file. |
| |
| Pipes and FIFOs |
| |
| * Creating a Pipe:: Making a pipe with the `pipe' function. |
| * Pipe to a Subprocess:: Using a pipe to communicate with a |
| child process. |
| * FIFO Special Files:: Making a FIFO special file. |
| * Pipe Atomicity:: When pipe (or FIFO) I/O is atomic. |
| |
| Sockets |
| |
| * Socket Concepts:: Basic concepts you need to know about. |
| * Communication Styles::Stream communication, datagrams and other styles. |
| * Socket Addresses:: How socket names (``addresses'') work. |
| * Interface Naming:: Identifying specific network interfaces. |
| * Local Namespace:: Details about the local namespace. |
| * Internet Namespace:: Details about the Internet namespace. |
| * Misc Namespaces:: Other namespaces not documented fully here. |
| * Open/Close Sockets:: Creating sockets and destroying them. |
| * Connections:: Operations on sockets with connection state. |
| * Datagrams:: Operations on datagram sockets. |
| * Inetd:: Inetd is a daemon that starts servers on request. |
| The most convenient way to write a server |
| is to make it work with Inetd. |
| * Socket Options:: Miscellaneous low-level socket options. |
| * Networks Database:: Accessing the database of network names. |
| |
| Socket Addresses |
| |
| * Address Formats:: About `struct sockaddr'. |
| * Setting Address:: Binding an address to a socket. |
| * Reading Address:: Reading the address of a socket. |
| |
| Local Namespace |
| |
| * Concepts: Local Namespace Concepts. What you need to understand. |
| * Details: Local Namespace Details. Address format, symbolic names, etc. |
| * Example: Local Socket Example. Example of creating a socket. |
| |
| Internet Namespace |
| |
| * Internet Address Formats:: How socket addresses are specified in the |
| Internet namespace. |
| * Host Addresses:: All about host addresses of Internet host. |
| * Ports:: Internet port numbers. |
| * Services Database:: Ports may have symbolic names. |
| * Byte Order:: Different hosts may use different byte |
| ordering conventions; you need to |
| canonicalize host address and port number. |
| * Protocols Database:: Referring to protocols by name. |
| * Inet Example:: Putting it all together. |
| |
| Host Addresses |
| |
| * Abstract Host Addresses:: What a host number consists of. |
| * Data type: Host Address Data Type. Data type for a host number. |
| * Functions: Host Address Functions. Functions to operate on them. |
| * Names: Host Names. Translating host names to host numbers. |
| |
| Open/Close Sockets |
| |
| * Creating a Socket:: How to open a socket. |
| * Closing a Socket:: How to close a socket. |
| * Socket Pairs:: These are created like pipes. |
| |
| Connections |
| |
| * Connecting:: What the client program must do. |
| * Listening:: How a server program waits for requests. |
| * Accepting Connections:: What the server does when it gets a request. |
| * Who is Connected:: Getting the address of the |
| other side of a connection. |
| * Transferring Data:: How to send and receive data. |
| * Byte Stream Example:: An example program: a client for communicating |
| over a byte stream socket in the Internet namespace. |
| * Server Example:: A corresponding server program. |
| * Out-of-Band Data:: This is an advanced feature. |
| |
| Transferring Data |
| |
| * Sending Data:: Sending data with `send'. |
| * Receiving Data:: Reading data with `recv'. |
| * Socket Data Options:: Using `send' and `recv'. |
| |
| Datagrams |
| |
| * Sending Datagrams:: Sending packets on a datagram socket. |
| * Receiving Datagrams:: Receiving packets on a datagram socket. |
| * Datagram Example:: An example program: packets sent over a |
| datagram socket in the local namespace. |
| * Example Receiver:: Another program, that receives those packets. |
| |
| Inetd |
| |
| * Inetd Servers:: |
| * Configuring Inetd:: |
| |
| Socket Options |
| |
| * Socket Option Functions:: The basic functions for setting and getting |
| socket options. |
| * Socket-Level Options:: Details of the options at the socket level. |
| |
| Low-Level Terminal Interface |
| |
| * Is It a Terminal:: How to determine if a file is a terminal |
| device, and what its name is. |
| * I/O Queues:: About flow control and typeahead. |
| * Canonical or Not:: Two basic styles of input processing. |
| * Terminal Modes:: How to examine and modify flags controlling |
| details of terminal I/O: echoing, |
| signals, editing. Posix. |
| * BSD Terminal Modes:: BSD compatible terminal mode setting |
| * Line Control:: Sending break sequences, clearing |
| terminal buffers ... |
| * Noncanon Example:: How to read single characters without echo. |
| * Pseudo-Terminals:: How to open a pseudo-terminal. |
| |
| Terminal Modes |
| |
| * Mode Data Types:: The data type `struct termios' and |
| related types. |
| * Mode Functions:: Functions to read and set the terminal |
| attributes. |
| * Setting Modes:: The right way to set terminal attributes |
| reliably. |
| * Input Modes:: Flags controlling low-level input handling. |
| * Output Modes:: Flags controlling low-level output handling. |
| * Control Modes:: Flags controlling serial port behavior. |
| * Local Modes:: Flags controlling high-level input handling. |
| * Line Speed:: How to read and set the terminal line speed. |
| * Special Characters:: Characters that have special effects, |
| and how to change them. |
| * Noncanonical Input:: Controlling how long to wait for input. |
| |
| Special Characters |
| |
| * Editing Characters:: Special characters that terminate lines and |
| delete text, and other editing functions. |
| * Signal Characters:: Special characters that send or raise signals |
| to or for certain classes of processes. |
| * Start/Stop Characters:: Special characters that suspend or resume |
| suspended output. |
| * Other Special:: Other special characters for BSD systems: |
| they can discard output, and print status. |
| |
| Pseudo-Terminals |
| |
| * Allocation:: Allocating a pseudo terminal. |
| * Pseudo-Terminal Pairs:: How to open both sides of a |
| pseudo-terminal in a single operation. |
| |
| Syslog |
| |
| * Overview of Syslog:: Overview of a system's Syslog facility |
| * Submitting Syslog Messages:: Functions to submit messages to Syslog |
| |
| Submitting Syslog Messages |
| |
| * openlog:: Open connection to Syslog |
| * syslog; vsyslog:: Submit message to Syslog |
| * closelog:: Close connection to Syslog |
| * setlogmask:: Cause certain messages to be ignored |
| * Syslog Example:: Example of all of the above |
| |
| Mathematics |
| |
| * Mathematical Constants:: Precise numeric values for often-used |
| constants. |
| * Trig Functions:: Sine, cosine, tangent, and friends. |
| * Inverse Trig Functions:: Arcsine, arccosine, etc. |
| * Exponents and Logarithms:: Also pow and sqrt. |
| * Hyperbolic Functions:: sinh, cosh, tanh, etc. |
| * Special Functions:: Bessel, gamma, erf. |
| * Errors in Math Functions:: Known Maximum Errors in Math Functions. |
| * Pseudo-Random Numbers:: Functions for generating pseudo-random |
| numbers. |
| * FP Function Optimizations:: Fast code or small code. |
| |
| Pseudo-Random Numbers |
| |
| * ISO Random:: `rand' and friends. |
| * BSD Random:: `random' and friends. |
| * SVID Random:: `drand48' and friends. |
| |
| Arithmetic |
| |
| * Integers:: Basic integer types and concepts |
| * Integer Division:: Integer division with guaranteed rounding. |
| * Floating Point Numbers:: Basic concepts. IEEE 754. |
| * Floating Point Classes:: The five kinds of floating-point number. |
| * Floating Point Errors:: When something goes wrong in a calculation. |
| * Rounding:: Controlling how results are rounded. |
| * Control Functions:: Saving and restoring the FPU's state. |
| * Arithmetic Functions:: Fundamental operations provided by the library. |
| * Complex Numbers:: The types. Writing complex constants. |
| * Operations on Complex:: Projection, conjugation, decomposition. |
| * Parsing of Numbers:: Converting strings to numbers. |
| * System V Number Conversion:: An archaic way to convert numbers to strings. |
| |
| Floating Point Errors |
| |
| * FP Exceptions:: IEEE 754 math exceptions and how to detect them. |
| * Infinity and NaN:: Special values returned by calculations. |
| * Status bit operations:: Checking for exceptions after the fact. |
| * Math Error Reporting:: How the math functions report errors. |
| |
| Arithmetic Functions |
| |
| * Absolute Value:: Absolute values of integers and floats. |
| * Normalization Functions:: Extracting exponents and putting them back. |
| * Rounding Functions:: Rounding floats to integers. |
| * Remainder Functions:: Remainders on division, precisely defined. |
| * FP Bit Twiddling:: Sign bit adjustment. Adding epsilon. |
| * FP Comparison Functions:: Comparisons without risk of exceptions. |
| * Misc FP Arithmetic:: Max, min, positive difference, multiply-add. |
| |
| Parsing of Numbers |
| |
| * Parsing of Integers:: Functions for conversion of integer values. |
| * Parsing of Floats:: Functions for conversion of floating-point |
| values. |
| |
| Date and Time |
| |
| * Time Basics:: Concepts and definitions. |
| * Elapsed Time:: Data types to represent elapsed times |
| * Processor And CPU Time:: Time a program has spent executing. |
| * Calendar Time:: Manipulation of ``real'' dates and times. |
| * Setting an Alarm:: Sending a signal after a specified time. |
| * Sleeping:: Waiting for a period of time. |
| |
| Processor And CPU Time |
| |
| * CPU Time:: The `clock' function. |
| * Processor Time:: The `times' function. |
| |
| Calendar Time |
| |
| * Simple Calendar Time:: Facilities for manipulating calendar time. |
| * High-Resolution Calendar:: A time representation with greater precision. |
| * Broken-down Time:: Facilities for manipulating local time. |
| * High Accuracy Clock:: Maintaining a high accuracy system clock. |
| * Formatting Calendar Time:: Converting times to strings. |
| * Parsing Date and Time:: Convert textual time and date information back |
| into broken-down time values. |
| * TZ Variable:: How users specify the time zone. |
| * Time Zone Functions:: Functions to examine or specify the time zone. |
| * Time Functions Example:: An example program showing use of some of |
| the time functions. |
| |
| Parsing Date and Time |
| |
| * Low-Level Time String Parsing:: Interpret string according to given format. |
| * General Time String Parsing:: User-friendly function to parse data and |
| time strings. |
| |
| Resource Usage And Limitation |
| |
| * Resource Usage:: Measuring various resources used. |
| * Limits on Resources:: Specifying limits on resource usage. |
| * Priority:: Reading or setting process run priority. |
| * Memory Resources:: Querying memory available resources. |
| * Processor Resources:: Learn about the processors available. |
| |
| Priority |
| |
| * Absolute Priority:: The first tier of priority. Posix |
| * Realtime Scheduling:: Scheduling among the process nobility |
| * Basic Scheduling Functions:: Get/set scheduling policy, priority |
| * Traditional Scheduling:: Scheduling among the vulgar masses |
| * CPU Affinity:: Limiting execution to certain CPUs |
| |
| Traditional Scheduling |
| |
| * Traditional Scheduling Intro:: |
| * Traditional Scheduling Functions:: |
| |
| Memory Resources |
| |
| * Memory Subsystem:: Overview about traditional Unix memory handling. |
| * Query Memory Parameters:: How to get information about the memory |
| subsystem? |
| |
| Non-Local Exits |
| |
| * Intro: Non-Local Intro. When and how to use these facilities. |
| * Details: Non-Local Details. Functions for non-local exits. |
| * Non-Local Exits and Signals:: Portability issues. |
| * System V contexts:: Complete context control a la System V. |
| |
| Signal Handling |
| |
| * Concepts of Signals:: Introduction to the signal facilities. |
| * Standard Signals:: Particular kinds of signals with |
| standard names and meanings. |
| * Signal Actions:: Specifying what happens when a |
| particular signal is delivered. |
| * Defining Handlers:: How to write a signal handler function. |
| * Interrupted Primitives:: Signal handlers affect use of `open', |
| `read', `write' and other functions. |
| * Generating Signals:: How to send a signal to a process. |
| * Blocking Signals:: Making the system hold signals temporarily. |
| * Waiting for a Signal:: Suspending your program until a signal |
| arrives. |
| * Signal Stack:: Using a Separate Signal Stack. |
| * BSD Signal Handling:: Additional functions for backward |
| compatibility with BSD. |
| |
| Concepts of Signals |
| |
| * Kinds of Signals:: Some examples of what can cause a signal. |
| * Signal Generation:: Concepts of why and how signals occur. |
| * Delivery of Signal:: Concepts of what a signal does to the |
| process. |
| |
| Standard Signals |
| |
| * Program Error Signals:: Used to report serious program errors. |
| * Termination Signals:: Used to interrupt and/or terminate the |
| program. |
| * Alarm Signals:: Used to indicate expiration of timers. |
| * Asynchronous I/O Signals:: Used to indicate input is available. |
| * Job Control Signals:: Signals used to support job control. |
| * Operation Error Signals:: Used to report operational system errors. |
| * Miscellaneous Signals:: Miscellaneous Signals. |
| * Signal Messages:: Printing a message describing a signal. |
| |
| Signal Actions |
| |
| * Basic Signal Handling:: The simple `signal' function. |
| * Advanced Signal Handling:: The more powerful `sigaction' function. |
| * Signal and Sigaction:: How those two functions interact. |
| * Sigaction Function Example:: An example of using the sigaction function. |
| * Flags for Sigaction:: Specifying options for signal handling. |
| * Initial Signal Actions:: How programs inherit signal actions. |
| |
| Defining Handlers |
| |
| * Handler Returns:: Handlers that return normally, and what |
| this means. |
| * Termination in Handler:: How handler functions terminate a program. |
| * Longjmp in Handler:: Nonlocal transfer of control out of a |
| signal handler. |
| * Signals in Handler:: What happens when signals arrive while |
| the handler is already occupied. |
| * Merged Signals:: When a second signal arrives before the |
| first is handled. |
| * Nonreentrancy:: Do not call any functions unless you know they |
| are reentrant with respect to signals. |
| * Atomic Data Access:: A single handler can run in the middle of |
| reading or writing a single object. |
| |
| Atomic Data Access |
| |
| * Non-atomic Example:: A program illustrating interrupted access. |
| * Types: Atomic Types. Data types that guarantee no interruption. |
| * Usage: Atomic Usage. Proving that interruption is harmless. |
| |
| Generating Signals |
| |
| * Signaling Yourself:: A process can send a signal to itself. |
| * Signaling Another Process:: Send a signal to another process. |
| * Permission for kill:: Permission for using `kill'. |
| * Kill Example:: Using `kill' for Communication. |
| |
| Blocking Signals |
| |
| * Why Block:: The purpose of blocking signals. |
| * Signal Sets:: How to specify which signals to |
| block. |
| * Process Signal Mask:: Blocking delivery of signals to your |
| process during normal execution. |
| * Testing for Delivery:: Blocking to Test for Delivery of |
| a Signal. |
| * Blocking for Handler:: Blocking additional signals while a |
| handler is being run. |
| * Checking for Pending Signals:: Checking for Pending Signals |
| * Remembering a Signal:: How you can get almost the same |
| effect as blocking a signal, by |
| handling it and setting a flag |
| to be tested later. |
| |
| Waiting for a Signal |
| |
| * Using Pause:: The simple way, using `pause'. |
| * Pause Problems:: Why the simple way is often not very good. |
| * Sigsuspend:: Reliably waiting for a specific signal. |
| |
| BSD Signal Handling |
| |
| * BSD Handler:: BSD Function to Establish a Handler. |
| * Blocking in BSD:: BSD Functions for Blocking Signals. |
| |
| Program Basics |
| |
| * Program Arguments:: Parsing your program's command-line arguments |
| * Environment Variables:: Less direct parameters affecting your program |
| * Auxiliary Vector:: Least direct parameters affecting your program |
| * System Calls:: Requesting service from the system |
| * Program Termination:: Telling the system you're done; return status |
| |
| Program Arguments |
| |
| * Argument Syntax:: By convention, options start with a hyphen. |
| * Parsing Program Arguments:: Ways to parse program options and arguments. |
| |
| Parsing Program Arguments |
| |
| * Getopt:: Parsing program options using `getopt'. |
| * Argp:: Parsing program options using `argp_parse'. |
| * Suboptions:: Some programs need more detailed options. |
| * Suboptions Example:: This shows how it could be done for `mount'. |
| |
| Environment Variables |
| |
| * Environment Access:: How to get and set the values of |
| environment variables. |
| * Standard Environment:: These environment variables have |
| standard interpretations. |
| |
| Program Termination |
| |
| * Normal Termination:: If a program calls `exit', a |
| process terminates normally. |
| * Exit Status:: The `exit status' provides information |
| about why the process terminated. |
| * Cleanups on Exit:: A process can run its own cleanup |
| functions upon normal termination. |
| * Aborting a Program:: The `abort' function causes |
| abnormal program termination. |
| * Termination Internals:: What happens when a process terminates. |
| |
| Processes |
| |
| * Running a Command:: The easy way to run another program. |
| * Process Creation Concepts:: An overview of the hard way to do it. |
| * Process Identification:: How to get the process ID of a process. |
| * Creating a Process:: How to fork a child process. |
| * Executing a File:: How to make a process execute another program. |
| * Process Completion:: How to tell when a child process has completed. |
| * Process Completion Status:: How to interpret the status value |
| returned from a child process. |
| * BSD Wait Functions:: More functions, for backward compatibility. |
| * Process Creation Example:: A complete example program. |
| |
| Job Control |
| |
| * Concepts of Job Control:: Jobs can be controlled by a shell. |
| * Job Control is Optional:: Not all POSIX systems support job control. |
| * Controlling Terminal:: How a process gets its controlling terminal. |
| * Access to the Terminal:: How processes share the controlling terminal. |
| * Orphaned Process Groups:: Jobs left after the user logs out. |
| * Implementing a Shell:: What a shell must do to implement job control. |
| * Functions for Job Control:: Functions to control process groups. |
| |
| Implementing a Shell |
| |
| * Data Structures:: Introduction to the sample shell. |
| * Initializing the Shell:: What the shell must do to take |
| responsibility for job control. |
| * Launching Jobs:: Creating jobs to execute commands. |
| * Foreground and Background:: Putting a job in foreground of background. |
| * Stopped and Terminated Jobs:: Reporting job status. |
| * Continuing Stopped Jobs:: How to continue a stopped job in |
| the foreground or background. |
| * Missing Pieces:: Other parts of the shell. |
| |
| Functions for Job Control |
| |
| * 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. |
| |
| Name Service Switch |
| |
| * 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. |
| |
| NSS Configuration File |
| |
| * 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. |
| |
| NSS Module Internals |
| |
| * NSS Module Names:: Construction of the interface function of |
| the NSS modules. |
| * NSS Modules Interface:: Programming interface in the NSS module |
| functions. |
| |
| Extending NSS |
| |
| * 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. |
| |
| Users and Groups |
| |
| * 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. |
| |
| User Accounting Database |
| |
| * 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. |
| |
| User Database |
| |
| * 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. |
| |
| Group Database |
| |
| * 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. |
| |
| Netgroup Database |
| |
| * 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. |
| |
| System Management |
| |
| * 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 |
| |
| Filesystem Handling |
| |
| * Mount Information:: What is or could be mounted? |
| * Mount-Unmount-Remount:: Controlling what is mounted and how |
| |
| Mount Information |
| |
| * fstab:: The `fstab' file |
| * mtab:: The `mtab' file |
| * Other Mount Information:: Other (non-libc) sources of mount information |
| |
| System Configuration |
| |
| * 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. |
| |
| Sysconf |
| |
| * 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. |
| |
| Cryptographic Functions |
| |
| * Legal Problems:: This software can get you locked up, or worse. |
| * getpass:: Prompting the user for a password. |
| * crypt:: A one-way function for passwords. |
| * DES Encryption:: Routines for DES encryption. |
| |
| Debugging Support |
| |
| * Backtraces:: Obtaining and printing a back trace of the |
| current stack. |
| |
| POSIX Threads |
| |
| * Thread-specific Data:: Support for creating and |
| managing thread-specific data |
| * Non-POSIX Extensions:: Additional functions to extend |
| POSIX Thread functionality |
| |
| Non-POSIX Extensions |
| |
| * Default Thread Attributes:: Setting default attributes for |
| threads in a process. |
| |
| Internal Probes |
| |
| * Memory Allocation Probes:: Probes in the memory allocation subsystem |
| * Mathematical Function Probes:: Probes in mathematical functions |
| |
| Language Features |
| |
| * Consistency Checking:: Using `assert' to abort if |
| something ``impossible'' happens. |
| * Variadic Functions:: Defining functions with varying numbers |
| of args. |
| * Null Pointer Constant:: The macro `NULL'. |
| * Important Data Types:: Data types for object sizes. |
| * Data Type Measurements:: Parameters of data type representations. |
| |
| Variadic Functions |
| |
| * Why Variadic:: Reasons for making functions take |
| variable arguments. |
| * How Variadic:: How to define and call variadic functions. |
| * Variadic Example:: A complete example. |
| |
| How Variadic |
| |
| * Variadic Prototypes:: How to make a prototype for a function |
| with variable arguments. |
| * Receiving Arguments:: Steps you must follow to access the |
| optional argument values. |
| * How Many Arguments:: How to decide whether there are more arguments. |
| * Calling Variadics:: Things you need to know about calling |
| variable arguments functions. |
| * Argument Macros:: Detailed specification of the macros |
| for accessing variable arguments. |
| |
| Data Type Measurements |
| |
| * Width of Type:: How many bits does an integer type hold? |
| * Range of Type:: What are the largest and smallest values |
| that an integer type can hold? |
| * Floating Type Macros:: Parameters that measure the floating point types. |
| * Structure Measurement:: Getting measurements on structure types. |
| |
| Floating Type Macros |
| |
| * Floating Point Concepts:: Definitions of terminology. |
| * Floating Point Parameters:: Details of specific macros. |
| * IEEE Floating Point:: The measurements for one common |
| representation. |
| |
| Installation |
| |
| * Configuring and compiling:: How to compile and test GNU libc. |
| * Running make install:: How to install it once you've got it |
| compiled. |
| * Tools for Compilation:: You'll need these first. |
| * Linux:: Specific advice for GNU/Linux systems. |
| * Reporting Bugs:: So they'll get fixed. |
| |
| Maintenance |
| |
| * Source Layout:: How to add new functions or header files |
| to the GNU C Library. |
| * Porting:: How to port the GNU C Library to |
| a new machine or operating system. |
| |
| Source Layout |
| |
| * Platform: Adding Platform-specific. Adding platform-specific |
| features. |
| |
| Porting |
| |
| * Hierarchy Conventions:: The layout of the `sysdeps' hierarchy. |
| * Porting to Unix:: Porting the library to an average |
| Unix-like system. |
| |
| Platform |
| |
| * PowerPC:: Facilities Specific to the PowerPC Architecture |
| |
| |
| File: libc.info, Node: Introduction, Next: Error Reporting, Prev: Top, Up: Top |
| |
| 1 Introduction |
| ************** |
| |
| The C language provides no built-in facilities for performing such |
| common operations as input/output, memory management, string |
| manipulation, and the like. Instead, these facilities are defined in a |
| standard "library", which you compile and link with your programs. |
| |
| The GNU C Library, described in this document, defines all of the |
| library functions that are specified by the ISO C standard, as well as |
| additional features specific to POSIX and other derivatives of the Unix |
| operating system, and extensions specific to GNU systems. |
| |
| The purpose of this manual is to tell you how to use the facilities |
| of the GNU C Library. We have mentioned which features belong to which |
| standards to help you identify things that are potentially non-portable |
| to other systems. But the emphasis in this manual is not on strict |
| portability. |
| |
| * Menu: |
| |
| * Getting Started:: What this manual is for and how to use it. |
| * Standards and Portability:: Standards and sources upon which the GNU |
| C library is based. |
| * Using the Library:: Some practical uses for the library. |
| * Roadmap to the Manual:: Overview of the remaining chapters in |
| this manual. |
| |
| |
| File: libc.info, Node: Getting Started, Next: Standards and Portability, Up: Introduction |
| |
| 1.1 Getting Started |
| =================== |
| |
| This manual is written with the assumption that you are at least |
| somewhat familiar with the C programming language and basic programming |
| concepts. Specifically, familiarity with ISO standard C (*note ISO |
| C::), rather than "traditional" pre-ISO C dialects, is assumed. |
| |
| The GNU C Library includes several "header files", each of which |
| provides definitions and declarations for a group of related facilities; |
| this information is used by the C compiler when processing your program. |
| For example, the header file `stdio.h' declares facilities for |
| performing input and output, and the header file `string.h' declares |
| string processing utilities. The organization of this manual generally |
| follows the same division as the header files. |
| |
| If you are reading this manual for the first time, you should read |
| all of the introductory material and skim the remaining chapters. |
| There are a _lot_ of functions in the GNU C Library and it's not |
| realistic to expect that you will be able to remember exactly _how_ to |
| use each and every one of them. It's more important to become |
| generally familiar with the kinds of facilities that the library |
| provides, so that when you are writing your programs you can recognize |
| _when_ to make use of library functions, and _where_ in this manual you |
| can find more specific information about them. |
| |
| |
| File: libc.info, Node: Standards and Portability, Next: Using the Library, Prev: Getting Started, Up: Introduction |
| |
| 1.2 Standards and Portability |
| ============================= |
| |
| This section discusses the various standards and other sources that the |
| GNU C Library is based upon. These sources include the ISO C and POSIX |
| standards, and the System V and Berkeley Unix implementations. |
| |
| The primary focus of this manual is to tell you how to make effective |
| use of the GNU C Library facilities. But if you are concerned about |
| making your programs compatible with these standards, or portable to |
| operating systems other than GNU, this can affect how you use the |
| library. This section gives you an overview of these standards, so that |
| you will know what they are when they are mentioned in other parts of |
| the manual. |
| |
| *Note Library Summary::, for an alphabetical list of the functions |
| and other symbols provided by the library. This list also states which |
| standards each function or symbol comes from. |
| |
| * Menu: |
| |
| * ISO C:: The international standard for the C |
| programming language. |
| * POSIX:: The ISO/IEC 9945 (aka IEEE 1003) standards |
| for operating systems. |
| * Berkeley Unix:: BSD and SunOS. |
| * SVID:: The System V Interface Description. |
| * XPG:: The X/Open Portability Guide. |
| |
| |
| File: libc.info, Node: ISO C, Next: POSIX, Up: Standards and Portability |
| |
| 1.2.1 ISO C |
| ----------- |
| |
| The GNU C Library is compatible with the C standard adopted by the |
| American National Standards Institute (ANSI): `American National |
| Standard X3.159-1989--"ANSI C"' and later by the International |
| Standardization Organization (ISO): `ISO/IEC 9899:1990, "Programming |
| languages--C"'. We here refer to the standard as ISO C since this is |
| the more general standard in respect of ratification. The header files |
| and library facilities that make up the GNU C Library are a superset of |
| those specified by the ISO C standard. |
| |
| If you are concerned about strict adherence to the ISO C standard, |
| you should use the `-ansi' option when you compile your programs with |
| the GNU C compiler. This tells the compiler to define _only_ ISO |
| standard features from the library header files, unless you explicitly |
| ask for additional features. *Note Feature Test Macros::, for |
| information on how to do this. |
| |
| Being able to restrict the library to include only ISO C features is |
| important because ISO C puts limitations on what names can be defined |
| by the library implementation, and the GNU extensions don't fit these |
| limitations. *Note Reserved Names::, for more information about these |
| restrictions. |
| |
| This manual does not attempt to give you complete details on the |
| differences between ISO C and older dialects. It gives advice on how |
| to write programs to work portably under multiple C dialects, but does |
| not aim for completeness. |
| |
| |
| File: libc.info, Node: POSIX, Next: Berkeley Unix, Prev: ISO C, Up: Standards and Portability |
| |
| 1.2.2 POSIX (The Portable Operating System Interface) |
| ----------------------------------------------------- |
| |
| The GNU C Library is also compatible with the ISO "POSIX" family of |
| standards, known more formally as the "Portable Operating System |
| Interface for Computer Environments" (ISO/IEC 9945). They were also |
| published as ANSI/IEEE Std 1003. POSIX is derived mostly from various |
| versions of the Unix operating system. |
| |
| The library facilities specified by the POSIX standards are a |
| superset of those required by ISO C; POSIX specifies additional |
| features for ISO C functions, as well as specifying new additional |
| functions. In general, the additional requirements and functionality |
| defined by the POSIX standards are aimed at providing lower-level |
| support for a particular kind of operating system environment, rather |
| than general programming language support which can run in many diverse |
| operating system environments. |
| |
| The GNU C Library implements all of the functions specified in |
| `ISO/IEC 9945-1:1996, the POSIX System Application Program Interface', |
| commonly referred to as POSIX.1. The primary extensions to the ISO C |
| facilities specified by this standard include file system interface |
| primitives (*note File System Interface::), device-specific terminal |
| control functions (*note Low-Level Terminal Interface::), and process |
| control functions (*note Processes::). |
| |
| Some facilities from `ISO/IEC 9945-2:1993, the POSIX Shell and |
| Utilities standard' (POSIX.2) are also implemented in the GNU C Library. |
| These include utilities for dealing with regular expressions and other |
| pattern matching facilities (*note Pattern Matching::). |
| |
| * Menu: |
| |
| * POSIX Safety Concepts:: Safety concepts from POSIX. |
| * Unsafe Features:: Features that make functions unsafe. |
| * Conditionally Safe Features:: Features that make functions unsafe |
| in the absence of workarounds. |
| * Other Safety Remarks:: Additional safety features and remarks. |
| |
| |
| File: libc.info, Node: POSIX Safety Concepts, Next: Unsafe Features, Up: POSIX |
| |
| 1.2.2.1 POSIX Safety Concepts |
| ............................. |
| |
| This manual documents various safety properties of GNU C Library |
| functions, in lines that follow their prototypes and look like: |
| |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | |
| |
| The properties are assessed according to the criteria set forth in |
| the POSIX standard for such safety contexts as Thread-, Async-Signal- |
| and Async-Cancel- -Safety. Intuitive definitions of these properties, |
| attempting to capture the meaning of the standard definitions, follow. |
| |
| * `MT-Safe' or Thread-Safe functions are safe to call in the presence |
| of other threads. MT, in MT-Safe, stands for Multi Thread. |
| |
| Being MT-Safe does not imply a function is atomic, nor that it |
| uses any of the memory synchronization mechanisms POSIX exposes to |
| users. It is even possible that calling MT-Safe functions in |
| sequence does not yield an MT-Safe combination. For example, |
| having a thread call two MT-Safe functions one right after the |
| other does not guarantee behavior equivalent to atomic execution |
| of a combination of both functions, since concurrent calls in |
| other threads may interfere in a destructive way. |
| |
| Whole-program optimizations that could inline functions across |
| library interfaces may expose unsafe reordering, and so performing |
| inlining across the GNU C Library interface is not recommended. |
| The documented MT-Safety status is not guaranteed under |
| whole-program optimization. However, functions defined in |
| user-visible headers are designed to be safe for inlining. |
| |
| * `AS-Safe' or Async-Signal-Safe functions are safe to call from |
| asynchronous signal handlers. AS, in AS-Safe, stands for |
| Asynchronous Signal. |
| |
| Many functions that are AS-Safe may set `errno', or modify the |
| floating-point environment, because their doing so does not make |
| them unsuitable for use in signal handlers. However, programs |
| could misbehave should asynchronous signal handlers modify this |
| thread-local state, and the signal handling machinery cannot be |
| counted on to preserve it. Therefore, signal handlers that call |
| functions that may set `errno' or modify the floating-point |
| environment _must_ save their original values, and restore them |
| before returning. |
| |
| * `AC-Safe' or Async-Cancel-Safe functions are safe to call when |
| asynchronous cancellation is enabled. AC in AC-Safe stands for |
| Asynchronous Cancellation. |
| |
| The POSIX standard defines only three functions to be AC-Safe, |
| namely `pthread_cancel', `pthread_setcancelstate', and |
| `pthread_setcanceltype'. At present the GNU C Library provides no |
| guarantees beyond these three functions, but does document which |
| functions are presently AC-Safe. This documentation is provided |
| for use by the GNU C Library developers. |
| |
| Just like signal handlers, cancellation cleanup routines must |
| configure the floating point environment they require. The |
| routines cannot assume a floating point environment, particularly |
| when asynchronous cancellation is enabled. If the configuration |
| of the floating point environment cannot be performed atomically |
| then it is also possible that the environment encountered is |
| internally inconsistent. |
| |
| * `MT-Unsafe', `AS-Unsafe', `AC-Unsafe' functions are not safe to |
| call within the safety contexts described above. Calling them |
| within such contexts invokes undefined behavior. |
| |
| Functions not explicitly documented as safe in a safety context |
| should be regarded as Unsafe. |
| |
| * `Preliminary' safety properties are documented, indicating these |
| properties may _not_ be counted on in future releases of the GNU C |
| Library. |
| |
| Such preliminary properties are the result of an assessment of the |
| properties of our current implementation, rather than of what is |
| mandated and permitted by current and future standards. |
| |
| Although we strive to abide by the standards, in some cases our |
| implementation is safe even when the standard does not demand |
| safety, and in other cases our implementation does not meet the |
| standard safety requirements. The latter are most likely bugs; |
| the former, when marked as `Preliminary', should not be counted |
| on: future standards may require changes that are not compatible |
| with the additional safety properties afforded by the current |
| implementation. |
| |
| Furthermore, the POSIX standard does not offer a detailed |
| definition of safety. We assume that, by "safe to call", POSIX |
| means that, as long as the program does not invoke undefined |
| behavior, the "safe to call" function behaves as specified, and |
| does not cause other functions to deviate from their specified |
| behavior. We have chosen to use its loose definitions of safety, |
| not because they are the best definitions to use, but because |
| choosing them harmonizes this manual with POSIX. |
| |
| Please keep in mind that these are preliminary definitions and |
| annotations, and certain aspects of the definitions are still under |
| discussion and might be subject to clarification or change. |
| |
| Over time, we envision evolving the preliminary safety notes into |
| stable commitments, as stable as those of our interfaces. As we |
| do, we will remove the `Preliminary' keyword from safety notes. |
| As long as the keyword remains, however, they are not to be |
| regarded as a promise of future behavior. |
| |
| |
| Other keywords that appear in safety notes are defined in subsequent |
| sections. |
| |
| |
| File: libc.info, Node: Unsafe Features, Next: Conditionally Safe Features, Prev: POSIX Safety Concepts, Up: POSIX |
| |
| 1.2.2.2 Unsafe Features |
| ....................... |
| |
| Functions that are unsafe to call in certain contexts are annotated with |
| keywords that document their features that make them unsafe to call. |
| AS-Unsafe features in this section indicate the functions are never safe |
| to call when asynchronous signals are enabled. AC-Unsafe features |
| indicate they are never safe to call when asynchronous cancellation is |
| enabled. There are no MT-Unsafe marks in this section. |
| |
| * `lock' |
| |
| Functions marked with `lock' as an AS-Unsafe feature may be |
| interrupted by a signal while holding a non-recursive lock. If the |
| signal handler calls another such function that takes the same |
| lock, the result is a deadlock. |
| |
| Functions annotated with `lock' as an AC-Unsafe feature may, if |
| cancelled asynchronously, fail to release a lock that would have |
| been released if their execution had not been interrupted by |
| asynchronous thread cancellation. Once a lock is left taken, |
| attempts to take that lock will block indefinitely. |
| |
| * `corrupt' |
| |
| Functions marked with `corrupt' as an AS-Unsafe feature may corrupt |
| data structures and misbehave when they interrupt, or are |
| interrupted by, another such function. Unlike functions marked |
| with `lock', these take recursive locks to avoid MT-Safety |
| problems, but this is not enough to stop a signal handler from |
| observing a partially-updated data structure. Further corruption |
| may arise from the interrupted function's failure to notice |
| updates made by signal handlers. |
| |
| Functions marked with `corrupt' as an AC-Unsafe feature may leave |
| data structures in a corrupt, partially updated state. Subsequent |
| uses of the data structure may misbehave. |
| |
| * `heap' |
| |
| Functions marked with `heap' may call heap memory management |
| functions from the `malloc'/`free' family of functions and are |
| only as safe as those functions. This note is thus equivalent to: |
| |
| | AS-Unsafe lock | AC-Unsafe lock fd mem | |
| |
| * `dlopen' |
| |
| Functions marked with `dlopen' use the dynamic loader to load |
| shared libraries into the current execution image. This involves |
| opening files, mapping them into memory, allocating additional |
| memory, resolving symbols, applying relocations and more, all of |
| this while holding internal dynamic loader locks. |
| |
| The locks are enough for these functions to be AS- and AC-Unsafe, |
| but other issues may arise. At present this is a placeholder for |
| all potential safety issues raised by `dlopen'. |
| |
| * `plugin' |
| |
| Functions annotated with `plugin' may run code from plugins that |
| may be external to the GNU C Library. Such plugin functions are |
| assumed to be MT-Safe, AS-Unsafe and AC-Unsafe. Examples of such |
| plugins are stack unwinding libraries, name service switch (NSS) |
| and character set conversion (iconv) back-ends. |
| |
| Although the plugins mentioned as examples are all brought in by |
| means of dlopen, the `plugin' keyword does not imply any direct |
| involvement of the dynamic loader or the `libdl' interfaces, those |
| are covered by `dlopen'. For example, if one function loads a |
| module and finds the addresses of some of its functions, while |
| another just calls those already-resolved functions, the former |
| will be marked with `dlopen', whereas the latter will get the |
| `plugin'. When a single function takes all of these actions, then |
| it gets both marks. |
| |
| * `i18n' |
| |
| Functions marked with `i18n' may call internationalization |
| functions of the `gettext' family and will be only as safe as those |
| functions. This note is thus equivalent to: |
| |
| | MT-Safe env | AS-Unsafe corrupt heap dlopen | AC-Unsafe corrupt | |
| |
| * `timer' |
| |
| Functions marked with `timer' use the `alarm' function or similar |
| to set a time-out for a system call or a long-running operation. |
| In a multi-threaded program, there is a risk that the time-out |
| signal will be delivered to a different thread, thus failing to |
| interrupt the intended thread. Besides being MT-Unsafe, such |
| functions are always AS-Unsafe, because calling them in signal |
| handlers may interfere with timers set in the interrupted code, |
| and AC-Unsafe, because there is no safe way to guarantee an |
| earlier timer will be reset in case of asynchronous cancellation. |
| |
| |
| |
| File: libc.info, Node: Conditionally Safe Features, Next: Other Safety Remarks, Prev: Unsafe Features, Up: POSIX |
| |
| 1.2.2.3 Conditionally Safe Features |
| ................................... |
| |
| For some features that make functions unsafe to call in certain |
| contexts, there are known ways to avoid the safety problem other than |
| refraining from calling the function altogether. The keywords that |
| follow refer to such features, and each of their definitions indicate |
| how the whole program needs to be constrained in order to remove the |
| safety problem indicated by the keyword. Only when all the reasons that |
| make a function unsafe are observed and addressed, by applying the |
| documented constraints, does the function become safe to call in a |
| context. |
| |
| * `init' |
| |
| Functions marked with `init' as an MT-Unsafe feature perform |
| MT-Unsafe initialization when they are first called. |
| |
| Calling such a function at least once in single-threaded mode |
| removes this specific cause for the function to be regarded as |
| MT-Unsafe. If no other cause for that remains, the function can |
| then be safely called after other threads are started. |
| |
| Functions marked with `init' as an AS- or AC-Unsafe feature use the |
| internal `libc_once' machinery or similar to initialize internal |
| data structures. |
| |
| If a signal handler interrupts such an initializer, and calls any |
| function that also performs `libc_once' initialization, it will |
| deadlock if the thread library has been loaded. |
| |
| Furthermore, if an initializer is partially complete before it is |
| canceled or interrupted by a signal whose handler requires the same |
| initialization, some or all of the initialization may be performed |
| more than once, leaking resources or even resulting in corrupt |
| internal data. |
| |
| Applications that need to call functions marked with `init' as an |
| AS- or AC-Unsafe feature should ensure the initialization is |
| performed before configuring signal handlers or enabling |
| cancellation, so that the AS- and AC-Safety issues related with |
| `libc_once' do not arise. |
| |
| * `race' |
| |
| Functions annotated with `race' as an MT-Safety issue operate on |
| objects in ways that may cause data races or similar forms of |
| destructive interference out of concurrent execution. In some |
| cases, the objects are passed to the functions by users; in |
| others, they are used by the functions to return values to users; |
| in others, they are not even exposed to users. |
| |
| We consider access to objects passed as (indirect) arguments to |
| functions to be data race free. The assurance of data race free |
| objects is the caller's responsibility. We will not mark a |
| function as MT-Unsafe or AS-Unsafe if it misbehaves when users |
| fail to take the measures required by POSIX to avoid data races |
| when dealing with such objects. As a general rule, if a function |
| is documented as reading from an object passed (by reference) to |
| it, or modifying it, users ought to use memory synchronization |
| primitives to avoid data races just as they would should they |
| perform the accesses themselves rather than by calling the library |
| function. `FILE' streams are the exception to the general rule, |
| in that POSIX mandates the library to guard against data races in |
| many functions that manipulate objects of this specific opaque |
| type. We regard this as a convenience provided to users, rather |
| than as a general requirement whose expectations should extend to |
| other types. |
| |
| In order to remind users that guarding certain arguments is their |
| responsibility, we will annotate functions that take objects of |
| certain types as arguments. We draw the line for objects passed |
| by users as follows: objects whose types are exposed to users, and |
| that users are expected to access directly, such as memory |
| buffers, strings, and various user-visible `struct' types, do |
| _not_ give reason for functions to be annotated with `race'. It |
| would be noisy and redundant with the general requirement, and not |
| many would be surprised by the library's lack of internal guards |
| when accessing objects that can be accessed directly by users. |
| |
| As for objects that are opaque or opaque-like, in that they are to |
| be manipulated only by passing them to library functions (e.g., |
| `FILE', `DIR', `obstack', `iconv_t'), there might be additional |
| expectations as to internal coordination of access by the library. |
| We will annotate, with `race' followed by a colon and the argument |
| name, functions that take such objects but that do not take care |
| of synchronizing access to them by default. For example, `FILE' |
| stream `unlocked' functions will be annotated, but those that |
| perform implicit locking on `FILE' streams by default will not, |
| even though the implicit locking may be disabled on a per-stream |
| basis. |
| |
| In either case, we will not regard as MT-Unsafe functions that may |
| access user-supplied objects in unsafe ways should users fail to |
| ensure the accesses are well defined. The notion prevails that |
| users are expected to safeguard against data races any |
| user-supplied objects that the library accesses on their behalf. |
| |
| This user responsibility does not apply, however, to objects |
| controlled by the library itself, such as internal objects and |
| static buffers used to return values from certain calls. When the |
| library doesn't guard them against concurrent uses, these cases |
| are regarded as MT-Unsafe and AS-Unsafe (although the `race' mark |
| under AS-Unsafe will be omitted as redundant with the one under |
| MT-Unsafe). As in the case of user-exposed objects, the mark may |
| be followed by a colon and an identifier. The identifier groups |
| all functions that operate on a certain unguarded object; users |
| may avoid the MT-Safety issues related with unguarded concurrent |
| access to such internal objects by creating a non-recursive mutex |
| related with the identifier, and always holding the mutex when |
| calling any function marked as racy on that identifier, as they |
| would have to should the identifier be an object under user |
| control. The non-recursive mutex avoids the MT-Safety issue, but |
| it trades one AS-Safety issue for another, so use in asynchronous |
| signals remains undefined. |
| |
| When the identifier relates to a static buffer used to hold return |
| values, the mutex must be held for as long as the buffer remains |
| in use by the caller. Many functions that return pointers to |
| static buffers offer reentrant variants that store return values |
| in caller-supplied buffers instead. In some cases, such as |
| `tmpname', the variant is chosen not by calling an alternate entry |
| point, but by passing a non-`NULL' pointer to the buffer in which |
| the returned values are to be stored. These variants are |
| generally preferable in multi-threaded programs, although some of |
| them are not MT-Safe because of other internal buffers, also |
| documented with `race' notes. |
| |
| * `const' |
| |
| Functions marked with `const' as an MT-Safety issue non-atomically |
| modify internal objects that are better regarded as constant, |
| because a substantial portion of the GNU C Library accesses them |
| without synchronization. Unlike `race', that causes both readers |
| and writers of internal objects to be regarded as MT-Unsafe and |
| AS-Unsafe, this mark is applied to writers only. Writers remain |
| equally MT- and AS-Unsafe to call, but the then-mandatory |
| constness of objects they modify enables readers to be regarded as |
| MT-Safe and AS-Safe (as long as no other reasons for them to be |
| unsafe remain), since the lack of synchronization is not a problem |
| when the objects are effectively constant. |
| |
| The identifier that follows the `const' mark will appear by itself |
| as a safety note in readers. Programs that wish to work around |
| this safety issue, so as to call writers, may use a non-recursve |
| `rwlock' associated with the identifier, and guard _all_ calls to |
| functions marked with `const' followed by the identifier with a |
| write lock, and _all_ calls to functions marked with the identifier |
| by itself with a read lock. The non-recursive locking removes the |
| MT-Safety problem, but it trades one AS-Safety problem for |
| another, so use in asynchronous signals remains undefined. |
| |
| * `sig' |
| |
| Functions marked with `sig' as a MT-Safety issue (that implies an |
| identical AS-Safety issue, omitted for brevity) may temporarily |
| install a signal handler for internal purposes, which may |
| interfere with other uses of the signal, identified after a colon. |
| |
| This safety problem can be worked around by ensuring that no other |
| uses of the signal will take place for the duration of the call. |
| Holding a non-recursive mutex while calling all functions that use |
| the same temporary signal; blocking that signal before the call |
| and resetting its handler afterwards is recommended. |
| |
| There is no safe way to guarantee the original signal handler is |
| restored in case of asynchronous cancellation, therefore so-marked |
| functions are also AC-Unsafe. |
| |
| Besides the measures recommended to work around the MT- and |
| AS-Safety problem, in order to avert the cancellation problem, |
| disabling asynchronous cancellation _and_ installing a cleanup |
| handler to restore the signal to the desired state and to release |
| the mutex are recommended. |
| |
| * `term' |
| |
| Functions marked with `term' as an MT-Safety issue may change the |
| terminal settings in the recommended way, namely: call `tcgetattr', |
| modify some flags, and then call `tcsetattr'; this creates a window |
| in which changes made by other threads are lost. Thus, functions |
| marked with `term' are MT-Unsafe. The same window enables changes |
| made by asynchronous signals to be lost. These functions are also |
| AS-Unsafe, but the corresponding mark is omitted as redundant. |
| |
| It is thus advisable for applications using the terminal to avoid |
| concurrent and reentrant interactions with it, by not using it in |
| signal handlers or blocking signals that might use it, and holding |
| a lock while calling these functions and interacting with the |
| terminal. This lock should also be used for mutual exclusion with |
| functions marked with `race:tcattr(fd)', where FD is a file |
| descriptor for the controlling terminal. The caller may use a |
| single mutex for simplicity, or use one mutex per terminal, even |
| if referenced by different file descriptors. |
| |
| Functions marked with `term' as an AC-Safety issue are supposed to |
| restore terminal settings to their original state, after |
| temporarily changing them, but they may fail to do so if cancelled. |
| |
| Besides the measures recommended to work around the MT- and |
| AS-Safety problem, in order to avert the cancellation problem, |
| disabling asynchronous cancellation _and_ installing a cleanup |
| handler to restore the terminal settings to the original state and |
| to release the mutex are recommended. |
| |
| |
| |
| File: libc.info, Node: Other Safety Remarks, Prev: Conditionally Safe Features, Up: POSIX |
| |
| 1.2.2.4 Other Safety Remarks |
| ............................ |
| |
| Additional keywords may be attached to functions, indicating features |
| that do not make a function unsafe to call, but that may need to be |
| taken into account in certain classes of programs: |
| |
| * `locale' |
| |
| Functions annotated with `locale' as an MT-Safety issue read from |
| the locale object without any form of synchronization. Functions |
| annotated with `locale' called concurrently with locale changes may |
| behave in ways that do not correspond to any of the locales active |
| during their execution, but an unpredictable mix thereof. |
| |
| We do not mark these functions as MT- or AS-Unsafe, however, |
| because functions that modify the locale object are marked with |
| `const:locale' and regarded as unsafe. Being unsafe, the latter |
| are not to be called when multiple threads are running or |
| asynchronous signals are enabled, and so the locale can be |
| considered effectively constant in these contexts, which makes the |
| former safe. |
| |
| * `env' |
| |
| Functions marked with `env' as an MT-Safety issue access the |
| environment with `getenv' or similar, without any guards to ensure |
| safety in the presence of concurrent modifications. |
| |
| We do not mark these functions as MT- or AS-Unsafe, however, |
| because functions that modify the environment are all marked with |
| `const:env' and regarded as unsafe. Being unsafe, the latter are |
| not to be called when multiple threads are running or asynchronous |
| signals are enabled, and so the environment can be considered |
| effectively constant in these contexts, which makes the former |
| safe. |
| |
| * `hostid' |
| |
| The function marked with `hostid' as an MT-Safety issue reads from |
| the system-wide data structures that hold the "host ID" of the |
| machine. These data structures cannot generally be modified |
| atomically. Since it is expected that the "host ID" will not |
| normally change, the function that reads from it (`gethostid') is |
| regarded as safe, whereas the function that modifies it |
| (`sethostid') is marked with `const:hostid', indicating it may |
| require special care if it is to be called. In this specific |
| case, the special care amounts to system-wide (not merely |
| intra-process) coordination. |
| |
| * `sigintr' |
| |
| Functions marked with `sigintr' as an MT-Safety issue access the |
| `_sigintr' internal data structure without any guards to ensure |
| safety in the presence of concurrent modifications. |
| |
| We do not mark these functions as MT- or AS-Unsafe, however, |
| because functions that modify the this data structure are all |
| marked with `const:sigintr' and regarded as unsafe. Being unsafe, |
| the latter are not to be called when multiple threads are running |
| or asynchronous signals are enabled, and so the data structure can |
| be considered effectively constant in these contexts, which makes |
| the former safe. |
| |
| * `fd' |
| |
| Functions annotated with `fd' as an AC-Safety issue may leak file |
| descriptors if asynchronous thread cancellation interrupts their |
| execution. |
| |
| Functions that allocate or deallocate file descriptors will |
| generally be marked as such. Even if they attempted to protect |
| the file descriptor allocation and deallocation with cleanup |
| regions, allocating a new descriptor and storing its number where |
| the cleanup region could release it cannot be performed as a |
| single atomic operation. Similarly, releasing the descriptor and |
| taking it out of the data structure normally responsible for |
| releasing it cannot be performed atomically. There will always be |
| a window in which the descriptor cannot be released because it was |
| not stored in the cleanup handler argument yet, or it was already |
| taken out before releasing it. It cannot be taken out after |
| release: an open descriptor could mean either that the descriptor |
| still has to be closed, or that it already did so but the |
| descriptor was reallocated by another thread or signal handler. |
| |
| Such leaks could be internally avoided, with some performance |
| penalty, by temporarily disabling asynchronous thread |
| cancellation. However, since callers of allocation or |
| deallocation functions would have to do this themselves, to avoid |
| the same sort of leak in their own layer, it makes more sense for |
| the library to assume they are taking care of it than to impose a |
| performance penalty that is redundant when the problem is solved |
| in upper layers, and insufficient when it is not. |
| |
| This remark by itself does not cause a function to be regarded as |
| AC-Unsafe. However, cumulative effects of such leaks may pose a |
| problem for some programs. If this is the case, suspending |
| asynchronous cancellation for the duration of calls to such |
| functions is recommended. |
| |
| * `mem' |
| |
| Functions annotated with `mem' as an AC-Safety issue may leak |
| memory if asynchronous thread cancellation interrupts their |
| execution. |
| |
| The problem is similar to that of file descriptors: there is no |
| atomic interface to allocate memory and store its address in the |
| argument to a cleanup handler, or to release it and remove its |
| address from that argument, without at least temporarily disabling |
| asynchronous cancellation, which these functions do not do. |
| |
| This remark does not by itself cause a function to be regarded as |
| generally AC-Unsafe. However, cumulative effects of such leaks |
| may be severe enough for some programs that disabling asynchronous |
| cancellation for the duration of calls to such functions may be |
| required. |
| |
| * `cwd' |
| |
| Functions marked with `cwd' as an MT-Safety issue may temporarily |
| change the current working directory during their execution, which |
| may cause relative pathnames to be resolved in unexpected ways in |
| other threads or within asynchronous signal or cancellation |
| handlers. |
| |
| This is not enough of a reason to mark so-marked functions as MT- |
| or AS-Unsafe, but when this behavior is optional (e.g., `nftw' with |
| `FTW_CHDIR'), avoiding the option may be a good alternative to |
| using full pathnames or file descriptor-relative (e.g. `openat') |
| system calls. |
| |
| * `!posix' |
| |
| This remark, as an MT-, AS- or AC-Safety note to a function, |
| indicates the safety status of the function is known to differ |
| from the specified status in the POSIX standard. For example, |
| POSIX does not require a function to be Safe, but our |
| implementation is, or vice-versa. |
| |
| For the time being, the absence of this remark does not imply the |
| safety properties we documented are identical to those mandated by |
| POSIX for the corresponding functions. |
| |
| * `:identifier' |
| |
| Annotations may sometimes be followed by identifiers, intended to |
| group several functions that e.g. access the data structures in an |
| unsafe way, as in `race' and `const', or to provide more specific |
| information, such as naming a signal in a function marked with |
| `sig'. It is envisioned that it may be applied to `lock' and |
| `corrupt' as well in the future. |
| |
| In most cases, the identifier will name a set of functions, but it |
| may name global objects or function arguments, or identifiable |
| properties or logical components associated with them, with a |
| notation such as e.g. `:buf(arg)' to denote a buffer associated |
| with the argument ARG, or `:tcattr(fd)' to denote the terminal |
| attributes of a file descriptor FD. |
| |
| The most common use for identifiers is to provide logical groups of |
| functions and arguments that need to be protected by the same |
| synchronization primitive in order to ensure safe operation in a |
| given context. |
| |
| * `/condition' |
| |
| Some safety annotations may be conditional, in that they only |
| apply if a boolean expression involving arguments, global |
| variables or even the underlying kernel evaluates evaluates to |
| true. Such conditions as `/hurd' or `/!linux!bsd' indicate the |
| preceding marker only applies when the underlying kernel is the |
| HURD, or when it is neither Linux nor a BSD kernel, respectively. |
| `/!ps' and `/one_per_line' indicate the preceding marker only |
| applies when argument PS is NULL, or global variable ONE_PER_LINE |
| is nonzero. |
| |
| When all marks that render a function unsafe are adorned with such |
| conditions, and none of the named conditions hold, then the |
| function can be regarded as safe. |
| |
| |
| |
| File: libc.info, Node: Berkeley Unix, Next: SVID, Prev: POSIX, Up: Standards and Portability |
| |
| 1.2.3 Berkeley Unix |
| ------------------- |
| |
| The GNU C Library defines facilities from some versions of Unix which |
| are not formally standardized, specifically from the 4.2 BSD, 4.3 BSD, |
| and 4.4 BSD Unix systems (also known as "Berkeley Unix") and from |
| "SunOS" (a popular 4.2 BSD derivative that includes some Unix System V |
| functionality). These systems support most of the ISO C and POSIX |
| facilities, and 4.4 BSD and newer releases of SunOS in fact support |
| them all. |
| |
| The BSD facilities include symbolic links (*note Symbolic Links::), |
| the `select' function (*note Waiting for I/O::), the BSD signal |
| functions (*note BSD Signal Handling::), and sockets (*note Sockets::). |
| |
| |
| File: libc.info, Node: SVID, Next: XPG, Prev: Berkeley Unix, Up: Standards and Portability |
| |
| 1.2.4 SVID (The System V Interface Description) |
| ----------------------------------------------- |
| |
| The "System V Interface Description" (SVID) is a document describing |
| the AT&T Unix System V operating system. It is to some extent a |
| superset of the POSIX standard (*note POSIX::). |
| |
| The GNU C Library defines most of the facilities required by the SVID |
| that are not also required by the ISO C or POSIX standards, for |
| compatibility with System V Unix and other Unix systems (such as |
| SunOS) which include these facilities. However, many of the more |
| obscure and less generally useful facilities required by the SVID are |
| not included. (In fact, Unix System V itself does not provide them |
| all.) |
| |
| The supported facilities from System V include the methods for |
| inter-process communication and shared memory, the `hsearch' and |
| `drand48' families of functions, `fmtmsg' and several of the |
| mathematical functions. |
| |
| |
| File: libc.info, Node: XPG, Prev: SVID, Up: Standards and Portability |
| |
| 1.2.5 XPG (The X/Open Portability Guide) |
| ---------------------------------------- |
| |
| The X/Open Portability Guide, published by the X/Open Company, Ltd., is |
| a more general standard than POSIX. X/Open owns the Unix copyright and |
| the XPG specifies the requirements for systems which are intended to be |
| a Unix system. |
| |
| The GNU C Library complies to the X/Open Portability Guide, Issue |
| 4.2, with all extensions common to XSI (X/Open System Interface) |
| compliant systems and also all X/Open UNIX extensions. |
| |
| The additions on top of POSIX are mainly derived from functionality |
| available in System V and BSD systems. Some of the really bad mistakes |
| in System V systems were corrected, though. Since fulfilling the XPG |
| standard with the Unix extensions is a precondition for getting the |
| Unix brand chances are good that the functionality is available on |
| commercial systems. |
| |
| |
| File: libc.info, Node: Using the Library, Next: Roadmap to the Manual, Prev: Standards and Portability, Up: Introduction |
| |
| 1.3 Using the Library |
| ===================== |
| |
| This section describes some of the practical issues involved in using |
| the GNU C Library. |
| |
| * Menu: |
| |
| * Header Files:: How to include the header files in your |
| programs. |
| * Macro Definitions:: Some functions in the library may really |
| be implemented as macros. |
| * Reserved Names:: The C standard reserves some names for |
| the library, and some for users. |
| * Feature Test Macros:: How to control what names are defined. |
| |
| |
| File: libc.info, Node: Header Files, Next: Macro Definitions, Up: Using the Library |
| |
| 1.3.1 Header Files |
| ------------------ |
| |
| Libraries for use by C programs really consist of two parts: "header |
| files" that define types and macros and declare variables and |
| functions; and the actual library or "archive" that contains the |
| definitions of the variables and functions. |
| |
| (Recall that in C, a "declaration" merely provides information that |
| a function or variable exists and gives its type. For a function |
| declaration, information about the types of its arguments might be |
| provided as well. The purpose of declarations is to allow the compiler |
| to correctly process references to the declared variables and functions. |
| A "definition", on the other hand, actually allocates storage for a |
| variable or says what a function does.) |
| |
| In order to use the facilities in the GNU C Library, you should be |
| sure that your program source files include the appropriate header |
| files. This is so that the compiler has declarations of these |
| facilities available and can correctly process references to them. |
| Once your program has been compiled, the linker resolves these |
| references to the actual definitions provided in the archive file. |
| |
| Header files are included into a program source file by the |
| `#include' preprocessor directive. The C language supports two forms |
| of this directive; the first, |
| |
| #include "HEADER" |
| |
| is typically used to include a header file HEADER that you write |
| yourself; this would contain definitions and declarations describing the |
| interfaces between the different parts of your particular application. |
| By contrast, |
| |
| #include <file.h> |
| |
| is typically used to include a header file `file.h' that contains |
| definitions and declarations for a standard library. This file would |
| normally be installed in a standard place by your system administrator. |
| You should use this second form for the C library header files. |
| |
| Typically, `#include' directives are placed at the top of the C |
| source file, before any other code. If you begin your source files with |
| some comments explaining what the code in the file does (a good idea), |
| put the `#include' directives immediately afterwards, following the |
| feature test macro definition (*note Feature Test Macros::). |
| |
| For more information about the use of header files and `#include' |
| directives, *note Header Files: (cpp.info)Header Files. |
| |
| The GNU C Library provides several header files, each of which |
| contains the type and macro definitions and variable and function |
| declarations for a group of related facilities. This means that your |
| programs may need to include several header files, depending on exactly |
| which facilities you are using. |
| |
| Some library header files include other library header files |
| automatically. However, as a matter of programming style, you should |
| not rely on this; it is better to explicitly include all the header |
| files required for the library facilities you are using. The GNU C |
| Library header files have been written in such a way that it doesn't |
| matter if a header file is accidentally included more than once; |
| including a header file a second time has no effect. Likewise, if your |
| program needs to include multiple header files, the order in which they |
| are included doesn't matter. |
| |
| *Compatibility Note:* Inclusion of standard header files in any |
| order and any number of times works in any ISO C implementation. |
| However, this has traditionally not been the case in many older C |
| implementations. |
| |
| Strictly speaking, you don't _have to_ include a header file to use |
| a function it declares; you could declare the function explicitly |
| yourself, according to the specifications in this manual. But it is |
| usually better to include the header file because it may define types |
| and macros that are not otherwise available and because it may define |
| more efficient macro replacements for some functions. It is also a sure |
| way to have the correct declaration. |
| |
| |
| File: libc.info, Node: Macro Definitions, Next: Reserved Names, Prev: Header Files, Up: Using the Library |
| |
| 1.3.2 Macro Definitions of Functions |
| ------------------------------------ |
| |
| If we describe something as a function in this manual, it may have a |
| macro definition as well. This normally has no effect on how your |
| program runs--the macro definition does the same thing as the function |
| would. In particular, macro equivalents for library functions evaluate |
| arguments exactly once, in the same way that a function call would. The |
| main reason for these macro definitions is that sometimes they can |
| produce an inline expansion that is considerably faster than an actual |
| function call. |
| |
| Taking the address of a library function works even if it is also |
| defined as a macro. This is because, in this context, the name of the |
| function isn't followed by the left parenthesis that is syntactically |
| necessary to recognize a macro call. |
| |
| You might occasionally want to avoid using the macro definition of a |
| function--perhaps to make your program easier to debug. There are two |
| ways you can do this: |
| |
| * You can avoid a macro definition in a specific use by enclosing |
| the name of the function in parentheses. This works because the |
| name of the function doesn't appear in a syntactic context where |
| it is recognizable as a macro call. |
| |
| * You can suppress any macro definition for a whole source file by |
| using the `#undef' preprocessor directive, unless otherwise stated |
| explicitly in the description of that facility. |
| |
| For example, suppose the header file `stdlib.h' declares a function |
| named `abs' with |
| |
| extern int abs (int); |
| |
| and also provides a macro definition for `abs'. Then, in: |
| |
| #include <stdlib.h> |
| int f (int *i) { return abs (++*i); } |
| |
| the reference to `abs' might refer to either a macro or a function. On |
| the other hand, in each of the following examples the reference is to a |
| function and not a macro. |
| |
| #include <stdlib.h> |
| int g (int *i) { return (abs) (++*i); } |
| |
| #undef abs |
| int h (int *i) { return abs (++*i); } |
| |
| Since macro definitions that double for a function behave in exactly |
| the same way as the actual function version, there is usually no need |
| for any of these methods. In fact, removing macro definitions usually |
| just makes your program slower. |
| |
| |
| File: libc.info, Node: Reserved Names, Next: Feature Test Macros, Prev: Macro Definitions, Up: Using the Library |
| |
| 1.3.3 Reserved Names |
| -------------------- |
| |
| The names of all library types, macros, variables and functions that |
| come from the ISO C standard are reserved unconditionally; your program |
| *may not* redefine these names. All other library names are reserved |
| if your program explicitly includes the header file that defines or |
| declares them. There are several reasons for these restrictions: |
| |
| * Other people reading your code could get very confused if you were |
| using a function named `exit' to do something completely different |
| from what the standard `exit' function does, for example. |
| Preventing this situation helps to make your programs easier to |
| understand and contributes to modularity and maintainability. |
| |
| * It avoids the possibility of a user accidentally redefining a |
| library function that is called by other library functions. If |
| redefinition were allowed, those other functions would not work |
| properly. |
| |
| * It allows the compiler to do whatever special optimizations it |
| pleases on calls to these functions, without the possibility that |
| they may have been redefined by the user. Some library |
| facilities, such as those for dealing with variadic arguments |
| (*note Variadic Functions::) and non-local exits (*note Non-Local |
| Exits::), actually require a considerable amount of cooperation on |
| the part of the C compiler, and with respect to the |
| implementation, it might be easier for the compiler to treat these |
| as built-in parts of the language. |
| |
| In addition to the names documented in this manual, reserved names |
| include all external identifiers (global functions and variables) that |
| begin with an underscore (`_') and all identifiers regardless of use |
| that begin with either two underscores or an underscore followed by a |
| capital letter are reserved names. This is so that the library and |
| header files can define functions, variables, and macros for internal |
| purposes without risk of conflict with names in user programs. |
| |
| Some additional classes of identifier names are reserved for future |
| extensions to the C language or the POSIX.1 environment. While using |
| these names for your own purposes right now might not cause a problem, |
| they do raise the possibility of conflict with future versions of the C |
| or POSIX standards, so you should avoid these names. |
| |
| * Names beginning with a capital `E' followed a digit or uppercase |
| letter may be used for additional error code names. *Note Error |
| Reporting::. |
| |
| * Names that begin with either `is' or `to' followed by a lowercase |
| letter may be used for additional character testing and conversion |
| functions. *Note Character Handling::. |
| |
| * Names that begin with `LC_' followed by an uppercase letter may be |
| used for additional macros specifying locale attributes. *Note |
| Locales::. |
| |
| * Names of all existing mathematics functions (*note Mathematics::) |
| suffixed with `f' or `l' are reserved for corresponding functions |
| that operate on `float' and `long double' arguments, respectively. |
| |
| * Names that begin with `SIG' followed by an uppercase letter are |
| reserved for additional signal names. *Note Standard Signals::. |
| |
| * Names that begin with `SIG_' followed by an uppercase letter are |
| reserved for additional signal actions. *Note Basic Signal |
| Handling::. |
| |
| * Names beginning with `str', `mem', or `wcs' followed by a |
| lowercase letter are reserved for additional string and array |
| functions. *Note String and Array Utilities::. |
| |
| * Names that end with `_t' are reserved for additional type names. |
| |
| In addition, some individual header files reserve names beyond those |
| that they actually define. You only need to worry about these |
| restrictions if your program includes that particular header file. |
| |
| * The header file `dirent.h' reserves names prefixed with `d_'. |
| |
| * The header file `fcntl.h' reserves names prefixed with `l_', `F_', |
| `O_', and `S_'. |
| |
| * The header file `grp.h' reserves names prefixed with `gr_'. |
| |
| * The header file `limits.h' reserves names suffixed with `_MAX'. |
| |
| * The header file `pwd.h' reserves names prefixed with `pw_'. |
| |
| * The header file `signal.h' reserves names prefixed with `sa_' and |
| `SA_'. |
| |
| * The header file `sys/stat.h' reserves names prefixed with `st_' |
| and `S_'. |
| |
| * The header file `sys/times.h' reserves names prefixed with `tms_'. |
| |
| * The header file `termios.h' reserves names prefixed with `c_', |
| `V', `I', `O', and `TC'; and names prefixed with `B' followed by a |
| digit. |
| |
| |
| File: libc.info, Node: Feature Test Macros, Prev: Reserved Names, Up: Using the Library |
| |
| 1.3.4 Feature Test Macros |
| ------------------------- |
| |
| The exact set of features available when you compile a source file is |
| controlled by which "feature test macros" you define. |
| |
| If you compile your programs using `gcc -ansi', you get only the |
| ISO C library features, unless you explicitly request additional |
| features by defining one or more of the feature macros. *Note GNU CC |
| Command Options: (gcc.info)Invoking GCC, for more information about GCC |
| options. |
| |
| You should define these macros by using `#define' preprocessor |
| directives at the top of your source code files. These directives |
| _must_ come before any `#include' of a system header file. It is best |
| to make them the very first thing in the file, preceded only by |
| comments. You could also use the `-D' option to GCC, but it's better |
| if you make the source files indicate their own meaning in a |
| self-contained way. |
| |
| This system exists to allow the library to conform to multiple |
| standards. Although the different standards are often described as |
| supersets of each other, they are usually incompatible because larger |
| standards require functions with names that smaller ones reserve to the |
| user program. This is not mere pedantry -- it has been a problem in |
| practice. For instance, some non-GNU programs define functions named |
| `getline' that have nothing to do with this library's `getline'. They |
| would not be compilable if all features were enabled indiscriminately. |
| |
| This should not be used to verify that a program conforms to a |
| limited standard. It is insufficient for this purpose, as it will not |
| protect you from including header files outside the standard, or |
| relying on semantics undefined within the standard. |
| |
| -- Macro: _POSIX_SOURCE |
| If you define this macro, then the functionality from the POSIX.1 |
| standard (IEEE Standard 1003.1) is available, as well as all of the |
| ISO C facilities. |
| |
| The state of `_POSIX_SOURCE' is irrelevant if you define the macro |
| `_POSIX_C_SOURCE' to a positive integer. |
| |
| -- Macro: _POSIX_C_SOURCE |
| Define this macro to a positive integer to control which POSIX |
| functionality is made available. The greater the value of this |
| macro, the more functionality is made available. |
| |
| If you define this macro to a value greater than or equal to `1', |
| then the functionality from the 1990 edition of the POSIX.1 |
| standard (IEEE Standard 1003.1-1990) is made available. |
| |
| If you define this macro to a value greater than or equal to `2', |
| then the functionality from the 1992 edition of the POSIX.2 |
| standard (IEEE Standard 1003.2-1992) is made available. |
| |
| If you define this macro to a value greater than or equal to |
| `199309L', then the functionality from the 1993 edition of the |
| POSIX.1b standard (IEEE Standard 1003.1b-1993) is made available. |
| |
| Greater values for `_POSIX_C_SOURCE' will enable future extensions. |
| The POSIX standards process will define these values as necessary, |
| and the GNU C Library should support them some time after they |
| become standardized. The 1996 edition of POSIX.1 (ISO/IEC 9945-1: |
| 1996) states that if you define `_POSIX_C_SOURCE' to a value |
| greater than or equal to `199506L', then the functionality from |
| the 1996 edition is made available. |
| |
| -- Macro: _BSD_SOURCE |
| If you define this macro, functionality derived from 4.3 BSD Unix |
| is included as well as the ISO C, POSIX.1, and POSIX.2 material. |
| |
| -- Macro: _SVID_SOURCE |
| If you define this macro, functionality derived from SVID is |
| included as well as the ISO C, POSIX.1, POSIX.2, and X/Open |
| material. |
| |
| -- Macro: _XOPEN_SOURCE |
| -- Macro: _XOPEN_SOURCE_EXTENDED |
| If you define this macro, functionality described in the X/Open |
| Portability Guide is included. This is a superset of the POSIX.1 |
| and POSIX.2 functionality and in fact `_POSIX_SOURCE' and |
| `_POSIX_C_SOURCE' are automatically defined. |
| |
| As the unification of all Unices, functionality only available in |
| BSD and SVID is also included. |
| |
| If the macro `_XOPEN_SOURCE_EXTENDED' is also defined, even more |
| functionality is available. The extra functions will make all |
| functions available which are necessary for the X/Open Unix brand. |
| |
| If the macro `_XOPEN_SOURCE' has the value 500 this includes all |
| functionality described so far plus some new definitions from the |
| Single Unix Specification, version 2. |
| |
| -- Macro: _LARGEFILE_SOURCE |
| If this macro is defined some extra functions are available which |
| rectify a few shortcomings in all previous standards. |
| Specifically, the functions `fseeko' and `ftello' are available. |
| Without these functions the difference between the ISO C interface |
| (`fseek', `ftell') and the low-level POSIX interface (`lseek') |
| would lead to problems. |
| |
| This macro was introduced as part of the Large File Support |
| extension (LFS). |
| |
| -- Macro: _LARGEFILE64_SOURCE |
| If you define this macro an additional set of functions is made |
| available which enables 32 bit systems to use files of sizes beyond |
| the usual limit of 2GB. This interface is not available if the |
| system does not support files that large. On systems where the |
| natural file size limit is greater than 2GB (i.e., on 64 bit |
| systems) the new functions are identical to the replaced functions. |
| |
| The new functionality is made available by a new set of types and |
| functions which replace the existing ones. The names of these new |
| objects contain `64' to indicate the intention, e.g., `off_t' vs. |
| `off64_t' and `fseeko' vs. `fseeko64'. |
| |
| This macro was introduced as part of the Large File Support |
| extension (LFS). It is a transition interface for the period when |
| 64 bit offsets are not generally used (see `_FILE_OFFSET_BITS'). |
| |
| -- Macro: _FILE_OFFSET_BITS |
| This macro determines which file system interface shall be used, |
| one replacing the other. Whereas `_LARGEFILE64_SOURCE' makes the |
| 64 bit interface available as an additional interface, |
| `_FILE_OFFSET_BITS' allows the 64 bit interface to replace the old |
| interface. |
| |
| If `_FILE_OFFSET_BITS' is undefined, or if it is defined to the |
| value `32', nothing changes. The 32 bit interface is used and |
| types like `off_t' have a size of 32 bits on 32 bit systems. |
| |
| If the macro is defined to the value `64', the large file interface |
| replaces the old interface. I.e., the functions are not made |
| available under different names (as they are with |
| `_LARGEFILE64_SOURCE'). Instead the old function names now |
| reference the new functions, e.g., a call to `fseeko' now indeed |
| calls `fseeko64'. |
| |
| This macro should only be selected if the system provides |
| mechanisms for handling large files. On 64 bit systems this macro |
| has no effect since the `*64' functions are identical to the |
| normal functions. |
| |
| This macro was introduced as part of the Large File Support |
| extension (LFS). |
| |
| -- Macro: _ISOC99_SOURCE |
| Until the revised ISO C standard is widely adopted the new features |
| are not automatically enabled. The GNU C Library nevertheless has |
| a complete implementation of the new standard and to enable the |
| new features the macro `_ISOC99_SOURCE' should be defined. |
| |
| -- Macro: _GNU_SOURCE |
| If you define this macro, everything is included: ISO C89, |
| ISO C99, POSIX.1, POSIX.2, BSD, SVID, X/Open, LFS, and GNU |
| extensions. In the cases where POSIX.1 conflicts with BSD, the |
| POSIX definitions take precedence. |
| |
| -- Macro: _DEFAULT_SOURCE |
| If you define this macro, most features are included apart from |
| X/Open, LFS and GNU extensions; the effect is similar to defining |
| `_POSIX_C_SOURCE' to `200809L' and `_POSIX_SOURCE', |
| `_SVID_SOURCE', and `_BSD_SOURCE' to 1. Defining this macro, on |
| its own and without using compiler options such as `-ansi' or |
| `-std=c99', has the same effect as not defining any feature test |
| macros; defining it together with other feature test macros, or |
| when options such as `-ansi' are used, enables those features even |
| when the other options would otherwise cause them to be disabled. |
| |
| -- Macro: _REENTRANT |
| -- Macro: _THREAD_SAFE |
| If you define one of these macros, reentrant versions of several |
| functions get declared. Some of the functions are specified in |
| POSIX.1c but many others are only available on a few other systems |
| or are unique to the GNU C Library. The problem is the delay in |
| the standardization of the thread safe C library interface. |
| |
| Unlike on some other systems, no special version of the C library |
| must be used for linking. There is only one version but while |
| compiling this it must have been specified to compile as thread |
| safe. |
| |
| We recommend you use `_GNU_SOURCE' in new programs. If you don't |
| specify the `-ansi' option to GCC, or other conformance options such as |
| `-std=c99', and don't define any of these macros explicitly, the effect |
| is the same as defining `_DEFAULT_SOURCE' to 1. |
| |
| When you define a feature test macro to request a larger class of |
| features, it is harmless to define in addition a feature test macro for |
| a subset of those features. For example, if you define |
| `_POSIX_C_SOURCE', then defining `_POSIX_SOURCE' as well has no effect. |
| Likewise, if you define `_GNU_SOURCE', then defining either |
| `_POSIX_SOURCE' or `_POSIX_C_SOURCE' or `_SVID_SOURCE' as well has no |
| effect. |
| |
| |
| File: libc.info, Node: Roadmap to the Manual, Prev: Using the Library, Up: Introduction |
| |
| 1.4 Roadmap to the Manual |
| ========================= |
| |
| Here is an overview of the contents of the remaining chapters of this |
| manual. |
| |
| * *note Error Reporting::, describes how errors detected by the |
| library are reported. |
| |
| * *note Language Features::, contains information about library |
| support for standard parts of the C language, including things |
| like the `sizeof' operator and the symbolic constant `NULL', how |
| to write functions accepting variable numbers of arguments, and |
| constants describing the ranges and other properties of the |
| numerical types. There is also a simple debugging mechanism which |
| allows you to put assertions in your code, and have diagnostic |
| messages printed if the tests fail. |
| |
| * *note Memory::, describes the GNU C Library's facilities for |
| managing and using virtual and real memory, including dynamic |
| allocation of virtual memory. If you do not know in advance how |
| much memory your program needs, you can allocate it dynamically |
| instead, and manipulate it via pointers. |
| |
| * *note Character Handling::, contains information about character |
| classification functions (such as `isspace') and functions for |
| performing case conversion. |
| |
| * *note String and Array Utilities::, has descriptions of functions |
| for manipulating strings (null-terminated character arrays) and |
| general byte arrays, including operations such as copying and |
| comparison. |
| |
| * *note I/O Overview::, gives an overall look at the input and output |
| facilities in the library, and contains information about basic |
| concepts such as file names. |
| |
| * *note I/O on Streams::, describes I/O operations involving streams |
| (or `FILE *' objects). These are the normal C library functions |
| from `stdio.h'. |
| |
| * *note Low-Level I/O::, contains information about I/O operations |
| on file descriptors. File descriptors are a lower-level mechanism |
| specific to the Unix family of operating systems. |
| |
| * *note File System Interface::, has descriptions of operations on |
| entire files, such as functions for deleting and renaming them and |
| for creating new directories. This chapter also contains |
| information about how you can access the attributes of a file, |
| such as its owner and file protection modes. |
| |
| * *note Pipes and FIFOs::, contains information about simple |
| interprocess communication mechanisms. Pipes allow communication |
| between two related processes (such as between a parent and |
| child), while FIFOs allow communication between processes sharing |
| a common file system on the same machine. |
| |
| * *note Sockets::, describes a more complicated interprocess |
| communication mechanism that allows processes running on different |
| machines to communicate over a network. This chapter also |
| contains information about Internet host addressing and how to use |
| the system network databases. |
| |
| * *note Low-Level Terminal Interface::, describes how you can change |
| the attributes of a terminal device. If you want to disable echo |
| of characters typed by the user, for example, read this chapter. |
| |
| * *note Mathematics::, contains information about the math library |
| functions. These include things like random-number generators and |
| remainder functions on integers as well as the usual trigonometric |
| and exponential functions on floating-point numbers. |
| |
| * *note Low-Level Arithmetic Functions: Arithmetic, describes |
| functions for simple arithmetic, analysis of floating-point |
| values, and reading numbers from strings. |
| |
| * *note Searching and Sorting::, contains information about functions |
| for searching and sorting arrays. You can use these functions on |
| any kind of array by providing an appropriate comparison function. |
| |
| * *note Pattern Matching::, presents functions for matching regular |
| expressions and shell file name patterns, and for expanding words |
| as the shell does. |
| |
| * *note Date and Time::, describes functions for measuring both |
| calendar time and CPU time, as well as functions for setting |
| alarms and timers. |
| |
| * *note Character Set Handling::, contains information about |
| manipulating characters and strings using character sets larger |
| than will fit in the usual `char' data type. |
| |
| * *note Locales::, describes how selecting a particular country or |
| language affects the behavior of the library. For example, the |
| locale affects collation sequences for strings and how monetary |
| values are formatted. |
| |
| * *note Non-Local Exits::, contains descriptions of the `setjmp' and |
| `longjmp' functions. These functions provide a facility for |
| `goto'-like jumps which can jump from one function to another. |
| |
| * *note Signal Handling::, tells you all about signals--what they |
| are, how to establish a handler that is called when a particular |
| kind of signal is delivered, and how to prevent signals from |
| arriving during critical sections of your program. |
| |
| * *note Program Basics::, tells how your programs can access their |
| command-line arguments and environment variables. |
| |
| * *note Processes::, contains information about how to start new |
| processes and run programs. |
| |
| * *note Job Control::, describes functions for manipulating process |
| groups and the controlling terminal. This material is probably |
| only of interest if you are writing a shell or other program which |
| handles job control specially. |
| |
| * *note Name Service Switch::, describes the services which are |
| available for looking up names in the system databases, how to |
| determine which service is used for which database, and how these |
| services are implemented so that contributors can design their own |
| services. |
| |
| * *note User Database::, and *note Group Database::, tell you how to |
| access the system user and group databases. |
| |
| * *note System Management::, describes functions for controlling and |
| getting information about the hardware and software configuration |
| your program is executing under. |
| |
| * *note System Configuration::, tells you how you can get |
| information about various operating system limits. Most of these |
| parameters are provided for compatibility with POSIX. |
| |
| * *note Library Summary::, gives a summary of all the functions, |
| variables, and macros in the library, with complete data types and |
| function prototypes, and says what standard or system each is |
| derived from. |
| |
| * *note Installation::, explains how to build and install the GNU C |
| Library on your system, and how to report any bugs you might find. |
| |
| * *note Maintenance::, explains how to add new functions or port the |
| library to a new system. |
| |
| If you already know the name of the facility you are interested in, |
| you can look it up in *note Library Summary::. This gives you a |
| summary of its syntax and a pointer to where you can find a more |
| detailed description. This appendix is particularly useful if you just |
| want to verify the order and type of arguments to a function, for |
| example. It also tells you what standard or system each function, |
| variable, or macro is derived from. |
| |
| |
| File: libc.info, Node: Error Reporting, Next: Memory, Prev: Introduction, Up: Top |
| |
| 2 Error Reporting |
| ***************** |
| |
| Many functions in the GNU C Library detect and report error conditions, |
| and sometimes your programs need to check for these error conditions. |
| For example, when you open an input file, you should verify that the |
| file was actually opened correctly, and print an error message or take |
| other appropriate action if the call to the library function failed. |
| |
| This chapter describes how the error reporting facility works. Your |
| program should include the header file `errno.h' to use this facility. |
| |
| * Menu: |
| |
| * Checking for Errors:: How errors are reported by library functions. |
| * Error Codes:: Error code macros; all of these expand |
| into integer constant values. |
| * Error Messages:: Mapping error codes onto error messages. |
| |
| |
| File: libc.info, Node: Checking for Errors, Next: Error Codes, Up: Error Reporting |
| |
| 2.1 Checking for Errors |
| ======================= |
| |
| Most library functions return a special value to indicate that they have |
| failed. The special value is typically `-1', a null pointer, or a |
| constant such as `EOF' that is defined for that purpose. But this |
| return value tells you only that an error has occurred. To find out |
| what kind of error it was, you need to look at the error code stored in |
| the variable `errno'. This variable is declared in the header file |
| `errno.h'. |
| |
| -- Variable: volatile int errno |
| The variable `errno' contains the system error number. You can |
| change the value of `errno'. |
| |
| Since `errno' is declared `volatile', it might be changed |
| asynchronously by a signal handler; see *note Defining Handlers::. |
| However, a properly written signal handler saves and restores the |
| value of `errno', so you generally do not need to worry about this |
| possibility except when writing signal handlers. |
| |
| The initial value of `errno' at program startup is zero. Many |
| library functions are guaranteed to set it to certain nonzero |
| values when they encounter certain kinds of errors. These error |
| conditions are listed for each function. These functions do not |
| change `errno' when they succeed; thus, the value of `errno' after |
| a successful call is not necessarily zero, and you should not use |
| `errno' to determine _whether_ a call failed. The proper way to |
| do that is documented for each function. _If_ the call failed, |
| you can examine `errno'. |
| |
| Many library functions can set `errno' to a nonzero value as a |
| result of calling other library functions which might fail. You |
| should assume that any library function might alter `errno' when |
| the function returns an error. |
| |
| *Portability Note:* ISO C specifies `errno' as a "modifiable |
| lvalue" rather than as a variable, permitting it to be implemented |
| as a macro. For example, its expansion might involve a function |
| call, like `*__errno_location ()'. In fact, that is what it is on |
| GNU/Linux and GNU/Hurd systems. The GNU C Library, on each |
| system, does whatever is right for the particular system. |
| |
| There are a few library functions, like `sqrt' and `atan', that |
| return a perfectly legitimate value in case of an error, but also |
| set `errno'. For these functions, if you want to check to see |
| whether an error occurred, the recommended method is to set `errno' |
| to zero before calling the function, and then check its value |
| afterward. |
| |
| All the error codes have symbolic names; they are macros defined in |
| `errno.h'. The names start with `E' and an upper-case letter or digit; |
| you should consider names of this form to be reserved names. *Note |
| Reserved Names::. |
| |
| The error code values are all positive integers and are all distinct, |
| with one exception: `EWOULDBLOCK' and `EAGAIN' are the same. Since the |
| values are distinct, you can use them as labels in a `switch' |
| statement; just don't use both `EWOULDBLOCK' and `EAGAIN'. Your |
| program should not make any other assumptions about the specific values |
| of these symbolic constants. |
| |
| The value of `errno' doesn't necessarily have to correspond to any |
| of these macros, since some library functions might return other error |
| codes of their own for other situations. The only values that are |
| guaranteed to be meaningful for a particular library function are the |
| ones that this manual lists for that function. |
| |
| Except on GNU/Hurd systems, almost any system call can return |
| `EFAULT' if it is given an invalid pointer as an argument. Since this |
| could only happen as a result of a bug in your program, and since it |
| will not happen on GNU/Hurd systems, we have saved space by not |
| mentioning `EFAULT' in the descriptions of individual functions. |
| |
| In some Unix systems, many system calls can also return `EFAULT' if |
| given as an argument a pointer into the stack, and the kernel for some |
| obscure reason fails in its attempt to extend the stack. If this ever |
| happens, you should probably try using statically or dynamically |
| allocated memory instead of stack memory on that system. |
| |
| |
| File: libc.info, Node: Error Codes, Next: Error Messages, Prev: Checking for Errors, Up: Error Reporting |
| |
| 2.2 Error Codes |
| =============== |
| |
| The error code macros are defined in the header file `errno.h'. All of |
| them expand into integer constant values. Some of these error codes |
| can't occur on GNU systems, but they can occur using the GNU C Library |
| on other systems. |
| |
| -- Macro: int EPERM |
| Operation not permitted; only the owner of the file (or other |
| resource) or processes with special privileges can perform the |
| operation. |
| |
| -- Macro: int ENOENT |
| No such file or directory. This is a "file doesn't exist" error |
| for ordinary files that are referenced in contexts where they are |
| expected to already exist. |
| |
| -- Macro: int ESRCH |
| No process matches the specified process ID. |
| |
| -- Macro: int EINTR |
| Interrupted function call; an asynchronous signal occurred and |
| prevented completion of the call. When this happens, you should |
| try the call again. |
| |
| You can choose to have functions resume after a signal that is |
| handled, rather than failing with `EINTR'; see *note Interrupted |
| Primitives::. |
| |
| -- Macro: int EIO |
| Input/output error; usually used for physical read or write errors. |
| |
| -- Macro: int ENXIO |
| No such device or address. The system tried to use the device |
| represented by a file you specified, and it couldn't find the |
| device. This can mean that the device file was installed |
| incorrectly, or that the physical device is missing or not |
| correctly attached to the computer. |
| |
| -- Macro: int E2BIG |
| Argument list too long; used when the arguments passed to a new |
| program being executed with one of the `exec' functions (*note |
| Executing a File::) occupy too much memory space. This condition |
| never arises on GNU/Hurd systems. |
| |
| -- Macro: int ENOEXEC |
| Invalid executable file format. This condition is detected by the |
| `exec' functions; see *note Executing a File::. |
| |
| -- Macro: int EBADF |
| Bad file descriptor; for example, I/O on a descriptor that has been |
| closed or reading from a descriptor open only for writing (or vice |
| versa). |
| |
| -- Macro: int ECHILD |
| There are no child processes. This error happens on operations |
| that are supposed to manipulate child processes, when there aren't |
| any processes to manipulate. |
| |
| -- Macro: int EDEADLK |
| Deadlock avoided; allocating a system resource would have resulted |
| in a deadlock situation. The system does not guarantee that it |
| will notice all such situations. This error means you got lucky |
| and the system noticed; it might just hang. *Note File Locks::, |
| for an example. |
| |
| -- Macro: int ENOMEM |
| No memory available. The system cannot allocate more virtual |
| memory because its capacity is full. |
| |
| -- Macro: int EACCES |
| Permission denied; the file permissions do not allow the attempted |
| operation. |
| |
| -- Macro: int EFAULT |
| Bad address; an invalid pointer was detected. On GNU/Hurd |
| systems, this error never happens; you get a signal instead. |
| |
| -- Macro: int ENOTBLK |
| A file that isn't a block special file was given in a situation |
| that requires one. For example, trying to mount an ordinary file |
| as a file system in Unix gives this error. |
| |
| -- Macro: int EBUSY |
| Resource busy; a system resource that can't be shared is already |
| in use. For example, if you try to delete a file that is the root |
| of a currently mounted filesystem, you get this error. |
| |
| -- Macro: int EEXIST |
| File exists; an existing file was specified in a context where it |
| only makes sense to specify a new file. |
| |
| -- Macro: int EXDEV |
| An attempt to make an improper link across file systems was |
| detected. This happens not only when you use `link' (*note Hard |
| Links::) but also when you rename a file with `rename' (*note |
| Renaming Files::). |
| |
| -- Macro: int ENODEV |
| The wrong type of device was given to a function that expects a |
| particular sort of device. |
| |
| -- Macro: int ENOTDIR |
| A file that isn't a directory was specified when a directory is |
| required. |
| |
| -- Macro: int EISDIR |
| File is a directory; you cannot open a directory for writing, or |
| create or remove hard links to it. |
| |
| -- Macro: int EINVAL |
| Invalid argument. This is used to indicate various kinds of |
| problems with passing the wrong argument to a library function. |
| |
| -- Macro: int EMFILE |
| The current process has too many files open and can't open any |
| more. Duplicate descriptors do count toward this limit. |
| |
| In BSD and GNU, the number of open files is controlled by a |
| resource limit that can usually be increased. If you get this |
| error, you might want to increase the `RLIMIT_NOFILE' limit or |
| make it unlimited; *note Limits on Resources::. |
| |
| -- Macro: int ENFILE |
| There are too many distinct file openings in the entire system. |
| Note that any number of linked channels count as just one file |
| opening; see *note Linked Channels::. This error never occurs on |
| GNU/Hurd systems. |
| |
| -- Macro: int ENOTTY |
| Inappropriate I/O control operation, such as trying to set terminal |
| modes on an ordinary file. |
| |
| -- Macro: int ETXTBSY |
| An attempt to execute a file that is currently open for writing, or |
| write to a file that is currently being executed. Often using a |
| debugger to run a program is considered having it open for writing |
| and will cause this error. (The name stands for "text file |
| busy".) This is not an error on GNU/Hurd systems; the text is |
| copied as necessary. |
| |
| -- Macro: int EFBIG |
| File too big; the size of a file would be larger than allowed by |
| the system. |
| |
| -- Macro: int ENOSPC |
| No space left on device; write operation on a file failed because |
| the disk is full. |
| |
| -- Macro: int ESPIPE |
| Invalid seek operation (such as on a pipe). |
| |
| -- Macro: int EROFS |
| An attempt was made to modify something on a read-only file system. |
| |
| -- Macro: int EMLINK |
| Too many links; the link count of a single file would become too |
| large. `rename' can cause this error if the file being renamed |
| already has as many links as it can take (*note Renaming Files::). |
| |
| -- Macro: int EPIPE |
| Broken pipe; there is no process reading from the other end of a |
| pipe. Every library function that returns this error code also |
| generates a `SIGPIPE' signal; this signal terminates the program |
| if not handled or blocked. Thus, your program will never actually |
| see `EPIPE' unless it has handled or blocked `SIGPIPE'. |
| |
| -- Macro: int EDOM |
| Domain error; used by mathematical functions when an argument |
| value does not fall into the domain over which the function is |
| defined. |
| |
| -- Macro: int ERANGE |
| Range error; used by mathematical functions when the result value |
| is not representable because of overflow or underflow. |
| |
| -- Macro: int EAGAIN |
| Resource temporarily unavailable; the call might work if you try |
| again later. The macro `EWOULDBLOCK' is another name for `EAGAIN'; |
| they are always the same in the GNU C Library. |
| |
| This error can happen in a few different situations: |
| |
| * An operation that would block was attempted on an object that |
| has non-blocking mode selected. Trying the same operation |
| again will block until some external condition makes it |
| possible to read, write, or connect (whatever the operation). |
| You can use `select' to find out when the operation will be |
| possible; *note Waiting for I/O::. |
| |
| *Portability Note:* In many older Unix systems, this condition |
| was indicated by `EWOULDBLOCK', which was a distinct error |
| code different from `EAGAIN'. To make your program portable, |
| you should check for both codes and treat them the same. |
| |
| * A temporary resource shortage made an operation impossible. |
| `fork' can return this error. It indicates that the shortage |
| is expected to pass, so your program can try the call again |
| later and it may succeed. It is probably a good idea to |
| delay for a few seconds before trying it again, to allow time |
| for other processes to release scarce resources. Such |
| shortages are usually fairly serious and affect the whole |
| system, so usually an interactive program should report the |
| error to the user and return to its command loop. |
| |
| -- Macro: int EWOULDBLOCK |
| In the GNU C Library, this is another name for `EAGAIN' (above). |
| The values are always the same, on every operating system. |
| |
| C libraries in many older Unix systems have `EWOULDBLOCK' as a |
| separate error code. |
| |
| -- Macro: int EINPROGRESS |
| An operation that cannot complete immediately was initiated on an |
| object that has non-blocking mode selected. Some functions that |
| must always block (such as `connect'; *note Connecting::) never |
| return `EAGAIN'. Instead, they return `EINPROGRESS' to indicate |
| that the operation has begun and will take some time. Attempts to |
| manipulate the object before the call completes return `EALREADY'. |
| You can use the `select' function to find out when the pending |
| operation has completed; *note Waiting for I/O::. |
| |
| -- Macro: int EALREADY |
| An operation is already in progress on an object that has |
| non-blocking mode selected. |
| |
| -- Macro: int ENOTSOCK |
| A file that isn't a socket was specified when a socket is required. |
| |
| -- Macro: int EMSGSIZE |
| The size of a message sent on a socket was larger than the |
| supported maximum size. |
| |
| -- Macro: int EPROTOTYPE |
| The socket type does not support the requested communications |
| protocol. |
| |
| -- Macro: int ENOPROTOOPT |
| You specified a socket option that doesn't make sense for the |
| particular protocol being used by the socket. *Note Socket |
| Options::. |
| |
| -- Macro: int EPROTONOSUPPORT |
| The socket domain does not support the requested communications |
| protocol (perhaps because the requested protocol is completely |
| invalid). *Note Creating a Socket::. |
| |
| -- Macro: int ESOCKTNOSUPPORT |
| The socket type is not supported. |
| |
| -- Macro: int EOPNOTSUPP |
| The operation you requested is not supported. Some socket |
| functions don't make sense for all types of sockets, and others |
| may not be implemented for all communications protocols. On |
| GNU/Hurd systems, this error can happen for many calls when the |
| object does not support the particular operation; it is a generic |
| indication that the server knows nothing to do for that call. |
| |
| -- Macro: int EPFNOSUPPORT |
| The socket communications protocol family you requested is not |
| supported. |
| |
| -- Macro: int EAFNOSUPPORT |
| The address family specified for a socket is not supported; it is |
| inconsistent with the protocol being used on the socket. *Note |
| Sockets::. |
| |
| -- Macro: int EADDRINUSE |
| The requested socket address is already in use. *Note Socket |
| Addresses::. |
| |
| -- Macro: int EADDRNOTAVAIL |
| The requested socket address is not available; for example, you |
| tried to give a socket a name that doesn't match the local host |
| name. *Note Socket Addresses::. |
| |
| -- Macro: int ENETDOWN |
| A socket operation failed because the network was down. |
| |
| -- Macro: int ENETUNREACH |
| A socket operation failed because the subnet containing the remote |
| host was unreachable. |
| |
| -- Macro: int ENETRESET |
| A network connection was reset because the remote host crashed. |
| |
| -- Macro: int ECONNABORTED |
| A network connection was aborted locally. |
| |
| -- Macro: int ECONNRESET |
| A network connection was closed for reasons outside the control of |
| the local host, such as by the remote machine rebooting or an |
| unrecoverable protocol violation. |
| |
| -- Macro: int ENOBUFS |
| The kernel's buffers for I/O operations are all in use. In GNU, |
| this error is always synonymous with `ENOMEM'; you may get one or |
| the other from network operations. |
| |
| -- Macro: int EISCONN |
| You tried to connect a socket that is already connected. *Note |
| Connecting::. |
| |
| -- Macro: int ENOTCONN |
| The socket is not connected to anything. You get this error when |
| you try to transmit data over a socket, without first specifying a |
| destination for the data. For a connectionless socket (for |
| datagram protocols, such as UDP), you get `EDESTADDRREQ' instead. |
| |
| -- Macro: int EDESTADDRREQ |
| No default destination address was set for the socket. You get |
| this error when you try to transmit data over a connectionless |
| socket, without first specifying a destination for the data with |
| `connect'. |
| |
| -- Macro: int ESHUTDOWN |
| The socket has already been shut down. |
| |
| -- Macro: int ETOOMANYREFS |
| ??? |
| |
| -- Macro: int ETIMEDOUT |
| A socket operation with a specified timeout received no response |
| during the timeout period. |
| |
| -- Macro: int ECONNREFUSED |
| A remote host refused to allow the network connection (typically |
| because it is not running the requested service). |
| |
| -- Macro: int ELOOP |
| Too many levels of symbolic links were encountered in looking up a |
| file name. This often indicates a cycle of symbolic links. |
| |
| -- Macro: int ENAMETOOLONG |
| Filename too long (longer than `PATH_MAX'; *note Limits for |
| Files::) or host name too long (in `gethostname' or `sethostname'; |
| *note Host Identification::). |
| |
| -- Macro: int EHOSTDOWN |
| The remote host for a requested network connection is down. |
| |
| -- Macro: int EHOSTUNREACH |
| The remote host for a requested network connection is not |
| reachable. |
| |
| -- Macro: int ENOTEMPTY |
| Directory not empty, where an empty directory was expected. |
| Typically, this error occurs when you are trying to delete a |
| directory. |
| |
| -- Macro: int EPROCLIM |
| This means that the per-user limit on new process would be |
| exceeded by an attempted `fork'. *Note Limits on Resources::, for |
| details on the `RLIMIT_NPROC' limit. |
| |
| -- Macro: int EUSERS |
| The file quota system is confused because there are too many users. |
| |
| -- Macro: int EDQUOT |
| The user's disk quota was exceeded. |
| |
| -- Macro: int ESTALE |
| Stale file handle. This indicates an internal confusion in the |
| file system which is due to file system rearrangements on the |
| server host for NFS file systems or corruption in other file |
| systems. Repairing this condition usually requires unmounting, |
| possibly repairing and remounting the file system. |
| |
| -- Macro: int EREMOTE |
| An attempt was made to NFS-mount a remote file system with a file |
| name that already specifies an NFS-mounted file. (This is an |
| error on some operating systems, but we expect it to work properly |
| on GNU/Hurd systems, making this error code impossible.) |
| |
| -- Macro: int EBADRPC |
| ??? |
| |
| -- Macro: int ERPCMISMATCH |
| ??? |
| |
| -- Macro: int EPROGUNAVAIL |
| ??? |
| |
| -- Macro: int EPROGMISMATCH |
| ??? |
| |
| -- Macro: int EPROCUNAVAIL |
| ??? |
| |
| -- Macro: int ENOLCK |
| No locks available. This is used by the file locking facilities; |
| see *note File Locks::. This error is never generated by GNU/Hurd |
| systems, but it can result from an operation to an NFS server |
| running another operating system. |
| |
| -- Macro: int EFTYPE |
| Inappropriate file type or format. The file was the wrong type |
| for the operation, or a data file had the wrong format. |
| |
| On some systems `chmod' returns this error if you try to set the |
| sticky bit on a non-directory file; *note Setting Permissions::. |
| |
| -- Macro: int EAUTH |
| ??? |
| |
| -- Macro: int ENEEDAUTH |
| ??? |
| |
| -- Macro: int ENOSYS |
| Function not implemented. This indicates that the function called |
| is not implemented at all, either in the C library itself or in the |
| operating system. When you get this error, you can be sure that |
| this particular function will always fail with `ENOSYS' unless you |
| install a new version of the C library or the operating system. |
| |
| -- Macro: int ENOTSUP |
| Not supported. A function returns this error when certain |
| parameter values are valid, but the functionality they request is |
| not available. This can mean that the function does not implement |
| a particular command or option value or flag bit at all. For |
| functions that operate on some object given in a parameter, such |
| as a file descriptor or a port, it might instead mean that only |
| _that specific object_ (file descriptor, port, etc.) is unable to |
| support the other parameters given; different file descriptors |
| might support different ranges of parameter values. |
| |
| If the entire function is not available at all in the |
| implementation, it returns `ENOSYS' instead. |
| |
| -- Macro: int EILSEQ |
| While decoding a multibyte character the function came along an |
| invalid or an incomplete sequence of bytes or the given wide |
| character is invalid. |
| |
| -- Macro: int EBACKGROUND |
| On GNU/Hurd systems, servers supporting the `term' protocol return |
| this error for certain operations when the caller is not in the |
| foreground process group of the terminal. Users do not usually |
| see this error because functions such as `read' and `write' |
| translate it into a `SIGTTIN' or `SIGTTOU' signal. *Note Job |
| Control::, for information on process groups and these signals. |
| |
| -- Macro: int EDIED |
| On GNU/Hurd systems, opening a file returns this error when the |
| file is translated by a program and the translator program dies |
| while starting up, before it has connected to the file. |
| |
| -- Macro: int ED |
| The experienced user will know what is wrong. |
| |
| -- Macro: int EGREGIOUS |
| You did *what*? |
| |
| -- Macro: int EIEIO |
| Go home and have a glass of warm, dairy-fresh milk. |
| |
| -- Macro: int EGRATUITOUS |
| This error code has no purpose. |
| |
| -- Macro: int EBADMSG |
| |
| -- Macro: int EIDRM |
| |
| -- Macro: int EMULTIHOP |
| |
| -- Macro: int ENODATA |
| |
| -- Macro: int ENOLINK |
| |
| -- Macro: int ENOMSG |
| |
| -- Macro: int ENOSR |
| |
| -- Macro: int ENOSTR |
| |
| -- Macro: int EOVERFLOW |
| |
| -- Macro: int EPROTO |
| |
| -- Macro: int ETIME |
| |
| -- Macro: int ECANCELED |
| Operation canceled; an asynchronous operation was canceled before |
| it completed. *Note Asynchronous I/O::. When you call |
| `aio_cancel', the normal result is for the operations affected to |
| complete with this error; *note Cancel AIO Operations::. |
| |
| _The following error codes are defined by the Linux/i386 kernel. |
| They are not yet documented._ |
| |
| -- Macro: int ERESTART |
| |
| -- Macro: int ECHRNG |
| |
| -- Macro: int EL2NSYNC |
| |
| -- Macro: int EL3HLT |
| |
| -- Macro: int EL3RST |
| |
| -- Macro: int ELNRNG |
| |
| -- Macro: int EUNATCH |
| |
| -- Macro: int ENOCSI |
| |
| -- Macro: int EL2HLT |
| |
| -- Macro: int EBADE |
| |
| -- Macro: int EBADR |
| |
| -- Macro: int EXFULL |
| |
| -- Macro: int ENOANO |
| |
| -- Macro: int EBADRQC |
| |
| -- Macro: int EBADSLT |
| |
| -- Macro: int EDEADLOCK |
| |
| -- Macro: int EBFONT |
| |
| -- Macro: int ENONET |
| |
| -- Macro: int ENOPKG |
| |
| -- Macro: int EADV |
| |
| -- Macro: int ESRMNT |
| |
| -- Macro: int ECOMM |
| |
| -- Macro: int EDOTDOT |
| |
| -- Macro: int ENOTUNIQ |
| |
| -- Macro: int EBADFD |
| |
| -- Macro: int EREMCHG |
| |
| -- Macro: int ELIBACC |
| |
| -- Macro: int ELIBBAD |
| |
| -- Macro: int ELIBSCN |
| |
| -- Macro: int ELIBMAX |
| |
| -- Macro: int ELIBEXEC |
| |
| -- Macro: int ESTRPIPE |
| |
| -- Macro: int EUCLEAN |
| |
| -- Macro: int ENOTNAM |
| |
| -- Macro: int ENAVAIL |
| |
| -- Macro: int EISNAM |
| |
| -- Macro: int EREMOTEIO |
| |
| -- Macro: int ENOMEDIUM |
| |
| -- Macro: int EMEDIUMTYPE |
| |
| -- Macro: int ENOKEY |
| |
| -- Macro: int EKEYEXPIRED |
| |
| -- Macro: int EKEYREVOKED |
| |
| -- Macro: int EKEYREJECTED |
| |
| -- Macro: int EOWNERDEAD |
| |
| -- Macro: int ENOTRECOVERABLE |
| |
| -- Macro: int ERFKILL |
| |
| -- Macro: int EHWPOISON |
| |
| |
| File: libc.info, Node: Error Messages, Prev: Error Codes, Up: Error Reporting |
| |
| 2.3 Error Messages |
| ================== |
| |
| The library has functions and variables designed to make it easy for |
| your program to report informative error messages in the customary |
| format about the failure of a library call. The functions `strerror' |
| and `perror' give you the standard error message for a given error |
| code; the variable `program_invocation_short_name' gives you convenient |
| access to the name of the program that encountered the error. |
| |
| -- Function: char * strerror (int ERRNUM) |
| Preliminary: | MT-Unsafe race:strerror | AS-Unsafe heap i18n | |
| AC-Unsafe mem | *Note POSIX Safety Concepts::. |
| |
| The `strerror' function maps the error code (*note Checking for |
| Errors::) specified by the ERRNUM argument to a descriptive error |
| message string. The return value is a pointer to this string. |
| |
| The value ERRNUM normally comes from the variable `errno'. |
| |
| You should not modify the string returned by `strerror'. Also, if |
| you make subsequent calls to `strerror', the string might be |
| overwritten. (But it's guaranteed that no library function ever |
| calls `strerror' behind your back.) |
| |
| The function `strerror' is declared in `string.h'. |
| |
| -- Function: char * strerror_r (int ERRNUM, char *BUF, size_t N) |
| Preliminary: | MT-Safe | AS-Unsafe i18n | AC-Unsafe | *Note POSIX |
| Safety Concepts::. |
| |
| The `strerror_r' function works like `strerror' but instead of |
| returning the error message in a statically allocated buffer |
| shared by all threads in the process, it returns a private copy |
| for the thread. This might be either some permanent global data or |
| a message string in the user supplied buffer starting at BUF with |
| the length of N bytes. |
| |
| At most N characters are written (including the NUL byte) so it is |
| up to the user to select the buffer large enough. |
| |
| This function should always be used in multi-threaded programs |
| since there is no way to guarantee the string returned by |
| `strerror' really belongs to the last call of the current thread. |
| |
| This function `strerror_r' is a GNU extension and it is declared in |
| `string.h'. |
| |
| -- Function: void perror (const char *MESSAGE) |
| Preliminary: | MT-Safe race:stderr | AS-Unsafe corrupt i18n heap |
| lock | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety |
| Concepts::. |
| |
| This function prints an error message to the stream `stderr'; see |
| *note Standard Streams::. The orientation of `stderr' is not |
| changed. |
| |
| If you call `perror' with a MESSAGE that is either a null pointer |
| or an empty string, `perror' just prints the error message |
| corresponding to `errno', adding a trailing newline. |
| |
| If you supply a non-null MESSAGE argument, then `perror' prefixes |
| its output with this string. It adds a colon and a space |
| character to separate the MESSAGE from the error string |
| corresponding to `errno'. |
| |
| The function `perror' is declared in `stdio.h'. |
| |
| `strerror' and `perror' produce the exact same message for any given |
| error code; the precise text varies from system to system. With the |
| GNU C Library, the messages are fairly short; there are no multi-line |
| messages or embedded newlines. Each error message begins with a capital |
| letter and does not include any terminating punctuation. |
| |
| *Compatibility Note:* The `strerror' function was introduced in |
| ISO C89. Many older C systems do not support this function yet. |
| |
| Many programs that don't read input from the terminal are designed to |
| exit if any system call fails. By convention, the error message from |
| such a program should start with the program's name, sans directories. |
| You can find that name in the variable `program_invocation_short_name'; |
| the full file name is stored the variable `program_invocation_name'. |
| |
| -- Variable: char * program_invocation_name |
| This variable's value is the name that was used to invoke the |
| program running in the current process. It is the same as |
| `argv[0]'. Note that this is not necessarily a useful file name; |
| often it contains no directory names. *Note Program Arguments::. |
| |
| -- Variable: char * program_invocation_short_name |
| This variable's value is the name that was used to invoke the |
| program running in the current process, with directory names |
| removed. (That is to say, it is the same as |
| `program_invocation_name' minus everything up to the last slash, |
| if any.) |
| |
| The library initialization code sets up both of these variables |
| before calling `main'. |
| |
| *Portability Note:* These two variables are GNU extensions. If you |
| want your program to work with non-GNU libraries, you must save the |
| value of `argv[0]' in `main', and then strip off the directory names |
| yourself. We added these extensions to make it possible to write |
| self-contained error-reporting subroutines that require no explicit |
| cooperation from `main'. |
| |
| Here is an example showing how to handle failure to open a file |
| correctly. The function `open_sesame' tries to open the named file for |
| reading and returns a stream if successful. The `fopen' library |
| function returns a null pointer if it couldn't open the file for some |
| reason. In that situation, `open_sesame' constructs an appropriate |
| error message using the `strerror' function, and terminates the |
| program. If we were going to make some other library calls before |
| passing the error code to `strerror', we'd have to save it in a local |
| variable instead, because those other library functions might overwrite |
| `errno' in the meantime. |
| |
| #include <errno.h> |
| #include <stdio.h> |
| #include <stdlib.h> |
| #include <string.h> |
| |
| FILE * |
| open_sesame (char *name) |
| { |
| FILE *stream; |
| |
| errno = 0; |
| stream = fopen (name, "r"); |
| if (stream == NULL) |
| { |
| fprintf (stderr, "%s: Couldn't open file %s; %s\n", |
| program_invocation_short_name, name, strerror (errno)); |
| exit (EXIT_FAILURE); |
| } |
| else |
| return stream; |
| } |
| |
| Using `perror' has the advantage that the function is portable and |
| available on all systems implementing ISO C. But often the text |
| `perror' generates is not what is wanted and there is no way to extend |
| or change what `perror' does. The GNU coding standard, for instance, |
| requires error messages to be preceded by the program name and programs |
| which read some input files should provide information about the input |
| file name and the line number in case an error is encountered while |
| reading the file. For these occasions there are two functions |
| available which are widely used throughout the GNU project. These |
| functions are declared in `error.h'. |
| |
| -- Function: void error (int STATUS, int ERRNUM, const char *FORMAT, |
| ...) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap i18n | |
| AC-Safe | *Note POSIX Safety Concepts::. |
| |
| The `error' function can be used to report general problems during |
| program execution. The FORMAT argument is a format string just |
| like those given to the `printf' family of functions. The |
| arguments required for the format can follow the FORMAT parameter. |
| Just like `perror', `error' also can report an error code in |
| textual form. But unlike `perror' the error value is explicitly |
| passed to the function in the ERRNUM parameter. This eliminates |
| the problem mentioned above that the error reporting function must |
| be called immediately after the function causing the error since |
| otherwise `errno' might have a different value. |
| |
| The `error' prints first the program name. If the application |
| defined a global variable `error_print_progname' and points it to a |
| function this function will be called to print the program name. |
| Otherwise the string from the global variable `program_name' is |
| used. The program name is followed by a colon and a space which |
| in turn is followed by the output produced by the format string. |
| If the ERRNUM parameter is non-zero the format string output is |
| followed by a colon and a space, followed by the error message for |
| the error code ERRNUM. In any case is the output terminated with |
| a newline. |
| |
| The output is directed to the `stderr' stream. If the `stderr' |
| wasn't oriented before the call it will be narrow-oriented |
| afterwards. |
| |
| The function will return unless the STATUS parameter has a |
| non-zero value. In this case the function will call `exit' with |
| the STATUS value for its parameter and therefore never return. If |
| `error' returns the global variable `error_message_count' is |
| incremented by one to keep track of the number of errors reported. |
| |
| -- Function: void error_at_line (int STATUS, int ERRNUM, const char |
| *FNAME, unsigned int LINENO, const char *FORMAT, ...) |
| Preliminary: | MT-Unsafe race:error_at_line/error_one_per_line |
| locale | AS-Unsafe corrupt heap i18n | AC-Unsafe |
| corrupt/error_one_per_line | *Note POSIX Safety Concepts::. |
| |
| The `error_at_line' function is very similar to the `error' |
| function. The only difference are the additional parameters FNAME |
| and LINENO. The handling of the other parameters is identical to |
| that of `error' except that between the program name and the string |
| generated by the format string additional text is inserted. |
| |
| Directly following the program name a colon, followed by the file |
| name pointer to by FNAME, another colon, and a value of LINENO is |
| printed. |
| |
| This additional output of course is meant to be used to locate an |
| error in an input file (like a programming language source code |
| file etc). |
| |
| If the global variable `error_one_per_line' is set to a non-zero |
| value `error_at_line' will avoid printing consecutive messages for |
| the same file and line. Repetition which are not directly |
| following each other are not caught. |
| |
| Just like `error' this function only returned if STATUS is zero. |
| Otherwise `exit' is called with the non-zero value. If `error' |
| returns the global variable `error_message_count' is incremented |
| by one to keep track of the number of errors reported. |
| |
| As mentioned above the `error' and `error_at_line' functions can be |
| customized by defining a variable named `error_print_progname'. |
| |
| -- Variable: void (*error_print_progname) (void) |
| If the `error_print_progname' variable is defined to a non-zero |
| value the function pointed to is called by `error' or |
| `error_at_line'. It is expected to print the program name or do |
| something similarly useful. |
| |
| The function is expected to be print to the `stderr' stream and |
| must be able to handle whatever orientation the stream has. |
| |
| The variable is global and shared by all threads. |
| |
| -- Variable: unsigned int error_message_count |
| The `error_message_count' variable is incremented whenever one of |
| the functions `error' or `error_at_line' returns. The variable is |
| global and shared by all threads. |
| |
| -- Variable: int error_one_per_line |
| The `error_one_per_line' variable influences only `error_at_line'. |
| Normally the `error_at_line' function creates output for every |
| invocation. If `error_one_per_line' is set to a non-zero value |
| `error_at_line' keeps track of the last file name and line number |
| for which an error was reported and avoid directly following |
| messages for the same file and line. This variable is global and |
| shared by all threads. |
| |
| A program which read some input file and reports errors in it could look |
| like this: |
| |
| { |
| char *line = NULL; |
| size_t len = 0; |
| unsigned int lineno = 0; |
| |
| error_message_count = 0; |
| while (! feof_unlocked (fp)) |
| { |
| ssize_t n = getline (&line, &len, fp); |
| if (n <= 0) |
| /* End of file or error. */ |
| break; |
| ++lineno; |
| |
| /* Process the line. */ |
| ... |
| |
| if (Detect error in line) |
| error_at_line (0, errval, filename, lineno, |
| "some error text %s", some_variable); |
| } |
| |
| if (error_message_count != 0) |
| error (EXIT_FAILURE, 0, "%u errors found", error_message_count); |
| } |
| |
| `error' and `error_at_line' are clearly the functions of choice and |
| enable the programmer to write applications which follow the GNU coding |
| standard. The GNU C Library additionally contains functions which are |
| used in BSD for the same purpose. These functions are declared in |
| `err.h'. It is generally advised to not use these functions. They are |
| included only for compatibility. |
| |
| -- Function: void warn (const char *FORMAT, ...) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap i18n | |
| AC-Unsafe corrupt lock mem | *Note POSIX Safety Concepts::. |
| |
| The `warn' function is roughly equivalent to a call like |
| error (0, errno, format, the parameters) |
| except that the global variables `error' respects and modifies are |
| not used. |
| |
| -- Function: void vwarn (const char *FORMAT, va_list AP) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap i18n | |
| AC-Unsafe corrupt lock mem | *Note POSIX Safety Concepts::. |
| |
| The `vwarn' function is just like `warn' except that the |
| parameters for the handling of the format string FORMAT are passed |
| in as a value of type `va_list'. |
| |
| -- Function: void warnx (const char *FORMAT, ...) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe |
| corrupt lock mem | *Note POSIX Safety Concepts::. |
| |
| The `warnx' function is roughly equivalent to a call like |
| error (0, 0, format, the parameters) |
| except that the global variables `error' respects and modifies are |
| not used. The difference to `warn' is that no error number string |
| is printed. |
| |
| -- Function: void vwarnx (const char *FORMAT, va_list AP) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe |
| corrupt lock mem | *Note POSIX Safety Concepts::. |
| |
| The `vwarnx' function is just like `warnx' except that the |
| parameters for the handling of the format string FORMAT are passed |
| in as a value of type `va_list'. |
| |
| -- Function: void err (int STATUS, const char *FORMAT, ...) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap i18n | |
| AC-Unsafe corrupt lock mem | *Note POSIX Safety Concepts::. |
| |
| The `err' function is roughly equivalent to a call like |
| error (status, errno, format, the parameters) |
| except that the global variables `error' respects and modifies are |
| not used and that the program is exited even if STATUS is zero. |
| |
| -- Function: void verr (int STATUS, const char *FORMAT, va_list AP) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap i18n | |
| AC-Unsafe corrupt lock mem | *Note POSIX Safety Concepts::. |
| |
| The `verr' function is just like `err' except that the parameters |
| for the handling of the format string FORMAT are passed in as a |
| value of type `va_list'. |
| |
| -- Function: void errx (int STATUS, const char *FORMAT, ...) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe |
| corrupt lock mem | *Note POSIX Safety Concepts::. |
| |
| The `errx' function is roughly equivalent to a call like |
| error (status, 0, format, the parameters) |
| except that the global variables `error' respects and modifies are |
| not used and that the program is exited even if STATUS is zero. |
| The difference to `err' is that no error number string is printed. |
| |
| -- Function: void verrx (int STATUS, const char *FORMAT, va_list AP) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe |
| corrupt lock mem | *Note POSIX Safety Concepts::. |
| |
| The `verrx' function is just like `errx' except that the |
| parameters for the handling of the format string FORMAT are passed |
| in as a value of type `va_list'. |
| |
| |
| File: libc.info, Node: Memory, Next: Character Handling, Prev: Error Reporting, Up: Top |
| |
| 3 Virtual Memory Allocation And Paging |
| ************************************** |
| |
| This chapter describes how processes manage and use memory in a system |
| that uses the GNU C Library. |
| |
| The GNU C Library has several functions for dynamically allocating |
| virtual memory in various ways. They vary in generality and in |
| efficiency. The library also provides functions for controlling paging |
| and allocation of real memory. |
| |
| * Menu: |
| |
| * Memory Concepts:: An introduction to concepts and terminology. |
| * Memory Allocation:: Allocating storage for your program data |
| * Resizing the Data Segment:: `brk', `sbrk' |
| * Locking Pages:: Preventing page faults |
| |
| Memory mapped I/O is not discussed in this chapter. *Note |
| Memory-mapped I/O::. |
| |
| |
| File: libc.info, Node: Memory Concepts, Next: Memory Allocation, Up: Memory |
| |
| 3.1 Process Memory Concepts |
| =========================== |
| |
| One of the most basic resources a process has available to it is memory. |
| There are a lot of different ways systems organize memory, but in a |
| typical one, each process has one linear virtual address space, with |
| addresses running from zero to some huge maximum. It need not be |
| contiguous; i.e., not all of these addresses actually can be used to |
| store data. |
| |
| The virtual memory is divided into pages (4 kilobytes is typical). |
| Backing each page of virtual memory is a page of real memory (called a |
| "frame") or some secondary storage, usually disk space. The disk space |
| might be swap space or just some ordinary disk file. Actually, a page |
| of all zeroes sometimes has nothing at all backing it - there's just a |
| flag saying it is all zeroes. |
| |
| The same frame of real memory or backing store can back multiple |
| virtual pages belonging to multiple processes. This is normally the |
| case, for example, with virtual memory occupied by GNU C Library code. |
| The same real memory frame containing the `printf' function backs a |
| virtual memory page in each of the existing processes that has a |
| `printf' call in its program. |
| |
| In order for a program to access any part of a virtual page, the page |
| must at that moment be backed by ("connected to") a real frame. But |
| because there is usually a lot more virtual memory than real memory, the |
| pages must move back and forth between real memory and backing store |
| regularly, coming into real memory when a process needs to access them |
| and then retreating to backing store when not needed anymore. This |
| movement is called "paging". |
| |
| When a program attempts to access a page which is not at that moment |
| backed by real memory, this is known as a "page fault". When a page |
| fault occurs, the kernel suspends the process, places the page into a |
| real page frame (this is called "paging in" or "faulting in"), then |
| resumes the process so that from the process' point of view, the page |
| was in real memory all along. In fact, to the process, all pages always |
| seem to be in real memory. Except for one thing: the elapsed execution |
| time of an instruction that would normally be a few nanoseconds is |
| suddenly much, much, longer (because the kernel normally has to do I/O |
| to complete the page-in). For programs sensitive to that, the functions |
| described in *note Locking Pages:: can control it. |
| |
| Within each virtual address space, a process has to keep track of |
| what is at which addresses, and that process is called memory |
| allocation. Allocation usually brings to mind meting out scarce |
| resources, but in the case of virtual memory, that's not a major goal, |
| because there is generally much more of it than anyone needs. Memory |
| allocation within a process is mainly just a matter of making sure that |
| the same byte of memory isn't used to store two different things. |
| |
| Processes allocate memory in two major ways: by exec and |
| programmatically. Actually, forking is a third way, but it's not very |
| interesting. *Note Creating a Process::. |
| |
| Exec is the operation of creating a virtual address space for a |
| process, loading its basic program into it, and executing the program. |
| It is done by the "exec" family of functions (e.g. `execl'). The |
| operation takes a program file (an executable), it allocates space to |
| load all the data in the executable, loads it, and transfers control to |
| it. That data is most notably the instructions of the program (the |
| "text"), but also literals and constants in the program and even some |
| variables: C variables with the static storage class (*note Memory |
| Allocation and C::). |
| |
| Once that program begins to execute, it uses programmatic allocation |
| to gain additional memory. In a C program with the GNU C Library, there |
| are two kinds of programmatic allocation: automatic and dynamic. *Note |
| Memory Allocation and C::. |
| |
| Memory-mapped I/O is another form of dynamic virtual memory |
| allocation. Mapping memory to a file means declaring that the contents |
| of certain range of a process' addresses shall be identical to the |
| contents of a specified regular file. The system makes the virtual |
| memory initially contain the contents of the file, and if you modify |
| the memory, the system writes the same modification to the file. Note |
| that due to the magic of virtual memory and page faults, there is no |
| reason for the system to do I/O to read the file, or allocate real |
| memory for its contents, until the program accesses the virtual memory. |
| *Note Memory-mapped I/O::. |
| |
| Just as it programmatically allocates memory, the program can |
| programmatically deallocate ("free") it. You can't free the memory |
| that was allocated by exec. When the program exits or execs, you might |
| say that all its memory gets freed, but since in both cases the address |
| space ceases to exist, the point is really moot. *Note Program |
| Termination::. |
| |
| A process' virtual address space is divided into segments. A |
| segment is a contiguous range of virtual addresses. Three important |
| segments are: |
| |
| * The "text segment" contains a program's instructions and literals |
| and static constants. It is allocated by exec and stays the same |
| size for the life of the virtual address space. |
| |
| * The "data segment" is working storage for the program. It can be |
| preallocated and preloaded by exec and the process can extend or |
| shrink it by calling functions as described in *Note Resizing the |
| Data Segment::. Its lower end is fixed. |
| |
| * The "stack segment" contains a program stack. It grows as the |
| stack grows, but doesn't shrink when the stack shrinks. |
| |
| |
| |
| File: libc.info, Node: Memory Allocation, Next: Resizing the Data Segment, Prev: Memory Concepts, Up: Memory |
| |
| 3.2 Allocating Storage For Program Data |
| ======================================= |
| |
| This section covers how ordinary programs manage storage for their data, |
| including the famous `malloc' function and some fancier facilities |
| special the GNU C Library and GNU Compiler. |
| |
| * Menu: |
| |
| * Memory Allocation and C:: How to get different kinds of allocation in C. |
| * Unconstrained Allocation:: The `malloc' facility allows fully general |
| dynamic allocation. |
| * Allocation Debugging:: Finding memory leaks and not freed memory. |
| * Obstacks:: Obstacks are less general than malloc |
| but more efficient and convenient. |
| * Variable Size Automatic:: Allocation of variable-sized blocks |
| of automatic storage that are freed when the |
| calling function returns. |
| |
| |
| File: libc.info, Node: Memory Allocation and C, Next: Unconstrained Allocation, Up: Memory Allocation |
| |
| 3.2.1 Memory Allocation in C Programs |
| ------------------------------------- |
| |
| The C language supports two kinds of memory allocation through the |
| variables in C programs: |
| |
| * "Static allocation" is what happens when you declare a static or |
| global variable. Each static or global variable defines one block |
| of space, of a fixed size. The space is allocated once, when your |
| program is started (part of the exec operation), and is never |
| freed. |
| |
| * "Automatic allocation" happens when you declare an automatic |
| variable, such as a function argument or a local variable. The |
| space for an automatic variable is allocated when the compound |
| statement containing the declaration is entered, and is freed when |
| that compound statement is exited. |
| |
| In GNU C, the size of the automatic storage can be an expression |
| that varies. In other C implementations, it must be a constant. |
| |
| A third important kind of memory allocation, "dynamic allocation", |
| is not supported by C variables but is available via GNU C Library |
| functions. |
| |
| 3.2.1.1 Dynamic Memory Allocation |
| ................................. |
| |
| "Dynamic memory allocation" is a technique in which programs determine |
| as they are running where to store some information. You need dynamic |
| allocation when the amount of memory you need, or how long you continue |
| to need it, depends on factors that are not known before the program |
| runs. |
| |
| For example, you may need a block to store a line read from an input |
| file; since there is no limit to how long a line can be, you must |
| allocate the memory dynamically and make it dynamically larger as you |
| read more of the line. |
| |
| Or, you may need a block for each record or each definition in the |
| input data; since you can't know in advance how many there will be, you |
| must allocate a new block for each record or definition as you read it. |
| |
| When you use dynamic allocation, the allocation of a block of memory |
| is an action that the program requests explicitly. You call a function |
| or macro when you want to allocate space, and specify the size with an |
| argument. If you want to free the space, you do so by calling another |
| function or macro. You can do these things whenever you want, as often |
| as you want. |
| |
| Dynamic allocation is not supported by C variables; there is no |
| storage class "dynamic", and there can never be a C variable whose |
| value is stored in dynamically allocated space. The only way to get |
| dynamically allocated memory is via a system call (which is generally |
| via a GNU C Library function call), and the only way to refer to |
| dynamically allocated space is through a pointer. Because it is less |
| convenient, and because the actual process of dynamic allocation |
| requires more computation time, programmers generally use dynamic |
| allocation only when neither static nor automatic allocation will serve. |
| |
| For example, if you want to allocate dynamically some space to hold a |
| `struct foobar', you cannot declare a variable of type `struct foobar' |
| whose contents are the dynamically allocated space. But you can |
| declare a variable of pointer type `struct foobar *' and assign it the |
| address of the space. Then you can use the operators `*' and `->' on |
| this pointer variable to refer to the contents of the space: |
| |
| { |
| struct foobar *ptr |
| = (struct foobar *) malloc (sizeof (struct foobar)); |
| ptr->name = x; |
| ptr->next = current_foobar; |
| current_foobar = ptr; |
| } |
| |
| |
| File: libc.info, Node: Unconstrained Allocation, Next: Allocation Debugging, Prev: Memory Allocation and C, Up: Memory Allocation |
| |
| 3.2.2 Unconstrained Allocation |
| ------------------------------ |
| |
| The most general dynamic allocation facility is `malloc'. It allows |
| you to allocate blocks of memory of any size at any time, make them |
| bigger or smaller at any time, and free the blocks individually at any |
| time (or never). |
| |
| * Menu: |
| |
| * Basic Allocation:: Simple use of `malloc'. |
| * Malloc Examples:: Examples of `malloc'. `xmalloc'. |
| * Freeing after Malloc:: Use `free' to free a block you |
| got with `malloc'. |
| * Changing Block Size:: Use `realloc' to make a block |
| bigger or smaller. |
| * Allocating Cleared Space:: Use `calloc' to allocate a |
| block and clear it. |
| * Efficiency and Malloc:: Efficiency considerations in use of |
| these functions. |
| * Aligned Memory Blocks:: Allocating specially aligned memory. |
| * Malloc Tunable Parameters:: Use `mallopt' to adjust allocation |
| parameters. |
| * Heap Consistency Checking:: Automatic checking for errors. |
| * Hooks for Malloc:: You can use these hooks for debugging |
| programs that use `malloc'. |
| * Statistics of Malloc:: Getting information about how much |
| memory your program is using. |
| * Summary of Malloc:: Summary of `malloc' and related functions. |
| |
| |
| File: libc.info, Node: Basic Allocation, Next: Malloc Examples, Up: Unconstrained Allocation |
| |
| 3.2.2.1 Basic Memory Allocation |
| ............................... |
| |
| To allocate a block of memory, call `malloc'. The prototype for this |
| function is in `stdlib.h'. |
| |
| -- Function: void * malloc (size_t SIZE) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd mem | |
| *Note POSIX Safety Concepts::. |
| |
| This function returns a pointer to a newly allocated block SIZE |
| bytes long, or a null pointer if the block could not be allocated. |
| |
| The contents of the block are undefined; you must initialize it |
| yourself (or use `calloc' instead; *note Allocating Cleared Space::). |
| Normally you would cast the value as a pointer to the kind of object |
| that you want to store in the block. Here we show an example of doing |
| so, and of initializing the space with zeros using the library function |
| `memset' (*note Copying and Concatenation::): |
| |
| struct foo *ptr; |
| ... |
| ptr = (struct foo *) malloc (sizeof (struct foo)); |
| if (ptr == 0) abort (); |
| memset (ptr, 0, sizeof (struct foo)); |
| |
| You can store the result of `malloc' into any pointer variable |
| without a cast, because ISO C automatically converts the type `void *' |
| to another type of pointer when necessary. But the cast is necessary |
| in contexts other than assignment operators or if you might want your |
| code to run in traditional C. |
| |
| Remember that when allocating space for a string, the argument to |
| `malloc' must be one plus the length of the string. This is because a |
| string is terminated with a null character that doesn't count in the |
| "length" of the string but does need space. For example: |
| |
| char *ptr; |
| ... |
| ptr = (char *) malloc (length + 1); |
| |
| *Note Representation of Strings::, for more information about this. |
| |
| |
| File: libc.info, Node: Malloc Examples, Next: Freeing after Malloc, Prev: Basic Allocation, Up: Unconstrained Allocation |
| |
| 3.2.2.2 Examples of `malloc' |
| ............................ |
| |
| If no more space is available, `malloc' returns a null pointer. You |
| should check the value of _every_ call to `malloc'. It is useful to |
| write a subroutine that calls `malloc' and reports an error if the |
| value is a null pointer, returning only if the value is nonzero. This |
| function is conventionally called `xmalloc'. Here it is: |
| |
| void * |
| xmalloc (size_t size) |
| { |
| void *value = malloc (size); |
| if (value == 0) |
| fatal ("virtual memory exhausted"); |
| return value; |
| } |
| |
| Here is a real example of using `malloc' (by way of `xmalloc'). The |
| function `savestring' will copy a sequence of characters into a newly |
| allocated null-terminated string: |
| |
| char * |
| savestring (const char *ptr, size_t len) |
| { |
| char *value = (char *) xmalloc (len + 1); |
| value[len] = '\0'; |
| return (char *) memcpy (value, ptr, len); |
| } |
| |
| The block that `malloc' gives you is guaranteed to be aligned so |
| that it can hold any type of data. On GNU systems, the address is |
| always a multiple of eight on 32-bit systems, and a multiple of 16 on |
| 64-bit systems. Only rarely is any higher boundary (such as a page |
| boundary) necessary; for those cases, use `aligned_alloc' or |
| `posix_memalign' (*note Aligned Memory Blocks::). |
| |
| Note that the memory located after the end of the block is likely to |
| be in use for something else; perhaps a block already allocated by |
| another call to `malloc'. If you attempt to treat the block as longer |
| than you asked for it to be, you are liable to destroy the data that |
| `malloc' uses to keep track of its blocks, or you may destroy the |
| contents of another block. If you have already allocated a block and |
| discover you want it to be bigger, use `realloc' (*note Changing Block |
| Size::). |
| |
| |
| File: libc.info, Node: Freeing after Malloc, Next: Changing Block Size, Prev: Malloc Examples, Up: Unconstrained Allocation |
| |
| 3.2.2.3 Freeing Memory Allocated with `malloc' |
| .............................................. |
| |
| When you no longer need a block that you got with `malloc', use the |
| function `free' to make the block available to be allocated again. The |
| prototype for this function is in `stdlib.h'. |
| |
| -- Function: void free (void *PTR) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd mem | |
| *Note POSIX Safety Concepts::. |
| |
| The `free' function deallocates the block of memory pointed at by |
| PTR. |
| |
| -- Function: void cfree (void *PTR) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd mem | |
| *Note POSIX Safety Concepts::. |
| |
| This function does the same thing as `free'. It's provided for |
| backward compatibility with SunOS; you should use `free' instead. |
| |
| Freeing a block alters the contents of the block. *Do not expect to |
| find any data (such as a pointer to the next block in a chain of |
| blocks) in the block after freeing it.* Copy whatever you need out of |
| the block before freeing it! Here is an example of the proper way to |
| free all the blocks in a chain, and the strings that they point to: |
| |
| struct chain |
| { |
| struct chain *next; |
| char *name; |
| } |
| |
| void |
| free_chain (struct chain *chain) |
| { |
| while (chain != 0) |
| { |
| struct chain *next = chain->next; |
| free (chain->name); |
| free (chain); |
| chain = next; |
| } |
| } |
| |
| Occasionally, `free' can actually return memory to the operating |
| system and make the process smaller. Usually, all it can do is allow a |
| later call to `malloc' to reuse the space. In the meantime, the space |
| remains in your program as part of a free-list used internally by |
| `malloc'. |
| |
| There is no point in freeing blocks at the end of a program, because |
| all of the program's space is given back to the system when the process |
| terminates. |
| |
| |
| File: libc.info, Node: Changing Block Size, Next: Allocating Cleared Space, Prev: Freeing after Malloc, Up: Unconstrained Allocation |
| |
| 3.2.2.4 Changing the Size of a Block |
| .................................... |
| |
| Often you do not know for certain how big a block you will ultimately |
| need at the time you must begin to use the block. For example, the |
| block might be a buffer that you use to hold a line being read from a |
| file; no matter how long you make the buffer initially, you may |
| encounter a line that is longer. |
| |
| You can make the block longer by calling `realloc'. This function |
| is declared in `stdlib.h'. |
| |
| -- Function: void * realloc (void *PTR, size_t NEWSIZE) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd mem | |
| *Note POSIX Safety Concepts::. |
| |
| The `realloc' function changes the size of the block whose address |
| is PTR to be NEWSIZE. |
| |
| Since the space after the end of the block may be in use, `realloc' |
| may find it necessary to copy the block to a new address where |
| more free space is available. The value of `realloc' is the new |
| address of the block. If the block needs to be moved, `realloc' |
| copies the old contents. |
| |
| If you pass a null pointer for PTR, `realloc' behaves just like |
| `malloc (NEWSIZE)'. This can be convenient, but beware that older |
| implementations (before ISO C) may not support this behavior, and |
| will probably crash when `realloc' is passed a null pointer. |
| |
| Like `malloc', `realloc' may return a null pointer if no memory |
| space is available to make the block bigger. When this happens, the |
| original block is untouched; it has not been modified or relocated. |
| |
| In most cases it makes no difference what happens to the original |
| block when `realloc' fails, because the application program cannot |
| continue when it is out of memory, and the only thing to do is to give |
| a fatal error message. Often it is convenient to write and use a |
| subroutine, conventionally called `xrealloc', that takes care of the |
| error message as `xmalloc' does for `malloc': |
| |
| void * |
| xrealloc (void *ptr, size_t size) |
| { |
| void *value = realloc (ptr, size); |
| if (value == 0) |
| fatal ("Virtual memory exhausted"); |
| return value; |
| } |
| |
| You can also use `realloc' to make a block smaller. The reason you |
| would do this is to avoid tying up a lot of memory space when only a |
| little is needed. In several allocation implementations, making a |
| block smaller sometimes necessitates copying it, so it can fail if no |
| other space is available. |
| |
| If the new size you specify is the same as the old size, `realloc' |
| is guaranteed to change nothing and return the same address that you |
| gave. |
| |
| |
| File: libc.info, Node: Allocating Cleared Space, Next: Efficiency and Malloc, Prev: Changing Block Size, Up: Unconstrained Allocation |
| |
| 3.2.2.5 Allocating Cleared Space |
| ................................ |
| |
| The function `calloc' allocates memory and clears it to zero. It is |
| declared in `stdlib.h'. |
| |
| -- Function: void * calloc (size_t COUNT, size_t ELTSIZE) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd mem | |
| *Note POSIX Safety Concepts::. |
| |
| This function allocates a block long enough to contain a vector of |
| COUNT elements, each of size ELTSIZE. Its contents are cleared to |
| zero before `calloc' returns. |
| |
| You could define `calloc' as follows: |
| |
| void * |
| calloc (size_t count, size_t eltsize) |
| { |
| size_t size = count * eltsize; |
| void *value = malloc (size); |
| if (value != 0) |
| memset (value, 0, size); |
| return value; |
| } |
| |
| But in general, it is not guaranteed that `calloc' calls `malloc' |
| internally. Therefore, if an application provides its own |
| `malloc'/`realloc'/`free' outside the C library, it should always |
| define `calloc', too. |
| |
| |
| File: libc.info, Node: Efficiency and Malloc, Next: Aligned Memory Blocks, Prev: Allocating Cleared Space, Up: Unconstrained Allocation |
| |
| 3.2.2.6 Efficiency Considerations for `malloc' |
| .............................................. |
| |
| As opposed to other versions, the `malloc' in the GNU C Library does |
| not round up block sizes to powers of two, neither for large nor for |
| small sizes. Neighboring chunks can be coalesced on a `free' no matter |
| what their size is. This makes the implementation suitable for all |
| kinds of allocation patterns without generally incurring high memory |
| waste through fragmentation. |
| |
| Very large blocks (much larger than a page) are allocated with |
| `mmap' (anonymous or via `/dev/zero') by this implementation. This has |
| the great advantage that these chunks are returned to the system |
| immediately when they are freed. Therefore, it cannot happen that a |
| large chunk becomes "locked" in between smaller ones and even after |
| calling `free' wastes memory. The size threshold for `mmap' to be used |
| can be adjusted with `mallopt'. The use of `mmap' can also be disabled |
| completely. |
| |
| |
| File: libc.info, Node: Aligned Memory Blocks, Next: Malloc Tunable Parameters, Prev: Efficiency and Malloc, Up: Unconstrained Allocation |
| |
| 3.2.2.7 Allocating Aligned Memory Blocks |
| ........................................ |
| |
| The address of a block returned by `malloc' or `realloc' in GNU systems |
| is always a multiple of eight (or sixteen on 64-bit systems). If you |
| need a block whose address is a multiple of a higher power of two than |
| that, use `aligned_alloc' or `posix_memalign'. `aligned_alloc' and |
| `posix_memalign' are declared in `stdlib.h'. |
| |
| -- Function: void * aligned_alloc (size_t ALIGNMENT, size_t SIZE) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd mem | |
| *Note POSIX Safety Concepts::. |
| |
| The `aligned_alloc' function allocates a block of SIZE bytes whose |
| address is a multiple of ALIGNMENT. The ALIGNMENT must be a power |
| of two and SIZE must be a multiple of ALIGNMENT. |
| |
| The `aligned_alloc' function returns a null pointer on error and |
| sets `errno' to one of the following values: |
| |
| `ENOMEM' |
| There was insufficient memory available to satisfy the |
| request. |
| |
| `EINVAL' |
| ALIGNMENT is not a power of two. |
| |
| This function was introduced in ISO C11 and hence may have |
| better portability to modern non-POSIX systems than |
| `posix_memalign'. |
| |
| |
| -- Function: void * memalign (size_t BOUNDARY, size_t SIZE) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd mem | |
| *Note POSIX Safety Concepts::. |
| |
| The `memalign' function allocates a block of SIZE bytes whose |
| address is a multiple of BOUNDARY. The BOUNDARY must be a power |
| of two! The function `memalign' works by allocating a somewhat |
| larger block, and then returning an address within the block that |
| is on the specified boundary. |
| |
| The `memalign' function returns a null pointer on error and sets |
| `errno' to one of the following values: |
| |
| `ENOMEM' |
| There was insufficient memory available to satisfy the |
| request. |
| |
| `EINVAL' |
| ALIGNMENT is not a power of two. |
| |
| |
| The `memalign' function is obsolete and `aligned_alloc' or |
| `posix_memalign' should be used instead. |
| |
| -- Function: int posix_memalign (void **MEMPTR, size_t ALIGNMENT, |
| size_t SIZE) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd mem | |
| *Note POSIX Safety Concepts::. |
| |
| The `posix_memalign' function is similar to the `memalign' |
| function in that it returns a buffer of SIZE bytes aligned to a |
| multiple of ALIGNMENT. But it adds one requirement to the |
| parameter ALIGNMENT: the value must be a power of two multiple of |
| `sizeof (void *)'. |
| |
| If the function succeeds in allocation memory a pointer to the |
| allocated memory is returned in `*MEMPTR' and the return value is |
| zero. Otherwise the function returns an error value indicating |
| the problem. The possible error values returned are: |
| |
| `ENOMEM' |
| There was insufficient memory available to satisfy the |
| request. |
| |
| `EINVAL' |
| ALIGNMENT is not a power of two multiple of `sizeof (void *)'. |
| |
| |
| This function was introduced in POSIX 1003.1d. Although this |
| function is superseded by `aligned_alloc', it is more portable to |
| older POSIX systems that do not support ISO C11. |
| |
| -- Function: void * valloc (size_t SIZE) |
| Preliminary: | MT-Unsafe init | AS-Unsafe init lock | AC-Unsafe |
| init lock fd mem | *Note POSIX Safety Concepts::. |
| |
| Using `valloc' is like using `memalign' and passing the page size |
| as the value of the second argument. It is implemented like this: |
| |
| void * |
| valloc (size_t size) |
| { |
| return memalign (getpagesize (), size); |
| } |
| |
| *note Query Memory Parameters:: for more information about the |
| memory subsystem. |
| |
| The `valloc' function is obsolete and `aligned_alloc' or |
| `posix_memalign' should be used instead. |
| |
| |
| File: libc.info, Node: Malloc Tunable Parameters, Next: Heap Consistency Checking, Prev: Aligned Memory Blocks, Up: Unconstrained Allocation |
| |
| 3.2.2.8 Malloc Tunable Parameters |
| ................................. |
| |
| You can adjust some parameters for dynamic memory allocation with the |
| `mallopt' function. This function is the general SVID/XPG interface, |
| defined in `malloc.h'. |
| |
| -- Function: int mallopt (int PARAM, int VALUE) |
| Preliminary: | MT-Unsafe init const:mallopt | AS-Unsafe init lock |
| | AC-Unsafe init lock | *Note POSIX Safety Concepts::. |
| |
| When calling `mallopt', the PARAM argument specifies the parameter |
| to be set, and VALUE the new value to be set. Possible choices |
| for PARAM, as defined in `malloc.h', are: |
| |
| `M_MMAP_MAX' |
| The maximum number of chunks to allocate with `mmap'. |
| Setting this to zero disables all use of `mmap'. |
| |
| `M_MMAP_THRESHOLD' |
| All chunks larger than this value are allocated outside the |
| normal heap, using the `mmap' system call. This way it is |
| guaranteed that the memory for these chunks can be returned |
| to the system on `free'. Note that requests smaller than |
| this threshold might still be allocated via `mmap'. |
| |
| `M_PERTURB' |
| If non-zero, memory blocks are filled with values depending |
| on some low order bits of this parameter when they are |
| allocated (except when allocated by `calloc') and freed. |
| This can be used to debug the use of uninitialized or freed |
| heap memory. Note that this option does not guarantee that |
| the freed block will have any specific values. It only |
| guarantees that the content the block had before it was freed |
| will be overwritten. |
| |
| `M_TOP_PAD' |
| This parameter determines the amount of extra memory to |
| obtain from the system when a call to `sbrk' is required. It |
| also specifies the number of bytes to retain when shrinking |
| the heap by calling `sbrk' with a negative argument. This |
| provides the necessary hysteresis in heap size such that |
| excessive amounts of system calls can be avoided. |
| |
| `M_TRIM_THRESHOLD' |
| This is the minimum size (in bytes) of the top-most, |
| releasable chunk that will cause `sbrk' to be called with a |
| negative argument in order to return memory to the system. |
| |
| |
| |
| File: libc.info, Node: Heap Consistency Checking, Next: Hooks for Malloc, Prev: Malloc Tunable Parameters, Up: Unconstrained Allocation |
| |
| 3.2.2.9 Heap Consistency Checking |
| ................................. |
| |
| You can ask `malloc' to check the consistency of dynamic memory by |
| using the `mcheck' function. This function is a GNU extension, |
| declared in `mcheck.h'. |
| |
| -- Function: int mcheck (void (*ABORTFN) (enum mcheck_status STATUS)) |
| Preliminary: | MT-Unsafe race:mcheck const:malloc_hooks | |
| AS-Unsafe corrupt | AC-Unsafe corrupt | *Note POSIX Safety |
| Concepts::. |
| |
| Calling `mcheck' tells `malloc' to perform occasional consistency |
| checks. These will catch things such as writing past the end of a |
| block that was allocated with `malloc'. |
| |
| The ABORTFN argument is the function to call when an inconsistency |
| is found. If you supply a null pointer, then `mcheck' uses a |
| default function which prints a message and calls `abort' (*note |
| Aborting a Program::). The function you supply is called with one |
| argument, which says what sort of inconsistency was detected; its |
| type is described below. |
| |
| It is too late to begin allocation checking once you have allocated |
| anything with `malloc'. So `mcheck' does nothing in that case. |
| The function returns `-1' if you call it too late, and `0' |
| otherwise (when it is successful). |
| |
| The easiest way to arrange to call `mcheck' early enough is to use |
| the option `-lmcheck' when you link your program; then you don't |
| need to modify your program source at all. Alternatively you |
| might use a debugger to insert a call to `mcheck' whenever the |
| program is started, for example these gdb commands will |
| automatically call `mcheck' whenever the program starts: |
| |
| (gdb) break main |
| Breakpoint 1, main (argc=2, argv=0xbffff964) at whatever.c:10 |
| (gdb) command 1 |
| Type commands for when breakpoint 1 is hit, one per line. |
| End with a line saying just "end". |
| >call mcheck(0) |
| >continue |
| >end |
| (gdb) ... |
| |
| This will however only work if no initialization function of any |
| object involved calls any of the `malloc' functions since `mcheck' |
| must be called before the first such function. |
| |
| |
| -- Function: enum mcheck_status mprobe (void *POINTER) |
| Preliminary: | MT-Unsafe race:mcheck const:malloc_hooks | |
| AS-Unsafe corrupt | AC-Unsafe corrupt | *Note POSIX Safety |
| Concepts::. |
| |
| The `mprobe' function lets you explicitly check for inconsistencies |
| in a particular allocated block. You must have already called |
| `mcheck' at the beginning of the program, to do its occasional |
| checks; calling `mprobe' requests an additional consistency check |
| to be done at the time of the call. |
| |
| The argument POINTER must be a pointer returned by `malloc' or |
| `realloc'. `mprobe' returns a value that says what inconsistency, |
| if any, was found. The values are described below. |
| |
| -- Data Type: enum mcheck_status |
| This enumerated type describes what kind of inconsistency was |
| detected in an allocated block, if any. Here are the possible |
| values: |
| |
| `MCHECK_DISABLED' |
| `mcheck' was not called before the first allocation. No |
| consistency checking can be done. |
| |
| `MCHECK_OK' |
| No inconsistency detected. |
| |
| `MCHECK_HEAD' |
| The data immediately before the block was modified. This |
| commonly happens when an array index or pointer is |
| decremented too far. |
| |
| `MCHECK_TAIL' |
| The data immediately after the block was modified. This |
| commonly happens when an array index or pointer is |
| incremented too far. |
| |
| `MCHECK_FREE' |
| The block was already freed. |
| |
| Another possibility to check for and guard against bugs in the use of |
| `malloc', `realloc' and `free' is to set the environment variable |
| `MALLOC_CHECK_'. When `MALLOC_CHECK_' is set, a special (less |
| efficient) implementation is used which is designed to be tolerant |
| against simple errors, such as double calls of `free' with the same |
| argument, or overruns of a single byte (off-by-one bugs). Not all such |
| errors can be protected against, however, and memory leaks can result. |
| If `MALLOC_CHECK_' is set to `0', any detected heap corruption is |
| silently ignored; if set to `1', a diagnostic is printed on `stderr'; |
| if set to `2', `abort' is called immediately. This can be useful |
| because otherwise a crash may happen much later, and the true cause for |
| the problem is then very hard to track down. |
| |
| There is one problem with `MALLOC_CHECK_': in SUID or SGID binaries |
| it could possibly be exploited since diverging from the normal programs |
| behavior it now writes something to the standard error descriptor. |
| Therefore the use of `MALLOC_CHECK_' is disabled by default for SUID |
| and SGID binaries. It can be enabled again by the system administrator |
| by adding a file `/etc/suid-debug' (the content is not important it |
| could be empty). |
| |
| So, what's the difference between using `MALLOC_CHECK_' and linking |
| with `-lmcheck'? `MALLOC_CHECK_' is orthogonal with respect to |
| `-lmcheck'. `-lmcheck' has been added for backward compatibility. |
| Both `MALLOC_CHECK_' and `-lmcheck' should uncover the same bugs - but |
| using `MALLOC_CHECK_' you don't need to recompile your application. |
| |
| |
| File: libc.info, Node: Hooks for Malloc, Next: Statistics of Malloc, Prev: Heap Consistency Checking, Up: Unconstrained Allocation |
| |
| 3.2.2.10 Memory Allocation Hooks |
| ................................ |
| |
| The GNU C Library lets you modify the behavior of `malloc', `realloc', |
| and `free' by specifying appropriate hook functions. You can use these |
| hooks to help you debug programs that use dynamic memory allocation, |
| for example. |
| |
| The hook variables are declared in `malloc.h'. |
| |
| -- Variable: __malloc_hook |
| The value of this variable is a pointer to the function that |
| `malloc' uses whenever it is called. You should define this |
| function to look like `malloc'; that is, like: |
| |
| void *FUNCTION (size_t SIZE, const void *CALLER) |
| |
| The value of CALLER is the return address found on the stack when |
| the `malloc' function was called. This value allows you to trace |
| the memory consumption of the program. |
| |
| -- Variable: __realloc_hook |
| The value of this variable is a pointer to function that `realloc' |
| uses whenever it is called. You should define this function to |
| look like `realloc'; that is, like: |
| |
| void *FUNCTION (void *PTR, size_t SIZE, const void *CALLER) |
| |
| The value of CALLER is the return address found on the stack when |
| the `realloc' function was called. This value allows you to trace |
| the memory consumption of the program. |
| |
| -- Variable: __free_hook |
| The value of this variable is a pointer to function that `free' |
| uses whenever it is called. You should define this function to |
| look like `free'; that is, like: |
| |
| void FUNCTION (void *PTR, const void *CALLER) |
| |
| The value of CALLER is the return address found on the stack when |
| the `free' function was called. This value allows you to trace the |
| memory consumption of the program. |
| |
| -- Variable: __memalign_hook |
| The value of this variable is a pointer to function that |
| `aligned_alloc', `memalign', `posix_memalign' and `valloc' use |
| whenever they are called. You should define this function to look |
| like `aligned_alloc'; that is, like: |
| |
| void *FUNCTION (size_t ALIGNMENT, size_t SIZE, const void *CALLER) |
| |
| The value of CALLER is the return address found on the stack when |
| the `aligned_alloc', `memalign', `posix_memalign' or `valloc' |
| functions are called. This value allows you to trace the memory |
| consumption of the program. |
| |
| You must make sure that the function you install as a hook for one of |
| these functions does not call that function recursively without |
| restoring the old value of the hook first! Otherwise, your program |
| will get stuck in an infinite recursion. Before calling the function |
| recursively, one should make sure to restore all the hooks to their |
| previous value. When coming back from the recursive call, all the |
| hooks should be resaved since a hook might modify itself. |
| |
| -- Variable: __malloc_initialize_hook |
| The value of this variable is a pointer to a function that is |
| called once when the malloc implementation is initialized. This |
| is a weak variable, so it can be overridden in the application |
| with a definition like the following: |
| |
| void (*__MALLOC_INITIALIZE_HOOK) (void) = my_init_hook; |
| |
| An issue to look out for is the time at which the malloc hook |
| functions can be safely installed. If the hook functions call the |
| malloc-related functions recursively, it is necessary that malloc has |
| already properly initialized itself at the time when `__malloc_hook' |
| etc. is assigned to. On the other hand, if the hook functions provide a |
| complete malloc implementation of their own, it is vital that the hooks |
| are assigned to _before_ the very first `malloc' call has completed, |
| because otherwise a chunk obtained from the ordinary, un-hooked malloc |
| may later be handed to `__free_hook', for example. |
| |
| In both cases, the problem can be solved by setting up the hooks from |
| within a user-defined function pointed to by |
| `__malloc_initialize_hook'--then the hooks will be set up safely at the |
| right time. |
| |
| Here is an example showing how to use `__malloc_hook' and |
| `__free_hook' properly. It installs a function that prints out |
| information every time `malloc' or `free' is called. We just assume |
| here that `realloc' and `memalign' are not used in our program. |
| |
| /* Prototypes for __malloc_hook, __free_hook */ |
| #include <malloc.h> |
| |
| /* Prototypes for our hooks. */ |
| static void my_init_hook (void); |
| static void *my_malloc_hook (size_t, const void *); |
| static void my_free_hook (void*, const void *); |
| |
| /* Override initializing hook from the C library. */ |
| void (*__malloc_initialize_hook) (void) = my_init_hook; |
| |
| static void |
| my_init_hook (void) |
| { |
| old_malloc_hook = __malloc_hook; |
| old_free_hook = __free_hook; |
| __malloc_hook = my_malloc_hook; |
| __free_hook = my_free_hook; |
| } |
| |
| static void * |
| my_malloc_hook (size_t size, const void *caller) |
| { |
| void *result; |
| /* Restore all old hooks */ |
| __malloc_hook = old_malloc_hook; |
| __free_hook = old_free_hook; |
| /* Call recursively */ |
| result = malloc (size); |
| /* Save underlying hooks */ |
| old_malloc_hook = __malloc_hook; |
| old_free_hook = __free_hook; |
| /* `printf' might call `malloc', so protect it too. */ |
| printf ("malloc (%u) returns %p\n", (unsigned int) size, result); |
| /* Restore our own hooks */ |
| __malloc_hook = my_malloc_hook; |
| __free_hook = my_free_hook; |
| return result; |
| } |
| |
| static void |
| my_free_hook (void *ptr, const void *caller) |
| { |
| /* Restore all old hooks */ |
| __malloc_hook = old_malloc_hook; |
| __free_hook = old_free_hook; |
| /* Call recursively */ |
| free (ptr); |
| /* Save underlying hooks */ |
| old_malloc_hook = __malloc_hook; |
| old_free_hook = __free_hook; |
| /* `printf' might call `free', so protect it too. */ |
| printf ("freed pointer %p\n", ptr); |
| /* Restore our own hooks */ |
| __malloc_hook = my_malloc_hook; |
| __free_hook = my_free_hook; |
| } |
| |
| main () |
| { |
| ... |
| } |
| |
| The `mcheck' function (*note Heap Consistency Checking::) works by |
| installing such hooks. |
| |
| |
| File: libc.info, Node: Statistics of Malloc, Next: Summary of Malloc, Prev: Hooks for Malloc, Up: Unconstrained Allocation |
| |
| 3.2.2.11 Statistics for Memory Allocation with `malloc' |
| ....................................................... |
| |
| You can get information about dynamic memory allocation by calling the |
| `mallinfo' function. This function and its associated data type are |
| declared in `malloc.h'; they are an extension of the standard SVID/XPG |
| version. |
| |
| -- Data Type: struct mallinfo |
| This structure type is used to return information about the dynamic |
| memory allocator. It contains the following members: |
| |
| `int arena' |
| This is the total size of memory allocated with `sbrk' by |
| `malloc', in bytes. |
| |
| `int ordblks' |
| This is the number of chunks not in use. (The memory |
| allocator internally gets chunks of memory from the operating |
| system, and then carves them up to satisfy individual |
| `malloc' requests; see *note Efficiency and Malloc::.) |
| |
| `int smblks' |
| This field is unused. |
| |
| `int hblks' |
| This is the total number of chunks allocated with `mmap'. |
| |
| `int hblkhd' |
| This is the total size of memory allocated with `mmap', in |
| bytes. |
| |
| `int usmblks' |
| This field is unused. |
| |
| `int fsmblks' |
| This field is unused. |
| |
| `int uordblks' |
| This is the total size of memory occupied by chunks handed |
| out by `malloc'. |
| |
| `int fordblks' |
| This is the total size of memory occupied by free (not in |
| use) chunks. |
| |
| `int keepcost' |
| This is the size of the top-most releasable chunk that |
| normally borders the end of the heap (i.e., the high end of |
| the virtual address space's data segment). |
| |
| |
| -- Function: struct mallinfo mallinfo (void) |
| Preliminary: | MT-Unsafe init const:mallopt | AS-Unsafe init lock |
| | AC-Unsafe init lock | *Note POSIX Safety Concepts::. |
| |
| This function returns information about the current dynamic memory |
| usage in a structure of type `struct mallinfo'. |
| |
| |
| File: libc.info, Node: Summary of Malloc, Prev: Statistics of Malloc, Up: Unconstrained Allocation |
| |
| 3.2.2.12 Summary of `malloc'-Related Functions |
| .............................................. |
| |
| Here is a summary of the functions that work with `malloc': |
| |
| `void *malloc (size_t SIZE)' |
| Allocate a block of SIZE bytes. *Note Basic Allocation::. |
| |
| `void free (void *ADDR)' |
| Free a block previously allocated by `malloc'. *Note Freeing |
| after Malloc::. |
| |
| `void *realloc (void *ADDR, size_t SIZE)' |
| Make a block previously allocated by `malloc' larger or smaller, |
| possibly by copying it to a new location. *Note Changing Block |
| Size::. |
| |
| `void *calloc (size_t COUNT, size_t ELTSIZE)' |
| Allocate a block of COUNT * ELTSIZE bytes using `malloc', and set |
| its contents to zero. *Note Allocating Cleared Space::. |
| |
| `void *valloc (size_t SIZE)' |
| Allocate a block of SIZE bytes, starting on a page boundary. |
| *Note Aligned Memory Blocks::. |
| |
| `void *aligned_alloc (size_t SIZE, size_t ALIGNMENT)' |
| Allocate a block of SIZE bytes, starting on an address that is a |
| multiple of ALIGNMENT. *Note Aligned Memory Blocks::. |
| |
| `int posix_memalign (void **MEMPTR, size_t ALIGNMENT, size_t SIZE)' |
| Allocate a block of SIZE bytes, starting on an address that is a |
| multiple of ALIGNMENT. *Note Aligned Memory Blocks::. |
| |
| `void *memalign (size_t SIZE, size_t BOUNDARY)' |
| Allocate a block of SIZE bytes, starting on an address that is a |
| multiple of BOUNDARY. *Note Aligned Memory Blocks::. |
| |
| `int mallopt (int PARAM, int VALUE)' |
| Adjust a tunable parameter. *Note Malloc Tunable Parameters::. |
| |
| `int mcheck (void (*ABORTFN) (void))' |
| Tell `malloc' to perform occasional consistency checks on |
| dynamically allocated memory, and to call ABORTFN when an |
| inconsistency is found. *Note Heap Consistency Checking::. |
| |
| `void *(*__malloc_hook) (size_t SIZE, const void *CALLER)' |
| A pointer to a function that `malloc' uses whenever it is called. |
| |
| `void *(*__realloc_hook) (void *PTR, size_t SIZE, const void *CALLER)' |
| A pointer to a function that `realloc' uses whenever it is called. |
| |
| `void (*__free_hook) (void *PTR, const void *CALLER)' |
| A pointer to a function that `free' uses whenever it is called. |
| |
| `void (*__memalign_hook) (size_t SIZE, size_t ALIGNMENT, const void *CALLER)' |
| A pointer to a function that `aligned_alloc', `memalign', |
| `posix_memalign' and `valloc' use whenever they are called. |
| |
| `struct mallinfo mallinfo (void)' |
| Return information about the current dynamic memory usage. *Note |
| Statistics of Malloc::. |
| |
| |
| File: libc.info, Node: Allocation Debugging, Next: Obstacks, Prev: Unconstrained Allocation, Up: Memory Allocation |
| |
| 3.2.3 Allocation Debugging |
| -------------------------- |
| |
| A complicated task when programming with languages which do not use |
| garbage collected dynamic memory allocation is to find memory leaks. |
| Long running programs must assure that dynamically allocated objects are |
| freed at the end of their lifetime. If this does not happen the system |
| runs out of memory, sooner or later. |
| |
| The `malloc' implementation in the GNU C Library provides some |
| simple means to detect such leaks and obtain some information to find |
| the location. To do this the application must be started in a special |
| mode which is enabled by an environment variable. There are no speed |
| penalties for the program if the debugging mode is not enabled. |
| |
| * Menu: |
| |
| * Tracing malloc:: How to install the tracing functionality. |
| * Using the Memory Debugger:: Example programs excerpts. |
| * Tips for the Memory Debugger:: Some more or less clever ideas. |
| * Interpreting the traces:: What do all these lines mean? |
| |
| |
| File: libc.info, Node: Tracing malloc, Next: Using the Memory Debugger, Up: Allocation Debugging |
| |
| 3.2.3.1 How to install the tracing functionality |
| ................................................ |
| |
| -- Function: void mtrace (void) |
| Preliminary: | MT-Unsafe env race:mtrace const:malloc_hooks init | |
| AS-Unsafe init heap corrupt lock | AC-Unsafe init corrupt lock fd |
| mem | *Note POSIX Safety Concepts::. |
| |
| When the `mtrace' function is called it looks for an environment |
| variable named `MALLOC_TRACE'. This variable is supposed to |
| contain a valid file name. The user must have write access. If |
| the file already exists it is truncated. If the environment |
| variable is not set or it does not name a valid file which can be |
| opened for writing nothing is done. The behavior of `malloc' etc. |
| is not changed. For obvious reasons this also happens if the |
| application is installed with the SUID or SGID bit set. |
| |
| If the named file is successfully opened, `mtrace' installs special |
| handlers for the functions `malloc', `realloc', and `free' (*note |
| Hooks for Malloc::). From then on, all uses of these functions |
| are traced and protocolled into the file. There is now of course |
| a speed penalty for all calls to the traced functions so tracing |
| should not be enabled during normal use. |
| |
| This function is a GNU extension and generally not available on |
| other systems. The prototype can be found in `mcheck.h'. |
| |
| -- Function: void muntrace (void) |
| Preliminary: | MT-Unsafe race:mtrace const:malloc_hooks locale | |
| AS-Unsafe corrupt heap | AC-Unsafe corrupt mem lock fd | *Note |
| POSIX Safety Concepts::. |
| |
| The `muntrace' function can be called after `mtrace' was used to |
| enable tracing the `malloc' calls. If no (successful) call of |
| `mtrace' was made `muntrace' does nothing. |
| |
| Otherwise it deinstalls the handlers for `malloc', `realloc', and |
| `free' and then closes the protocol file. No calls are |
| protocolled anymore and the program runs again at full speed. |
| |
| This function is a GNU extension and generally not available on |
| other systems. The prototype can be found in `mcheck.h'. |
| |
| |
| File: libc.info, Node: Using the Memory Debugger, Next: Tips for the Memory Debugger, Prev: Tracing malloc, Up: Allocation Debugging |
| |
| 3.2.3.2 Example program excerpts |
| ................................ |
| |
| Even though the tracing functionality does not influence the runtime |
| behavior of the program it is not a good idea to call `mtrace' in all |
| programs. Just imagine that you debug a program using `mtrace' and all |
| other programs used in the debugging session also trace their `malloc' |
| calls. The output file would be the same for all programs and thus is |
| unusable. Therefore one should call `mtrace' only if compiled for |
| debugging. A program could therefore start like this: |
| |
| #include <mcheck.h> |
| |
| int |
| main (int argc, char *argv[]) |
| { |
| #ifdef DEBUGGING |
| mtrace (); |
| #endif |
| ... |
| } |
| |
| This is all what is needed if you want to trace the calls during the |
| whole runtime of the program. Alternatively you can stop the tracing at |
| any time with a call to `muntrace'. It is even possible to restart the |
| tracing again with a new call to `mtrace'. But this can cause |
| unreliable results since there may be calls of the functions which are |
| not called. Please note that not only the application uses the traced |
| functions, also libraries (including the C library itself) use these |
| functions. |
| |
| This last point is also why it is no good idea to call `muntrace' |
| before the program terminated. The libraries are informed about the |
| termination of the program only after the program returns from `main' |
| or calls `exit' and so cannot free the memory they use before this time. |
| |
| So the best thing one can do is to call `mtrace' as the very first |
| function in the program and never call `muntrace'. So the program |
| traces almost all uses of the `malloc' functions (except those calls |
| which are executed by constructors of the program or used libraries). |
| |
| |
| File: libc.info, Node: Tips for the Memory Debugger, Next: Interpreting the traces, Prev: Using the Memory Debugger, Up: Allocation Debugging |
| |
| 3.2.3.3 Some more or less clever ideas |
| ...................................... |
| |
| You know the situation. The program is prepared for debugging and in |
| all debugging sessions it runs well. But once it is started without |
| debugging the error shows up. A typical example is a memory leak that |
| becomes visible only when we turn off the debugging. If you foresee |
| such situations you can still win. Simply use something equivalent to |
| the following little program: |
| |
| #include <mcheck.h> |
| #include <signal.h> |
| |
| static void |
| enable (int sig) |
| { |
| mtrace (); |
| signal (SIGUSR1, enable); |
| } |
| |
| static void |
| disable (int sig) |
| { |
| muntrace (); |
| signal (SIGUSR2, disable); |
| } |
| |
| int |
| main (int argc, char *argv[]) |
| { |
| ... |
| |
| signal (SIGUSR1, enable); |
| signal (SIGUSR2, disable); |
| |
| ... |
| } |
| |
| I.e., the user can start the memory debugger any time s/he wants if |
| the program was started with `MALLOC_TRACE' set in the environment. |
| The output will of course not show the allocations which happened before |
| the first signal but if there is a memory leak this will show up |
| nevertheless. |
| |
| |
| File: libc.info, Node: Interpreting the traces, Prev: Tips for the Memory Debugger, Up: Allocation Debugging |
| |
| 3.2.3.4 Interpreting the traces |
| ............................... |
| |
| If you take a look at the output it will look similar to this: |
| |
| = Start |
| [0x8048209] - 0x8064cc8 |
| [0x8048209] - 0x8064ce0 |
| [0x8048209] - 0x8064cf8 |
| [0x80481eb] + 0x8064c48 0x14 |
| [0x80481eb] + 0x8064c60 0x14 |
| [0x80481eb] + 0x8064c78 0x14 |
| [0x80481eb] + 0x8064c90 0x14 |
| = End |
| |
| What this all means is not really important since the trace file is |
| not meant to be read by a human. Therefore no attention is given to |
| readability. Instead there is a program which comes with the GNU C |
| Library which interprets the traces and outputs a summary in an |
| user-friendly way. The program is called `mtrace' (it is in fact a |
| Perl script) and it takes one or two arguments. In any case the name of |
| the file with the trace output must be specified. If an optional |
| argument precedes the name of the trace file this must be the name of |
| the program which generated the trace. |
| |
| drepper$ mtrace tst-mtrace log |
| No memory leaks. |
| |
| In this case the program `tst-mtrace' was run and it produced a |
| trace file `log'. The message printed by `mtrace' shows there are no |
| problems with the code, all allocated memory was freed afterwards. |
| |
| If we call `mtrace' on the example trace given above we would get a |
| different outout: |
| |
| drepper$ mtrace errlog |
| - 0x08064cc8 Free 2 was never alloc'd 0x8048209 |
| - 0x08064ce0 Free 3 was never alloc'd 0x8048209 |
| - 0x08064cf8 Free 4 was never alloc'd 0x8048209 |
| |
| Memory not freed: |
| ----------------- |
| Address Size Caller |
| 0x08064c48 0x14 at 0x80481eb |
| 0x08064c60 0x14 at 0x80481eb |
| 0x08064c78 0x14 at 0x80481eb |
| 0x08064c90 0x14 at 0x80481eb |
| |
| We have called `mtrace' with only one argument and so the script has |
| no chance to find out what is meant with the addresses given in the |
| trace. We can do better: |
| |
| drepper$ mtrace tst errlog |
| - 0x08064cc8 Free 2 was never alloc'd /home/drepper/tst.c:39 |
| - 0x08064ce0 Free 3 was never alloc'd /home/drepper/tst.c:39 |
| - 0x08064cf8 Free 4 was never alloc'd /home/drepper/tst.c:39 |
| |
| Memory not freed: |
| ----------------- |
| Address Size Caller |
| 0x08064c48 0x14 at /home/drepper/tst.c:33 |
| 0x08064c60 0x14 at /home/drepper/tst.c:33 |
| 0x08064c78 0x14 at /home/drepper/tst.c:33 |
| 0x08064c90 0x14 at /home/drepper/tst.c:33 |
| |
| Suddenly the output makes much more sense and the user can see |
| immediately where the function calls causing the trouble can be found. |
| |
| Interpreting this output is not complicated. There are at most two |
| different situations being detected. First, `free' was called for |
| pointers which were never returned by one of the allocation functions. |
| This is usually a very bad problem and what this looks like is shown in |
| the first three lines of the output. Situations like this are quite |
| rare and if they appear they show up very drastically: the program |
| normally crashes. |
| |
| The other situation which is much harder to detect are memory leaks. |
| As you can see in the output the `mtrace' function collects all this |
| information and so can say that the program calls an allocation function |
| from line 33 in the source file `/home/drepper/tst-mtrace.c' four times |
| without freeing this memory before the program terminates. Whether |
| this is a real problem remains to be investigated. |
| |
| |
| File: libc.info, Node: Obstacks, Next: Variable Size Automatic, Prev: Allocation Debugging, Up: Memory Allocation |
| |
| 3.2.4 Obstacks |
| -------------- |
| |
| An "obstack" is a pool of memory containing a stack of objects. You |
| can create any number of separate obstacks, and then allocate objects in |
| specified obstacks. Within each obstack, the last object allocated must |
| always be the first one freed, but distinct obstacks are independent of |
| each other. |
| |
| Aside from this one constraint of order of freeing, obstacks are |
| totally general: an obstack can contain any number of objects of any |
| size. They are implemented with macros, so allocation is usually very |
| fast as long as the objects are usually small. And the only space |
| overhead per object is the padding needed to start each object on a |
| suitable boundary. |
| |
| * Menu: |
| |
| * Creating Obstacks:: How to declare an obstack in your program. |
| * Preparing for Obstacks:: Preparations needed before you can |
| use obstacks. |
| * Allocation in an Obstack:: Allocating objects in an obstack. |
| * Freeing Obstack Objects:: Freeing objects in an obstack. |
| * Obstack Functions:: The obstack functions are both |
| functions and macros. |
| * Growing Objects:: Making an object bigger by stages. |
| * Extra Fast Growing:: Extra-high-efficiency (though more |
| complicated) growing objects. |
| * Status of an Obstack:: Inquiries about the status of an obstack. |
| * Obstacks Data Alignment:: Controlling alignment of objects in obstacks. |
| * Obstack Chunks:: How obstacks obtain and release chunks; |
| efficiency considerations. |
| * Summary of Obstacks:: |
| |
| |
| File: libc.info, Node: Creating Obstacks, Next: Preparing for Obstacks, Up: Obstacks |
| |
| 3.2.4.1 Creating Obstacks |
| ......................... |
| |
| The utilities for manipulating obstacks are declared in the header file |
| `obstack.h'. |
| |
| -- Data Type: struct obstack |
| An obstack is represented by a data structure of type `struct |
| obstack'. This structure has a small fixed size; it records the |
| status of the obstack and how to find the space in which objects |
| are allocated. It does not contain any of the objects themselves. |
| You should not try to access the contents of the structure |
| directly; use only the functions described in this chapter. |
| |
| You can declare variables of type `struct obstack' and use them as |
| obstacks, or you can allocate obstacks dynamically like any other kind |
| of object. Dynamic allocation of obstacks allows your program to have a |
| variable number of different stacks. (You can even allocate an obstack |
| structure in another obstack, but this is rarely useful.) |
| |
| All the functions that work with obstacks require you to specify |
| which obstack to use. You do this with a pointer of type `struct |
| obstack *'. In the following, we often say "an obstack" when strictly |
| speaking the object at hand is such a pointer. |
| |
| The objects in the obstack are packed into large blocks called |
| "chunks". The `struct obstack' structure points to a chain of the |
| chunks currently in use. |
| |
| The obstack library obtains a new chunk whenever you allocate an |
| object that won't fit in the previous chunk. Since the obstack library |
| manages chunks automatically, you don't need to pay much attention to |
| them, but you do need to supply a function which the obstack library |
| should use to get a chunk. Usually you supply a function which uses |
| `malloc' directly or indirectly. You must also supply a function to |
| free a chunk. These matters are described in the following section. |
| |
| |
| File: libc.info, Node: Preparing for Obstacks, Next: Allocation in an Obstack, Prev: Creating Obstacks, Up: Obstacks |
| |
| 3.2.4.2 Preparing for Using Obstacks |
| .................................... |
| |
| Each source file in which you plan to use the obstack functions must |
| include the header file `obstack.h', like this: |
| |
| #include <obstack.h> |
| |
| Also, if the source file uses the macro `obstack_init', it must |
| declare or define two functions or macros that will be called by the |
| obstack library. One, `obstack_chunk_alloc', is used to allocate the |
| chunks of memory into which objects are packed. The other, |
| `obstack_chunk_free', is used to return chunks when the objects in them |
| are freed. These macros should appear before any use of obstacks in |
| the source file. |
| |
| Usually these are defined to use `malloc' via the intermediary |
| `xmalloc' (*note Unconstrained Allocation::). This is done with the |
| following pair of macro definitions: |
| |
| #define obstack_chunk_alloc xmalloc |
| #define obstack_chunk_free free |
| |
| Though the memory you get using obstacks really comes from `malloc', |
| using obstacks is faster because `malloc' is called less often, for |
| larger blocks of memory. *Note Obstack Chunks::, for full details. |
| |
| At run time, before the program can use a `struct obstack' object as |
| an obstack, it must initialize the obstack by calling `obstack_init'. |
| |
| -- Function: int obstack_init (struct obstack *OBSTACK-PTR) |
| Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe mem | |
| *Note POSIX Safety Concepts::. |
| |
| Initialize obstack OBSTACK-PTR for allocation of objects. This |
| function calls the obstack's `obstack_chunk_alloc' function. If |
| allocation of memory fails, the function pointed to by |
| `obstack_alloc_failed_handler' is called. The `obstack_init' |
| function always returns 1 (Compatibility notice: Former versions of |
| obstack returned 0 if allocation failed). |
| |
| Here are two examples of how to allocate the space for an obstack and |
| initialize it. First, an obstack that is a static variable: |
| |
| static struct obstack myobstack; |
| ... |
| obstack_init (&myobstack); |
| |
| Second, an obstack that is itself dynamically allocated: |
| |
| struct obstack *myobstack_ptr |
| = (struct obstack *) xmalloc (sizeof (struct obstack)); |
| |
| obstack_init (myobstack_ptr); |
| |
| -- Variable: obstack_alloc_failed_handler |
| The value of this variable is a pointer to a function that |
| `obstack' uses when `obstack_chunk_alloc' fails to allocate |
| memory. The default action is to print a message and abort. You |
| should supply a function that either calls `exit' (*note Program |
| Termination::) or `longjmp' (*note Non-Local Exits::) and doesn't |
| return. |
| |
| void my_obstack_alloc_failed (void) |
| ... |
| obstack_alloc_failed_handler = &my_obstack_alloc_failed; |
| |
| |
| |
| File: libc.info, Node: Allocation in an Obstack, Next: Freeing Obstack Objects, Prev: Preparing for Obstacks, Up: Obstacks |
| |
| 3.2.4.3 Allocation in an Obstack |
| ................................ |
| |
| The most direct way to allocate an object in an obstack is with |
| `obstack_alloc', which is invoked almost like `malloc'. |
| |
| -- Function: void * obstack_alloc (struct obstack *OBSTACK-PTR, int |
| SIZE) |
| Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe |
| corrupt mem | *Note POSIX Safety Concepts::. |
| |
| This allocates an uninitialized block of SIZE bytes in an obstack |
| and returns its address. Here OBSTACK-PTR specifies which obstack |
| to allocate the block in; it is the address of the `struct obstack' |
| object which represents the obstack. Each obstack function or |
| macro requires you to specify an OBSTACK-PTR as the first argument. |
| |
| This function calls the obstack's `obstack_chunk_alloc' function if |
| it needs to allocate a new chunk of memory; it calls |
| `obstack_alloc_failed_handler' if allocation of memory by |
| `obstack_chunk_alloc' failed. |
| |
| For example, here is a function that allocates a copy of a string STR |
| in a specific obstack, which is in the variable `string_obstack': |
| |
| struct obstack string_obstack; |
| |
| char * |
| copystring (char *string) |
| { |
| size_t len = strlen (string) + 1; |
| char *s = (char *) obstack_alloc (&string_obstack, len); |
| memcpy (s, string, len); |
| return s; |
| } |
| |
| To allocate a block with specified contents, use the function |
| `obstack_copy', declared like this: |
| |
| -- Function: void * obstack_copy (struct obstack *OBSTACK-PTR, void |
| *ADDRESS, int SIZE) |
| Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe |
| corrupt mem | *Note POSIX Safety Concepts::. |
| |
| This allocates a block and initializes it by copying SIZE bytes of |
| data starting at ADDRESS. It calls `obstack_alloc_failed_handler' |
| if allocation of memory by `obstack_chunk_alloc' failed. |
| |
| -- Function: void * obstack_copy0 (struct obstack *OBSTACK-PTR, void |
| *ADDRESS, int SIZE) |
| Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe |
| corrupt mem | *Note POSIX Safety Concepts::. |
| |
| Like `obstack_copy', but appends an extra byte containing a null |
| character. This extra byte is not counted in the argument SIZE. |
| |
| The `obstack_copy0' function is convenient for copying a sequence of |
| characters into an obstack as a null-terminated string. Here is an |
| example of its use: |
| |
| char * |
| obstack_savestring (char *addr, int size) |
| { |
| return obstack_copy0 (&myobstack, addr, size); |
| } |
| |
| Contrast this with the previous example of `savestring' using `malloc' |
| (*note Basic Allocation::). |
| |
| |
| File: libc.info, Node: Freeing Obstack Objects, Next: Obstack Functions, Prev: Allocation in an Obstack, Up: Obstacks |
| |
| 3.2.4.4 Freeing Objects in an Obstack |
| ..................................... |
| |
| To free an object allocated in an obstack, use the function |
| `obstack_free'. Since the obstack is a stack of objects, freeing one |
| object automatically frees all other objects allocated more recently in |
| the same obstack. |
| |
| -- Function: void obstack_free (struct obstack *OBSTACK-PTR, void |
| *OBJECT) |
| Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe |
| corrupt | *Note POSIX Safety Concepts::. |
| |
| If OBJECT is a null pointer, everything allocated in the obstack |
| is freed. Otherwise, OBJECT must be the address of an object |
| allocated in the obstack. Then OBJECT is freed, along with |
| everything allocated in OBSTACK since OBJECT. |
| |
| Note that if OBJECT is a null pointer, the result is an |
| uninitialized obstack. To free all memory in an obstack but leave it |
| valid for further allocation, call `obstack_free' with the address of |
| the first object allocated on the obstack: |
| |
| obstack_free (obstack_ptr, first_object_allocated_ptr); |
| |
| Recall that the objects in an obstack are grouped into chunks. When |
| all the objects in a chunk become free, the obstack library |
| automatically frees the chunk (*note Preparing for Obstacks::). Then |
| other obstacks, or non-obstack allocation, can reuse the space of the |
| chunk. |
| |
| |
| File: libc.info, Node: Obstack Functions, Next: Growing Objects, Prev: Freeing Obstack Objects, Up: Obstacks |
| |
| 3.2.4.5 Obstack Functions and Macros |
| .................................... |
| |
| The interfaces for using obstacks may be defined either as functions or |
| as macros, depending on the compiler. The obstack facility works with |
| all C compilers, including both ISO C and traditional C, but there are |
| precautions you must take if you plan to use compilers other than GNU C. |
| |
| If you are using an old-fashioned non-ISO C compiler, all the obstack |
| "functions" are actually defined only as macros. You can call these |
| macros like functions, but you cannot use them in any other way (for |
| example, you cannot take their address). |
| |
| Calling the macros requires a special precaution: namely, the first |
| operand (the obstack pointer) may not contain any side effects, because |
| it may be computed more than once. For example, if you write this: |
| |
| obstack_alloc (get_obstack (), 4); |
| |
| you will find that `get_obstack' may be called several times. If you |
| use `*obstack_list_ptr++' as the obstack pointer argument, you will get |
| very strange results since the incrementation may occur several times. |
| |
| In ISO C, each function has both a macro definition and a function |
| definition. The function definition is used if you take the address of |
| the function without calling it. An ordinary call uses the macro |
| definition by default, but you can request the function definition |
| instead by writing the function name in parentheses, as shown here: |
| |
| char *x; |
| void *(*funcp) (); |
| /* Use the macro. */ |
| x = (char *) obstack_alloc (obptr, size); |
| /* Call the function. */ |
| x = (char *) (obstack_alloc) (obptr, size); |
| /* Take the address of the function. */ |
| funcp = obstack_alloc; |
| |
| This is the same situation that exists in ISO C for the standard library |
| functions. *Note Macro Definitions::. |
| |
| *Warning:* When you do use the macros, you must observe the |
| precaution of avoiding side effects in the first operand, even in ISO C. |
| |
| If you use the GNU C compiler, this precaution is not necessary, |
| because various language extensions in GNU C permit defining the macros |
| so as to compute each argument only once. |
| |
| |
| File: libc.info, Node: Growing Objects, Next: Extra Fast Growing, Prev: Obstack Functions, Up: Obstacks |
| |
| 3.2.4.6 Growing Objects |
| ....................... |
| |
| Because memory in obstack chunks is used sequentially, it is possible to |
| build up an object step by step, adding one or more bytes at a time to |
| the end of the object. With this technique, you do not need to know |
| how much data you will put in the object until you come to the end of |
| it. We call this the technique of "growing objects". The special |
| functions for adding data to the growing object are described in this |
| section. |
| |
| You don't need to do anything special when you start to grow an |
| object. Using one of the functions to add data to the object |
| automatically starts it. However, it is necessary to say explicitly |
| when the object is finished. This is done with the function |
| `obstack_finish'. |
| |
| The actual address of the object thus built up is not known until the |
| object is finished. Until then, it always remains possible that you |
| will add so much data that the object must be copied into a new chunk. |
| |
| While the obstack is in use for a growing object, you cannot use it |
| for ordinary allocation of another object. If you try to do so, the |
| space already added to the growing object will become part of the other |
| object. |
| |
| -- Function: void obstack_blank (struct obstack *OBSTACK-PTR, int SIZE) |
| Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe |
| corrupt mem | *Note POSIX Safety Concepts::. |
| |
| The most basic function for adding to a growing object is |
| `obstack_blank', which adds space without initializing it. |
| |
| -- Function: void obstack_grow (struct obstack *OBSTACK-PTR, void |
| *DATA, int SIZE) |
| Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe |
| corrupt mem | *Note POSIX Safety Concepts::. |
| |
| To add a block of initialized space, use `obstack_grow', which is |
| the growing-object analogue of `obstack_copy'. It adds SIZE bytes |
| of data to the growing object, copying the contents from DATA. |
| |
| -- Function: void obstack_grow0 (struct obstack *OBSTACK-PTR, void |
| *DATA, int SIZE) |
| Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe |
| corrupt mem | *Note POSIX Safety Concepts::. |
| |
| This is the growing-object analogue of `obstack_copy0'. It adds |
| SIZE bytes copied from DATA, followed by an additional null |
| character. |
| |
| -- Function: void obstack_1grow (struct obstack *OBSTACK-PTR, char C) |
| Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe |
| corrupt mem | *Note POSIX Safety Concepts::. |
| |
| To add one character at a time, use the function `obstack_1grow'. |
| It adds a single byte containing C to the growing object. |
| |
| -- Function: void obstack_ptr_grow (struct obstack *OBSTACK-PTR, void |
| *DATA) |
| Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe |
| corrupt mem | *Note POSIX Safety Concepts::. |
| |
| Adding the value of a pointer one can use the function |
| `obstack_ptr_grow'. It adds `sizeof (void *)' bytes containing |
| the value of DATA. |
| |
| -- Function: void obstack_int_grow (struct obstack *OBSTACK-PTR, int |
| DATA) |
| Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe |
| corrupt mem | *Note POSIX Safety Concepts::. |
| |
| A single value of type `int' can be added by using the |
| `obstack_int_grow' function. It adds `sizeof (int)' bytes to the |
| growing object and initializes them with the value of DATA. |
| |
| -- Function: void * obstack_finish (struct obstack *OBSTACK-PTR) |
| Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe |
| corrupt | *Note POSIX Safety Concepts::. |
| |
| When you are finished growing the object, use the function |
| `obstack_finish' to close it off and return its final address. |
| |
| Once you have finished the object, the obstack is available for |
| ordinary allocation or for growing another object. |
| |
| This function can return a null pointer under the same conditions |
| as `obstack_alloc' (*note Allocation in an Obstack::). |
| |
| When you build an object by growing it, you will probably need to |
| know afterward how long it became. You need not keep track of this as |
| you grow the object, because you can find out the length from the |
| obstack just before finishing the object with the function |
| `obstack_object_size', declared as follows: |
| |
| -- Function: int obstack_object_size (struct obstack *OBSTACK-PTR) |
| Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe | |
| *Note POSIX Safety Concepts::. |
| |
| This function returns the current size of the growing object, in |
| bytes. Remember to call this function _before_ finishing the |
| object. After it is finished, `obstack_object_size' will return |
| zero. |
| |
| If you have started growing an object and wish to cancel it, you |
| should finish it and then free it, like this: |
| |
| obstack_free (obstack_ptr, obstack_finish (obstack_ptr)); |
| |
| This has no effect if no object was growing. |
| |
| You can use `obstack_blank' with a negative size argument to make |
| the current object smaller. Just don't try to shrink it beyond zero |
| length--there's no telling what will happen if you do that. |
| |
| |
| File: libc.info, Node: Extra Fast Growing, Next: Status of an Obstack, Prev: Growing Objects, Up: Obstacks |
| |
| 3.2.4.7 Extra Fast Growing Objects |
| .................................. |
| |
| The usual functions for growing objects incur overhead for checking |
| whether there is room for the new growth in the current chunk. If you |
| are frequently constructing objects in small steps of growth, this |
| overhead can be significant. |
| |
| You can reduce the overhead by using special "fast growth" functions |
| that grow the object without checking. In order to have a robust |
| program, you must do the checking yourself. If you do this checking in |
| the simplest way each time you are about to add data to the object, you |
| have not saved anything, because that is what the ordinary growth |
| functions do. But if you can arrange to check less often, or check |
| more efficiently, then you make the program faster. |
| |
| The function `obstack_room' returns the amount of room available in |
| the current chunk. It is declared as follows: |
| |
| -- Function: int obstack_room (struct obstack *OBSTACK-PTR) |
| Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe | |
| *Note POSIX Safety Concepts::. |
| |
| This returns the number of bytes that can be added safely to the |
| current growing object (or to an object about to be started) in |
| obstack OBSTACK using the fast growth functions. |
| |
| While you know there is room, you can use these fast growth functions |
| for adding data to a growing object: |
| |
| -- Function: void obstack_1grow_fast (struct obstack *OBSTACK-PTR, |
| char C) |
| Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe |
| corrupt mem | *Note POSIX Safety Concepts::. |
| |
| The function `obstack_1grow_fast' adds one byte containing the |
| character C to the growing object in obstack OBSTACK-PTR. |
| |
| -- Function: void obstack_ptr_grow_fast (struct obstack *OBSTACK-PTR, |
| void *DATA) |
| Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe | |
| *Note POSIX Safety Concepts::. |
| |
| The function `obstack_ptr_grow_fast' adds `sizeof (void *)' bytes |
| containing the value of DATA to the growing object in obstack |
| OBSTACK-PTR. |
| |
| -- Function: void obstack_int_grow_fast (struct obstack *OBSTACK-PTR, |
| int DATA) |
| Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe | |
| *Note POSIX Safety Concepts::. |
| |
| The function `obstack_int_grow_fast' adds `sizeof (int)' bytes |
| containing the value of DATA to the growing object in obstack |
| OBSTACK-PTR. |
| |
| -- Function: void obstack_blank_fast (struct obstack *OBSTACK-PTR, int |
| SIZE) |
| Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe | |
| *Note POSIX Safety Concepts::. |
| |
| The function `obstack_blank_fast' adds SIZE bytes to the growing |
| object in obstack OBSTACK-PTR without initializing them. |
| |
| When you check for space using `obstack_room' and there is not |
| enough room for what you want to add, the fast growth functions are not |
| safe. In this case, simply use the corresponding ordinary growth |
| function instead. Very soon this will copy the object to a new chunk; |
| then there will be lots of room available again. |
| |
| So, each time you use an ordinary growth function, check afterward |
| for sufficient space using `obstack_room'. Once the object is copied |
| to a new chunk, there will be plenty of space again, so the program will |
| start using the fast growth functions again. |
| |
| Here is an example: |
| |
| void |
| add_string (struct obstack *obstack, const char *ptr, int len) |
| { |
| while (len > 0) |
| { |
| int room = obstack_room (obstack); |
| if (room == 0) |
| { |
| /* Not enough room. Add one character slowly, |
| which may copy to a new chunk and make room. */ |
| obstack_1grow (obstack, *ptr++); |
| len--; |
| } |
| else |
| { |
| if (room > len) |
| room = len; |
| /* Add fast as much as we have room for. */ |
| len -= room; |
| while (room-- > 0) |
| obstack_1grow_fast (obstack, *ptr++); |
| } |
| } |
| } |
| |
| |
| File: libc.info, Node: Status of an Obstack, Next: Obstacks Data Alignment, Prev: Extra Fast Growing, Up: Obstacks |
| |
| 3.2.4.8 Status of an Obstack |
| ............................ |
| |
| Here are functions that provide information on the current status of |
| allocation in an obstack. You can use them to learn about an object |
| while still growing it. |
| |
| -- Function: void * obstack_base (struct obstack *OBSTACK-PTR) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| This function returns the tentative address of the beginning of the |
| currently growing object in OBSTACK-PTR. If you finish the object |
| immediately, it will have that address. If you make it larger |
| first, it may outgrow the current chunk--then its address will |
| change! |
| |
| If no object is growing, this value says where the next object you |
| allocate will start (once again assuming it fits in the current |
| chunk). |
| |
| -- Function: void * obstack_next_free (struct obstack *OBSTACK-PTR) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| This function returns the address of the first free byte in the |
| current chunk of obstack OBSTACK-PTR. This is the end of the |
| currently growing object. If no object is growing, |
| `obstack_next_free' returns the same value as `obstack_base'. |
| |
| -- Function: int obstack_object_size (struct obstack *OBSTACK-PTR) |
| Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe | |
| *Note POSIX Safety Concepts::. |
| |
| This function returns the size in bytes of the currently growing |
| object. This is equivalent to |
| |
| obstack_next_free (OBSTACK-PTR) - obstack_base (OBSTACK-PTR) |
| |
| |
| File: libc.info, Node: Obstacks Data Alignment, Next: Obstack Chunks, Prev: Status of an Obstack, Up: Obstacks |
| |
| 3.2.4.9 Alignment of Data in Obstacks |
| ..................................... |
| |
| Each obstack has an "alignment boundary"; each object allocated in the |
| obstack automatically starts on an address that is a multiple of the |
| specified boundary. By default, this boundary is aligned so that the |
| object can hold any type of data. |
| |
| To access an obstack's alignment boundary, use the macro |
| `obstack_alignment_mask', whose function prototype looks like this: |
| |
| -- Macro: int obstack_alignment_mask (struct obstack *OBSTACK-PTR) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The value is a bit mask; a bit that is 1 indicates that the |
| corresponding bit in the address of an object should be 0. The |
| mask value should be one less than a power of 2; the effect is |
| that all object addresses are multiples of that power of 2. The |
| default value of the mask is a value that allows aligned objects |
| to hold any type of data: for example, if its value is 3, any type |
| of data can be stored at locations whose addresses are multiples |
| of 4. A mask value of 0 means an object can start on any multiple |
| of 1 (that is, no alignment is required). |
| |
| The expansion of the macro `obstack_alignment_mask' is an lvalue, |
| so you can alter the mask by assignment. For example, this |
| statement: |
| |
| obstack_alignment_mask (obstack_ptr) = 0; |
| |
| has the effect of turning off alignment processing in the |
| specified obstack. |
| |
| Note that a change in alignment mask does not take effect until |
| _after_ the next time an object is allocated or finished in the |
| obstack. If you are not growing an object, you can make the new |
| alignment mask take effect immediately by calling `obstack_finish'. |
| This will finish a zero-length object and then do proper alignment for |
| the next object. |
| |
| |
| File: libc.info, Node: Obstack Chunks, Next: Summary of Obstacks, Prev: Obstacks Data Alignment, Up: Obstacks |
| |
| 3.2.4.10 Obstack Chunks |
| ....................... |
| |
| Obstacks work by allocating space for themselves in large chunks, and |
| then parceling out space in the chunks to satisfy your requests. Chunks |
| are normally 4096 bytes long unless you specify a different chunk size. |
| The chunk size includes 8 bytes of overhead that are not actually used |
| for storing objects. Regardless of the specified size, longer chunks |
| will be allocated when necessary for long objects. |
| |
| The obstack library allocates chunks by calling the function |
| `obstack_chunk_alloc', which you must define. When a chunk is no |
| longer needed because you have freed all the objects in it, the obstack |
| library frees the chunk by calling `obstack_chunk_free', which you must |
| also define. |
| |
| These two must be defined (as macros) or declared (as functions) in |
| each source file that uses `obstack_init' (*note Creating Obstacks::). |
| Most often they are defined as macros like this: |
| |
| #define obstack_chunk_alloc malloc |
| #define obstack_chunk_free free |
| |
| Note that these are simple macros (no arguments). Macro definitions |
| with arguments will not work! It is necessary that |
| `obstack_chunk_alloc' or `obstack_chunk_free', alone, expand into a |
| function name if it is not itself a function name. |
| |
| If you allocate chunks with `malloc', the chunk size should be a |
| power of 2. The default chunk size, 4096, was chosen because it is long |
| enough to satisfy many typical requests on the obstack yet short enough |
| not to waste too much memory in the portion of the last chunk not yet |
| used. |
| |
| -- Macro: int obstack_chunk_size (struct obstack *OBSTACK-PTR) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This returns the chunk size of the given obstack. |
| |
| Since this macro expands to an lvalue, you can specify a new chunk |
| size by assigning it a new value. Doing so does not affect the chunks |
| already allocated, but will change the size of chunks allocated for |
| that particular obstack in the future. It is unlikely to be useful to |
| make the chunk size smaller, but making it larger might improve |
| efficiency if you are allocating many objects whose size is comparable |
| to the chunk size. Here is how to do so cleanly: |
| |
| if (obstack_chunk_size (obstack_ptr) < NEW-CHUNK-SIZE) |
| obstack_chunk_size (obstack_ptr) = NEW-CHUNK-SIZE; |
| |
| |
| File: libc.info, Node: Summary of Obstacks, Prev: Obstack Chunks, Up: Obstacks |
| |
| 3.2.4.11 Summary of Obstack Functions |
| ..................................... |
| |
| Here is a summary of all the functions associated with obstacks. Each |
| takes the address of an obstack (`struct obstack *') as its first |
| argument. |
| |
| `void obstack_init (struct obstack *OBSTACK-PTR)' |
| Initialize use of an obstack. *Note Creating Obstacks::. |
| |
| `void *obstack_alloc (struct obstack *OBSTACK-PTR, int SIZE)' |
| Allocate an object of SIZE uninitialized bytes. *Note Allocation |
| in an Obstack::. |
| |
| `void *obstack_copy (struct obstack *OBSTACK-PTR, void *ADDRESS, int SIZE)' |
| Allocate an object of SIZE bytes, with contents copied from |
| ADDRESS. *Note Allocation in an Obstack::. |
| |
| `void *obstack_copy0 (struct obstack *OBSTACK-PTR, void *ADDRESS, int SIZE)' |
| Allocate an object of SIZE+1 bytes, with SIZE of them copied from |
| ADDRESS, followed by a null character at the end. *Note |
| Allocation in an Obstack::. |
| |
| `void obstack_free (struct obstack *OBSTACK-PTR, void *OBJECT)' |
| Free OBJECT (and everything allocated in the specified obstack |
| more recently than OBJECT). *Note Freeing Obstack Objects::. |
| |
| `void obstack_blank (struct obstack *OBSTACK-PTR, int SIZE)' |
| Add SIZE uninitialized bytes to a growing object. *Note Growing |
| Objects::. |
| |
| `void obstack_grow (struct obstack *OBSTACK-PTR, void *ADDRESS, int SIZE)' |
| Add SIZE bytes, copied from ADDRESS, to a growing object. *Note |
| Growing Objects::. |
| |
| `void obstack_grow0 (struct obstack *OBSTACK-PTR, void *ADDRESS, int SIZE)' |
| Add SIZE bytes, copied from ADDRESS, to a growing object, and then |
| add another byte containing a null character. *Note Growing |
| Objects::. |
| |
| `void obstack_1grow (struct obstack *OBSTACK-PTR, char DATA-CHAR)' |
| Add one byte containing DATA-CHAR to a growing object. *Note |
| Growing Objects::. |
| |
| `void *obstack_finish (struct obstack *OBSTACK-PTR)' |
| Finalize the object that is growing and return its permanent |
| address. *Note Growing Objects::. |
| |
| `int obstack_object_size (struct obstack *OBSTACK-PTR)' |
| Get the current size of the currently growing object. *Note |
| Growing Objects::. |
| |
| `void obstack_blank_fast (struct obstack *OBSTACK-PTR, int SIZE)' |
| Add SIZE uninitialized bytes to a growing object without checking |
| that there is enough room. *Note Extra Fast Growing::. |
| |
| `void obstack_1grow_fast (struct obstack *OBSTACK-PTR, char DATA-CHAR)' |
| Add one byte containing DATA-CHAR to a growing object without |
| checking that there is enough room. *Note Extra Fast Growing::. |
| |
| `int obstack_room (struct obstack *OBSTACK-PTR)' |
| Get the amount of room now available for growing the current |
| object. *Note Extra Fast Growing::. |
| |
| `int obstack_alignment_mask (struct obstack *OBSTACK-PTR)' |
| The mask used for aligning the beginning of an object. This is an |
| lvalue. *Note Obstacks Data Alignment::. |
| |
| `int obstack_chunk_size (struct obstack *OBSTACK-PTR)' |
| The size for allocating chunks. This is an lvalue. *Note Obstack |
| Chunks::. |
| |
| `void *obstack_base (struct obstack *OBSTACK-PTR)' |
| Tentative starting address of the currently growing object. *Note |
| Status of an Obstack::. |
| |
| `void *obstack_next_free (struct obstack *OBSTACK-PTR)' |
| Address just after the end of the currently growing object. *Note |
| Status of an Obstack::. |
| |
| |
| File: libc.info, Node: Variable Size Automatic, Prev: Obstacks, Up: Memory Allocation |
| |
| 3.2.5 Automatic Storage with Variable Size |
| ------------------------------------------ |
| |
| The function `alloca' supports a kind of half-dynamic allocation in |
| which blocks are allocated dynamically but freed automatically. |
| |
| Allocating a block with `alloca' is an explicit action; you can |
| allocate as many blocks as you wish, and compute the size at run time. |
| But all the blocks are freed when you exit the function that `alloca' |
| was called from, just as if they were automatic variables declared in |
| that function. There is no way to free the space explicitly. |
| |
| The prototype for `alloca' is in `stdlib.h'. This function is a BSD |
| extension. |
| |
| -- Function: void * alloca (size_t SIZE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The return value of `alloca' is the address of a block of SIZE |
| bytes of memory, allocated in the stack frame of the calling |
| function. |
| |
| Do not use `alloca' inside the arguments of a function call--you |
| will get unpredictable results, because the stack space for the |
| `alloca' would appear on the stack in the middle of the space for the |
| function arguments. An example of what to avoid is `foo (x, alloca |
| (4), y)'. |
| |
| * Menu: |
| |
| * Alloca Example:: Example of using `alloca'. |
| * Advantages of Alloca:: Reasons to use `alloca'. |
| * Disadvantages of Alloca:: Reasons to avoid `alloca'. |
| * GNU C Variable-Size Arrays:: Only in GNU C, here is an alternative |
| method of allocating dynamically and |
| freeing automatically. |
| |
| |
| File: libc.info, Node: Alloca Example, Next: Advantages of Alloca, Up: Variable Size Automatic |
| |
| 3.2.5.1 `alloca' Example |
| ........................ |
| |
| As an example of the use of `alloca', here is a function that opens a |
| file name made from concatenating two argument strings, and returns a |
| file descriptor or minus one signifying failure: |
| |
| int |
| open2 (char *str1, char *str2, int flags, int mode) |
| { |
| char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1); |
| stpcpy (stpcpy (name, str1), str2); |
| return open (name, flags, mode); |
| } |
| |
| Here is how you would get the same results with `malloc' and `free': |
| |
| int |
| open2 (char *str1, char *str2, int flags, int mode) |
| { |
| char *name = (char *) malloc (strlen (str1) + strlen (str2) + 1); |
| int desc; |
| if (name == 0) |
| fatal ("virtual memory exceeded"); |
| stpcpy (stpcpy (name, str1), str2); |
| desc = open (name, flags, mode); |
| free (name); |
| return desc; |
| } |
| |
| As you can see, it is simpler with `alloca'. But `alloca' has |
| other, more important advantages, and some disadvantages. |
| |
| |
| File: libc.info, Node: Advantages of Alloca, Next: Disadvantages of Alloca, Prev: Alloca Example, Up: Variable Size Automatic |
| |
| 3.2.5.2 Advantages of `alloca' |
| .............................. |
| |
| Here are the reasons why `alloca' may be preferable to `malloc': |
| |
| * Using `alloca' wastes very little space and is very fast. (It is |
| open-coded by the GNU C compiler.) |
| |
| * Since `alloca' does not have separate pools for different sizes of |
| block, space used for any size block can be reused for any other |
| size. `alloca' does not cause memory fragmentation. |
| |
| * Nonlocal exits done with `longjmp' (*note Non-Local Exits::) |
| automatically free the space allocated with `alloca' when they exit |
| through the function that called `alloca'. This is the most |
| important reason to use `alloca'. |
| |
| To illustrate this, suppose you have a function |
| `open_or_report_error' which returns a descriptor, like `open', if |
| it succeeds, but does not return to its caller if it fails. If |
| the file cannot be opened, it prints an error message and jumps |
| out to the command level of your program using `longjmp'. Let's |
| change `open2' (*note Alloca Example::) to use this subroutine: |
| |
| int |
| open2 (char *str1, char *str2, int flags, int mode) |
| { |
| char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1); |
| stpcpy (stpcpy (name, str1), str2); |
| return open_or_report_error (name, flags, mode); |
| } |
| |
| Because of the way `alloca' works, the memory it allocates is |
| freed even when an error occurs, with no special effort required. |
| |
| By contrast, the previous definition of `open2' (which uses |
| `malloc' and `free') would develop a memory leak if it were |
| changed in this way. Even if you are willing to make more changes |
| to fix it, there is no easy way to do so. |
| |
| |
| File: libc.info, Node: Disadvantages of Alloca, Next: GNU C Variable-Size Arrays, Prev: Advantages of Alloca, Up: Variable Size Automatic |
| |
| 3.2.5.3 Disadvantages of `alloca' |
| ................................. |
| |
| These are the disadvantages of `alloca' in comparison with `malloc': |
| |
| * If you try to allocate more memory than the machine can provide, |
| you don't get a clean error message. Instead you get a fatal |
| signal like the one you would get from an infinite recursion; |
| probably a segmentation violation (*note Program Error Signals::). |
| |
| * Some non-GNU systems fail to support `alloca', so it is less |
| portable. However, a slower emulation of `alloca' written in C is |
| available for use on systems with this deficiency. |
| |
| |
| File: libc.info, Node: GNU C Variable-Size Arrays, Prev: Disadvantages of Alloca, Up: Variable Size Automatic |
| |
| 3.2.5.4 GNU C Variable-Size Arrays |
| .................................. |
| |
| In GNU C, you can replace most uses of `alloca' with an array of |
| variable size. Here is how `open2' would look then: |
| |
| int open2 (char *str1, char *str2, int flags, int mode) |
| { |
| char name[strlen (str1) + strlen (str2) + 1]; |
| stpcpy (stpcpy (name, str1), str2); |
| return open (name, flags, mode); |
| } |
| |
| But `alloca' is not always equivalent to a variable-sized array, for |
| several reasons: |
| |
| * A variable size array's space is freed at the end of the scope of |
| the name of the array. The space allocated with `alloca' remains |
| until the end of the function. |
| |
| * It is possible to use `alloca' within a loop, allocating an |
| additional block on each iteration. This is impossible with |
| variable-sized arrays. |
| |
| *NB:* If you mix use of `alloca' and variable-sized arrays within |
| one function, exiting a scope in which a variable-sized array was |
| declared frees all blocks allocated with `alloca' during the execution |
| of that scope. |
| |
| |
| File: libc.info, Node: Resizing the Data Segment, Next: Locking Pages, Prev: Memory Allocation, Up: Memory |
| |
| 3.3 Resizing the Data Segment |
| ============================= |
| |
| The symbols in this section are declared in `unistd.h'. |
| |
| You will not normally use the functions in this section, because the |
| functions described in *note Memory Allocation:: are easier to use. |
| Those are interfaces to a GNU C Library memory allocator that uses the |
| functions below itself. The functions below are simple interfaces to |
| system calls. |
| |
| -- Function: int brk (void *ADDR) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `brk' sets the high end of the calling process' data segment to |
| ADDR. |
| |
| The address of the end of a segment is defined to be the address |
| of the last byte in the segment plus 1. |
| |
| The function has no effect if ADDR is lower than the low end of |
| the data segment. (This is considered success, by the way). |
| |
| The function fails if it would cause the data segment to overlap |
| another segment or exceed the process' data storage limit (*note |
| Limits on Resources::). |
| |
| The function is named for a common historical case where data |
| storage and the stack are in the same segment. Data storage |
| allocation grows upward from the bottom of the segment while the |
| stack grows downward toward it from the top of the segment and the |
| curtain between them is called the "break". |
| |
| The return value is zero on success. On failure, the return value |
| is `-1' and `errno' is set accordingly. The following `errno' |
| values are specific to this function: |
| |
| `ENOMEM' |
| The request would cause the data segment to overlap another |
| segment or exceed the process' data storage limit. |
| |
| |
| -- Function: void *sbrk (ptrdiff_t DELTA) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is the same as `brk' except that you specify the new |
| end of the data segment as an offset DELTA from the current end |
| and on success the return value is the address of the resulting |
| end of the data segment instead of zero. |
| |
| This means you can use `sbrk(0)' to find out what the current end |
| of the data segment is. |
| |
| |
| |
| File: libc.info, Node: Locking Pages, Prev: Resizing the Data Segment, Up: Memory |
| |
| 3.4 Locking Pages |
| ================= |
| |
| You can tell the system to associate a particular virtual memory page |
| with a real page frame and keep it that way -- i.e., cause the page to |
| be paged in if it isn't already and mark it so it will never be paged |
| out and consequently will never cause a page fault. This is called |
| "locking" a page. |
| |
| The functions in this chapter lock and unlock the calling process' |
| pages. |
| |
| * Menu: |
| |
| * Why Lock Pages:: Reasons to read this section. |
| * Locked Memory Details:: Everything you need to know locked |
| memory |
| * Page Lock Functions:: Here's how to do it. |
| |
| |
| File: libc.info, Node: Why Lock Pages, Next: Locked Memory Details, Up: Locking Pages |
| |
| 3.4.1 Why Lock Pages |
| -------------------- |
| |
| Because page faults cause paged out pages to be paged in transparently, |
| a process rarely needs to be concerned about locking pages. However, |
| there are two reasons people sometimes are: |
| |
| * Speed. A page fault is transparent only insofar as the process is |
| not sensitive to how long it takes to do a simple memory access. |
| Time-critical processes, especially realtime processes, may not be |
| able to wait or may not be able to tolerate variance in execution |
| speed. |
| |
| A process that needs to lock pages for this reason probably also |
| needs priority among other processes for use of the CPU. *Note |
| Priority::. |
| |
| In some cases, the programmer knows better than the system's demand |
| paging allocator which pages should remain in real memory to |
| optimize system performance. In this case, locking pages can help. |
| |
| * Privacy. If you keep secrets in virtual memory and that virtual |
| memory gets paged out, that increases the chance that the secrets |
| will get out. If a password gets written out to disk swap space, |
| for example, it might still be there long after virtual and real |
| memory have been wiped clean. |
| |
| |
| Be aware that when you lock a page, that's one fewer page frame that |
| can be used to back other virtual memory (by the same or other |
| processes), which can mean more page faults, which means the system |
| runs more slowly. In fact, if you lock enough memory, some programs |
| may not be able to run at all for lack of real memory. |
| |
| |
| File: libc.info, Node: Locked Memory Details, Next: Page Lock Functions, Prev: Why Lock Pages, Up: Locking Pages |
| |
| 3.4.2 Locked Memory Details |
| --------------------------- |
| |
| A memory lock is associated with a virtual page, not a real frame. The |
| paging rule is: If a frame backs at least one locked page, don't page it |
| out. |
| |
| Memory locks do not stack. I.e., you can't lock a particular page |
| twice so that it has to be unlocked twice before it is truly unlocked. |
| It is either locked or it isn't. |
| |
| A memory lock persists until the process that owns the memory |
| explicitly unlocks it. (But process termination and exec cause the |
| virtual memory to cease to exist, which you might say means it isn't |
| locked any more). |
| |
| Memory locks are not inherited by child processes. (But note that |
| on a modern Unix system, immediately after a fork, the parent's and the |
| child's virtual address space are backed by the same real page frames, |
| so the child enjoys the parent's locks). *Note Creating a Process::. |
| |
| Because of its ability to impact other processes, only the superuser |
| can lock a page. Any process can unlock its own page. |
| |
| The system sets limits on the amount of memory a process can have |
| locked and the amount of real memory it can have dedicated to it. |
| *Note Limits on Resources::. |
| |
| In Linux, locked pages aren't as locked as you might think. Two |
| virtual pages that are not shared memory can nonetheless be backed by |
| the same real frame. The kernel does this in the name of efficiency |
| when it knows both virtual pages contain identical data, and does it |
| even if one or both of the virtual pages are locked. |
| |
| But when a process modifies one of those pages, the kernel must get |
| it a separate frame and fill it with the page's data. This is known as |
| a "copy-on-write page fault". It takes a small amount of time and in a |
| pathological case, getting that frame may require I/O. |
| |
| To make sure this doesn't happen to your program, don't just lock the |
| pages. Write to them as well, unless you know you won't write to them |
| ever. And to make sure you have pre-allocated frames for your stack, |
| enter a scope that declares a C automatic variable larger than the |
| maximum stack size you will need, set it to something, then return from |
| its scope. |
| |
| |
| File: libc.info, Node: Page Lock Functions, Prev: Locked Memory Details, Up: Locking Pages |
| |
| 3.4.3 Functions To Lock And Unlock Pages |
| ---------------------------------------- |
| |
| The symbols in this section are declared in `sys/mman.h'. These |
| functions are defined by POSIX.1b, but their availability depends on |
| your kernel. If your kernel doesn't allow these functions, they exist |
| but always fail. They _are_ available with a Linux kernel. |
| |
| *Portability Note:* POSIX.1b requires that when the `mlock' and |
| `munlock' functions are available, the file `unistd.h' define the macro |
| `_POSIX_MEMLOCK_RANGE' and the file `limits.h' define the macro |
| `PAGESIZE' to be the size of a memory page in bytes. It requires that |
| when the `mlockall' and `munlockall' functions are available, the |
| `unistd.h' file define the macro `_POSIX_MEMLOCK'. The GNU C Library |
| conforms to this requirement. |
| |
| -- Function: int mlock (const void *ADDR, size_t LEN) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `mlock' locks a range of the calling process' virtual pages. |
| |
| The range of memory starts at address ADDR and is LEN bytes long. |
| Actually, since you must lock whole pages, it is the range of |
| pages that include any part of the specified range. |
| |
| When the function returns successfully, each of those pages is |
| backed by (connected to) a real frame (is resident) and is marked |
| to stay that way. This means the function may cause page-ins and |
| have to wait for them. |
| |
| When the function fails, it does not affect the lock status of any |
| pages. |
| |
| The return value is zero if the function succeeds. Otherwise, it |
| is `-1' and `errno' is set accordingly. `errno' values specific |
| to this function are: |
| |
| `ENOMEM' |
| * At least some of the specified address range does not |
| exist in the calling process' virtual address space. |
| |
| * The locking would cause the process to exceed its locked |
| page limit. |
| |
| `EPERM' |
| The calling process is not superuser. |
| |
| `EINVAL' |
| LEN is not positive. |
| |
| `ENOSYS' |
| The kernel does not provide `mlock' capability. |
| |
| |
| You can lock _all_ a process' memory with `mlockall'. You unlock |
| memory with `munlock' or `munlockall'. |
| |
| To avoid all page faults in a C program, you have to use |
| `mlockall', because some of the memory a program uses is hidden |
| from the C code, e.g. the stack and automatic variables, and you |
| wouldn't know what address to tell `mlock'. |
| |
| |
| -- Function: int munlock (const void *ADDR, size_t LEN) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `munlock' unlocks a range of the calling process' virtual pages. |
| |
| `munlock' is the inverse of `mlock' and functions completely |
| analogously to `mlock', except that there is no `EPERM' failure. |
| |
| |
| -- Function: int mlockall (int FLAGS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `mlockall' locks all the pages in a process' virtual memory address |
| space, and/or any that are added to it in the future. This |
| includes the pages of the code, data and stack segment, as well as |
| shared libraries, user space kernel data, shared memory, and |
| memory mapped files. |
| |
| FLAGS is a string of single bit flags represented by the following |
| macros. They tell `mlockall' which of its functions you want. All |
| other bits must be zero. |
| |
| `MCL_CURRENT' |
| Lock all pages which currently exist in the calling process' |
| virtual address space. |
| |
| `MCL_FUTURE' |
| Set a mode such that any pages added to the process' virtual |
| address space in the future will be locked from birth. This |
| mode does not affect future address spaces owned by the same |
| process so exec, which replaces a process' address space, |
| wipes out `MCL_FUTURE'. *Note Executing a File::. |
| |
| |
| When the function returns successfully, and you specified |
| `MCL_CURRENT', all of the process' pages are backed by (connected |
| to) real frames (they are resident) and are marked to stay that |
| way. This means the function may cause page-ins and have to wait |
| for them. |
| |
| When the process is in `MCL_FUTURE' mode because it successfully |
| executed this function and specified `MCL_CURRENT', any system call |
| by the process that requires space be added to its virtual address |
| space fails with `errno' = `ENOMEM' if locking the additional space |
| would cause the process to exceed its locked page limit. In the |
| case that the address space addition that can't be accommodated is |
| stack expansion, the stack expansion fails and the kernel sends a |
| `SIGSEGV' signal to the process. |
| |
| When the function fails, it does not affect the lock status of any |
| pages or the future locking mode. |
| |
| The return value is zero if the function succeeds. Otherwise, it |
| is `-1' and `errno' is set accordingly. `errno' values specific |
| to this function are: |
| |
| `ENOMEM' |
| * At least some of the specified address range does not |
| exist in the calling process' virtual address space. |
| |
| * The locking would cause the process to exceed its locked |
| page limit. |
| |
| `EPERM' |
| The calling process is not superuser. |
| |
| `EINVAL' |
| Undefined bits in FLAGS are not zero. |
| |
| `ENOSYS' |
| The kernel does not provide `mlockall' capability. |
| |
| |
| You can lock just specific pages with `mlock'. You unlock pages |
| with `munlockall' and `munlock'. |
| |
| |
| -- Function: int munlockall (void) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `munlockall' unlocks every page in the calling process' virtual |
| address space and turn off `MCL_FUTURE' future locking mode. |
| |
| The return value is zero if the function succeeds. Otherwise, it |
| is `-1' and `errno' is set accordingly. The only way this |
| function can fail is for generic reasons that all functions and |
| system calls can fail, so there are no specific `errno' values. |
| |
| |
| |
| File: libc.info, Node: Character Handling, Next: String and Array Utilities, Prev: Memory, Up: Top |
| |
| 4 Character Handling |
| ******************** |
| |
| Programs that work with characters and strings often need to classify a |
| character--is it alphabetic, is it a digit, is it whitespace, and so |
| on--and perform case conversion operations on characters. The |
| functions in the header file `ctype.h' are provided for this purpose. |
| |
| Since the choice of locale and character set can alter the |
| classifications of particular character codes, all of these functions |
| are affected by the current locale. (More precisely, they are affected |
| by the locale currently selected for character classification--the |
| `LC_CTYPE' category; see *note Locale Categories::.) |
| |
| The ISO C standard specifies two different sets of functions. The |
| one set works on `char' type characters, the other one on `wchar_t' |
| wide characters (*note Extended Char Intro::). |
| |
| * Menu: |
| |
| * Classification of Characters:: Testing whether characters are |
| letters, digits, punctuation, etc. |
| |
| * Case Conversion:: Case mapping, and the like. |
| * Classification of Wide Characters:: Character class determination for |
| wide characters. |
| * Using Wide Char Classes:: Notes on using the wide character |
| classes. |
| * Wide Character Case Conversion:: Mapping of wide characters. |
| |
| |
| File: libc.info, Node: Classification of Characters, Next: Case Conversion, Up: Character Handling |
| |
| 4.1 Classification of Characters |
| ================================ |
| |
| This section explains the library functions for classifying characters. |
| For example, `isalpha' is the function to test for an alphabetic |
| character. It takes one argument, the character to test, and returns a |
| nonzero integer if the character is alphabetic, and zero otherwise. You |
| would use it like this: |
| |
| if (isalpha (c)) |
| printf ("The character `%c' is alphabetic.\n", c); |
| |
| Each of the functions in this section tests for membership in a |
| particular class of characters; each has a name starting with `is'. |
| Each of them takes one argument, which is a character to test, and |
| returns an `int' which is treated as a boolean value. The character |
| argument is passed as an `int', and it may be the constant value `EOF' |
| instead of a real character. |
| |
| The attributes of any given character can vary between locales. |
| *Note Locales::, for more information on locales. |
| |
| These functions are declared in the header file `ctype.h'. |
| |
| -- Function: int islower (int C) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Returns true if C is a lower-case letter. The letter need not be |
| from the Latin alphabet, any alphabet representable is valid. |
| |
| -- Function: int isupper (int C) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Returns true if C is an upper-case letter. The letter need not be |
| from the Latin alphabet, any alphabet representable is valid. |
| |
| -- Function: int isalpha (int C) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Returns true if C is an alphabetic character (a letter). If |
| `islower' or `isupper' is true of a character, then `isalpha' is |
| also true. |
| |
| In some locales, there may be additional characters for which |
| `isalpha' is true--letters which are neither upper case nor lower |
| case. But in the standard `"C"' locale, there are no such |
| additional characters. |
| |
| -- Function: int isdigit (int C) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Returns true if C is a decimal digit (`0' through `9'). |
| |
| -- Function: int isalnum (int C) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Returns true if C is an alphanumeric character (a letter or |
| number); in other words, if either `isalpha' or `isdigit' is true |
| of a character, then `isalnum' is also true. |
| |
| -- Function: int isxdigit (int C) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Returns true if C is a hexadecimal digit. Hexadecimal digits |
| include the normal decimal digits `0' through `9' and the letters |
| `A' through `F' and `a' through `f'. |
| |
| -- Function: int ispunct (int C) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Returns true if C is a punctuation character. This means any |
| printing character that is not alphanumeric or a space character. |
| |
| -- Function: int isspace (int C) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Returns true if C is a "whitespace" character. In the standard |
| `"C"' locale, `isspace' returns true for only the standard |
| whitespace characters: |
| |
| `' '' |
| space |
| |
| `'\f'' |
| formfeed |
| |
| `'\n'' |
| newline |
| |
| `'\r'' |
| carriage return |
| |
| `'\t'' |
| horizontal tab |
| |
| `'\v'' |
| vertical tab |
| |
| -- Function: int isblank (int C) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Returns true if C is a blank character; that is, a space or a tab. |
| This function was originally a GNU extension, but was added in |
| ISO C99. |
| |
| -- Function: int isgraph (int C) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Returns true if C is a graphic character; that is, a character |
| that has a glyph associated with it. The whitespace characters |
| are not considered graphic. |
| |
| -- Function: int isprint (int C) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Returns true if C is a printing character. Printing characters |
| include all the graphic characters, plus the space (` ') character. |
| |
| -- Function: int iscntrl (int C) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Returns true if C is a control character (that is, a character that |
| is not a printing character). |
| |
| -- Function: int isascii (int C) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Returns true if C is a 7-bit `unsigned char' value that fits into |
| the US/UK ASCII character set. This function is a BSD extension |
| and is also an SVID extension. |
| |
| |
| File: libc.info, Node: Case Conversion, Next: Classification of Wide Characters, Prev: Classification of Characters, Up: Character Handling |
| |
| 4.2 Case Conversion |
| =================== |
| |
| This section explains the library functions for performing conversions |
| such as case mappings on characters. For example, `toupper' converts |
| any character to upper case if possible. If the character can't be |
| converted, `toupper' returns it unchanged. |
| |
| These functions take one argument of type `int', which is the |
| character to convert, and return the converted character as an `int'. |
| If the conversion is not applicable to the argument given, the argument |
| is returned unchanged. |
| |
| *Compatibility Note:* In pre-ISO C dialects, instead of returning |
| the argument unchanged, these functions may fail when the argument is |
| not suitable for the conversion. Thus for portability, you may need to |
| write `islower(c) ? toupper(c) : c' rather than just `toupper(c)'. |
| |
| These functions are declared in the header file `ctype.h'. |
| |
| -- Function: int tolower (int C) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| If C is an upper-case letter, `tolower' returns the corresponding |
| lower-case letter. If C is not an upper-case letter, C is |
| returned unchanged. |
| |
| -- Function: int toupper (int C) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| If C is a lower-case letter, `toupper' returns the corresponding |
| upper-case letter. Otherwise C is returned unchanged. |
| |
| -- Function: int toascii (int C) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function converts C to a 7-bit `unsigned char' value that |
| fits into the US/UK ASCII character set, by clearing the high-order |
| bits. This function is a BSD extension and is also an SVID |
| extension. |
| |
| -- Function: int _tolower (int C) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This is identical to `tolower', and is provided for compatibility |
| with the SVID. *Note SVID::. |
| |
| -- Function: int _toupper (int C) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This is identical to `toupper', and is provided for compatibility |
| with the SVID. |
| |
| |
| File: libc.info, Node: Classification of Wide Characters, Next: Using Wide Char Classes, Prev: Case Conversion, Up: Character Handling |
| |
| 4.3 Character class determination for wide characters |
| ===================================================== |
| |
| Amendment 1 to ISO C90 defines functions to classify wide characters. |
| Although the original ISO C90 standard already defined the type |
| `wchar_t', no functions operating on them were defined. |
| |
| The general design of the classification functions for wide |
| characters is more general. It allows extensions to the set of |
| available classifications, beyond those which are always available. |
| The POSIX standard specifies how extensions can be made, and this is |
| already implemented in the GNU C Library implementation of the |
| `localedef' program. |
| |
| The character class functions are normally implemented with bitsets, |
| with a bitset per character. For a given character, the appropriate |
| bitset is read from a table and a test is performed as to whether a |
| certain bit is set. Which bit is tested for is determined by the class. |
| |
| For the wide character classification functions this is made visible. |
| There is a type classification type defined, a function to retrieve this |
| value for a given class, and a function to test whether a given |
| character is in this class, using the classification value. On top of |
| this the normal character classification functions as used for `char' |
| objects can be defined. |
| |
| -- Data type: wctype_t |
| The `wctype_t' can hold a value which represents a character class. |
| The only defined way to generate such a value is by using the |
| `wctype' function. |
| |
| This type is defined in `wctype.h'. |
| |
| -- Function: wctype_t wctype (const char *PROPERTY) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The `wctype' returns a value representing a class of wide |
| characters which is identified by the string PROPERTY. Beside |
| some standard properties each locale can define its own ones. In |
| case no property with the given name is known for the current |
| locale selected for the `LC_CTYPE' category, the function returns |
| zero. |
| |
| The properties known in every locale are: |
| |
| `"alnum"' `"alpha"' `"cntrl"' `"digit"' |
| `"graph"' `"lower"' `"print"' `"punct"' |
| `"space"' `"upper"' `"xdigit"' |
| |
| This function is declared in `wctype.h'. |
| |
| To test the membership of a character to one of the non-standard |
| classes the ISO C standard defines a completely new function. |
| |
| -- Function: int iswctype (wint_t WC, wctype_t DESC) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function returns a nonzero value if WC is in the character |
| class specified by DESC. DESC must previously be returned by a |
| successful call to `wctype'. |
| |
| This function is declared in `wctype.h'. |
| |
| To make it easier to use the commonly-used classification functions, |
| they are defined in the C library. There is no need to use `wctype' if |
| the property string is one of the known character classes. In some |
| situations it is desirable to construct the property strings, and then |
| it is important that `wctype' can also handle the standard classes. |
| |
| -- Function: int iswalnum (wint_t WC) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| This function returns a nonzero value if WC is an alphanumeric |
| character (a letter or number); in other words, if either |
| `iswalpha' or `iswdigit' is true of a character, then `iswalnum' |
| is also true. |
| |
| This function can be implemented using |
| |
| iswctype (wc, wctype ("alnum")) |
| |
| It is declared in `wctype.h'. |
| |
| -- Function: int iswalpha (wint_t WC) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| Returns true if WC is an alphabetic character (a letter). If |
| `iswlower' or `iswupper' is true of a character, then `iswalpha' |
| is also true. |
| |
| In some locales, there may be additional characters for which |
| `iswalpha' is true--letters which are neither upper case nor lower |
| case. But in the standard `"C"' locale, there are no such |
| additional characters. |
| |
| This function can be implemented using |
| |
| iswctype (wc, wctype ("alpha")) |
| |
| It is declared in `wctype.h'. |
| |
| -- Function: int iswcntrl (wint_t WC) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| Returns true if WC is a control character (that is, a character |
| that is not a printing character). |
| |
| This function can be implemented using |
| |
| iswctype (wc, wctype ("cntrl")) |
| |
| It is declared in `wctype.h'. |
| |
| -- Function: int iswdigit (wint_t WC) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| Returns true if WC is a digit (e.g., `0' through `9'). Please |
| note that this function does not only return a nonzero value for |
| _decimal_ digits, but for all kinds of digits. A consequence is |
| that code like the following will *not* work unconditionally for |
| wide characters: |
| |
| n = 0; |
| while (iswdigit (*wc)) |
| { |
| n *= 10; |
| n += *wc++ - L'0'; |
| } |
| |
| This function can be implemented using |
| |
| iswctype (wc, wctype ("digit")) |
| |
| It is declared in `wctype.h'. |
| |
| -- Function: int iswgraph (wint_t WC) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| Returns true if WC is a graphic character; that is, a character |
| that has a glyph associated with it. The whitespace characters |
| are not considered graphic. |
| |
| This function can be implemented using |
| |
| iswctype (wc, wctype ("graph")) |
| |
| It is declared in `wctype.h'. |
| |
| -- Function: int iswlower (wint_t WC) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| Returns true if WC is a lower-case letter. The letter need not be |
| from the Latin alphabet, any alphabet representable is valid. |
| |
| This function can be implemented using |
| |
| iswctype (wc, wctype ("lower")) |
| |
| It is declared in `wctype.h'. |
| |
| -- Function: int iswprint (wint_t WC) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| Returns true if WC is a printing character. Printing characters |
| include all the graphic characters, plus the space (` ') character. |
| |
| This function can be implemented using |
| |
| iswctype (wc, wctype ("print")) |
| |
| It is declared in `wctype.h'. |
| |
| -- Function: int iswpunct (wint_t WC) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| Returns true if WC is a punctuation character. This means any |
| printing character that is not alphanumeric or a space character. |
| |
| This function can be implemented using |
| |
| iswctype (wc, wctype ("punct")) |
| |
| It is declared in `wctype.h'. |
| |
| -- Function: int iswspace (wint_t WC) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| Returns true if WC is a "whitespace" character. In the standard |
| `"C"' locale, `iswspace' returns true for only the standard |
| whitespace characters: |
| |
| `L' '' |
| space |
| |
| `L'\f'' |
| formfeed |
| |
| `L'\n'' |
| newline |
| |
| `L'\r'' |
| carriage return |
| |
| `L'\t'' |
| horizontal tab |
| |
| `L'\v'' |
| vertical tab |
| |
| This function can be implemented using |
| |
| iswctype (wc, wctype ("space")) |
| |
| It is declared in `wctype.h'. |
| |
| -- Function: int iswupper (wint_t WC) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| Returns true if WC is an upper-case letter. The letter need not be |
| from the Latin alphabet, any alphabet representable is valid. |
| |
| This function can be implemented using |
| |
| iswctype (wc, wctype ("upper")) |
| |
| It is declared in `wctype.h'. |
| |
| -- Function: int iswxdigit (wint_t WC) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| Returns true if WC is a hexadecimal digit. Hexadecimal digits |
| include the normal decimal digits `0' through `9' and the letters |
| `A' through `F' and `a' through `f'. |
| |
| This function can be implemented using |
| |
| iswctype (wc, wctype ("xdigit")) |
| |
| It is declared in `wctype.h'. |
| |
| The GNU C Library also provides a function which is not defined in |
| the ISO C standard but which is available as a version for single byte |
| characters as well. |
| |
| -- Function: int iswblank (wint_t WC) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| Returns true if WC is a blank character; that is, a space or a tab. |
| This function was originally a GNU extension, but was added in |
| ISO C99. It is declared in `wchar.h'. |
| |
| |
| File: libc.info, Node: Using Wide Char Classes, Next: Wide Character Case Conversion, Prev: Classification of Wide Characters, Up: Character Handling |
| |
| 4.4 Notes on using the wide character classes |
| ============================================= |
| |
| The first note is probably not astonishing but still occasionally a |
| cause of problems. The `iswXXX' functions can be implemented using |
| macros and in fact, the GNU C Library does this. They are still |
| available as real functions but when the `wctype.h' header is included |
| the macros will be used. This is the same as the `char' type versions |
| of these functions. |
| |
| The second note covers something new. It can be best illustrated by |
| a (real-world) example. The first piece of code is an excerpt from the |
| original code. It is truncated a bit but the intention should be clear. |
| |
| int |
| is_in_class (int c, const char *class) |
| { |
| if (strcmp (class, "alnum") == 0) |
| return isalnum (c); |
| if (strcmp (class, "alpha") == 0) |
| return isalpha (c); |
| if (strcmp (class, "cntrl") == 0) |
| return iscntrl (c); |
| ... |
| return 0; |
| } |
| |
| Now, with the `wctype' and `iswctype' you can avoid the `if' |
| cascades, but rewriting the code as follows is wrong: |
| |
| int |
| is_in_class (int c, const char *class) |
| { |
| wctype_t desc = wctype (class); |
| return desc ? iswctype ((wint_t) c, desc) : 0; |
| } |
| |
| The problem is that it is not guaranteed that the wide character |
| representation of a single-byte character can be found using casting. |
| In fact, usually this fails miserably. The correct solution to this |
| problem is to write the code as follows: |
| |
| int |
| is_in_class (int c, const char *class) |
| { |
| wctype_t desc = wctype (class); |
| return desc ? iswctype (btowc (c), desc) : 0; |
| } |
| |
| *Note Converting a Character::, for more information on `btowc'. |
| Note that this change probably does not improve the performance of the |
| program a lot since the `wctype' function still has to make the string |
| comparisons. It gets really interesting if the `is_in_class' function |
| is called more than once for the same class name. In this case the |
| variable DESC could be computed once and reused for all the calls. |
| Therefore the above form of the function is probably not the final one. |
| |
