| This is |
| /tmp/dgboter/bbs/rhev-vm2--rhe6x86_64/buildbot/rhe6x86_64--aarch64-none-linux-gnu/build/build-aarch64-none-linux-gnu/obj/glibc/manual/libc.info, |
| produced by makeinfo version 4.13 from libc.texinfo. |
| |
| INFO-DIR-SECTION Software libraries |
| START-INFO-DIR-ENTRY |
| * Libc: (libc). C library. |
| END-INFO-DIR-ENTRY |
| |
| INFO-DIR-SECTION GNU C library functions and macros |
| START-INFO-DIR-ENTRY |
| * ALTWERASE: (libc)Local Modes. |
| * ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions. |
| * ARG_MAX: (libc)General Limits. |
| * BC_BASE_MAX: (libc)Utility Limits. |
| * BC_DIM_MAX: (libc)Utility Limits. |
| * BC_SCALE_MAX: (libc)Utility Limits. |
| * BC_STRING_MAX: (libc)Utility Limits. |
| * BRKINT: (libc)Input Modes. |
| * BUFSIZ: (libc)Controlling Buffering. |
| * CCTS_OFLOW: (libc)Control Modes. |
| * CHAR_BIT: (libc)Width of Type. |
| * CHILD_MAX: (libc)General Limits. |
| * CIGNORE: (libc)Control Modes. |
| * CLK_TCK: (libc)Processor Time. |
| * CLOCAL: (libc)Control Modes. |
| * CLOCKS_PER_SEC: (libc)CPU Time. |
| * COLL_WEIGHTS_MAX: (libc)Utility Limits. |
| * CPU_CLR: (libc)CPU Affinity. |
| * CPU_ISSET: (libc)CPU Affinity. |
| * CPU_SET: (libc)CPU Affinity. |
| * CPU_SETSIZE: (libc)CPU Affinity. |
| * CPU_ZERO: (libc)CPU Affinity. |
| * CREAD: (libc)Control Modes. |
| * CRTS_IFLOW: (libc)Control Modes. |
| * CS5: (libc)Control Modes. |
| * CS6: (libc)Control Modes. |
| * CS7: (libc)Control Modes. |
| * CS8: (libc)Control Modes. |
| * CSIZE: (libc)Control Modes. |
| * CSTOPB: (libc)Control Modes. |
| * DTTOIF: (libc)Directory Entries. |
| * E2BIG: (libc)Error Codes. |
| * EACCES: (libc)Error Codes. |
| * EADDRINUSE: (libc)Error Codes. |
| * EADDRNOTAVAIL: (libc)Error Codes. |
| * EADV: (libc)Error Codes. |
| * EAFNOSUPPORT: (libc)Error Codes. |
| * EAGAIN: (libc)Error Codes. |
| * EALREADY: (libc)Error Codes. |
| * EAUTH: (libc)Error Codes. |
| * EBACKGROUND: (libc)Error Codes. |
| * EBADE: (libc)Error Codes. |
| * EBADF: (libc)Error Codes. |
| * EBADFD: (libc)Error Codes. |
| * EBADMSG: (libc)Error Codes. |
| * EBADR: (libc)Error Codes. |
| * EBADRPC: (libc)Error Codes. |
| * EBADRQC: (libc)Error Codes. |
| * EBADSLT: (libc)Error Codes. |
| * EBFONT: (libc)Error Codes. |
| * EBUSY: (libc)Error Codes. |
| * ECANCELED: (libc)Error Codes. |
| * ECHILD: (libc)Error Codes. |
| * ECHO: (libc)Local Modes. |
| * ECHOCTL: (libc)Local Modes. |
| * ECHOE: (libc)Local Modes. |
| * ECHOK: (libc)Local Modes. |
| * ECHOKE: (libc)Local Modes. |
| * ECHONL: (libc)Local Modes. |
| * ECHOPRT: (libc)Local Modes. |
| * ECHRNG: (libc)Error Codes. |
| * ECOMM: (libc)Error Codes. |
| * ECONNABORTED: (libc)Error Codes. |
| * ECONNREFUSED: (libc)Error Codes. |
| * ECONNRESET: (libc)Error Codes. |
| * ED: (libc)Error Codes. |
| * EDEADLK: (libc)Error Codes. |
| * EDEADLOCK: (libc)Error Codes. |
| * EDESTADDRREQ: (libc)Error Codes. |
| * EDIED: (libc)Error Codes. |
| * EDOM: (libc)Error Codes. |
| * EDOTDOT: (libc)Error Codes. |
| * EDQUOT: (libc)Error Codes. |
| * EEXIST: (libc)Error Codes. |
| * EFAULT: (libc)Error Codes. |
| * EFBIG: (libc)Error Codes. |
| * EFTYPE: (libc)Error Codes. |
| * EGRATUITOUS: (libc)Error Codes. |
| * EGREGIOUS: (libc)Error Codes. |
| * EHOSTDOWN: (libc)Error Codes. |
| * EHOSTUNREACH: (libc)Error Codes. |
| * EHWPOISON: (libc)Error Codes. |
| * EIDRM: (libc)Error Codes. |
| * EIEIO: (libc)Error Codes. |
| * EILSEQ: (libc)Error Codes. |
| * EINPROGRESS: (libc)Error Codes. |
| * EINTR: (libc)Error Codes. |
| * EINVAL: (libc)Error Codes. |
| * EIO: (libc)Error Codes. |
| * EISCONN: (libc)Error Codes. |
| * EISDIR: (libc)Error Codes. |
| * EISNAM: (libc)Error Codes. |
| * EKEYEXPIRED: (libc)Error Codes. |
| * EKEYREJECTED: (libc)Error Codes. |
| * EKEYREVOKED: (libc)Error Codes. |
| * EL2HLT: (libc)Error Codes. |
| * EL2NSYNC: (libc)Error Codes. |
| * EL3HLT: (libc)Error Codes. |
| * EL3RST: (libc)Error Codes. |
| * ELIBACC: (libc)Error Codes. |
| * ELIBBAD: (libc)Error Codes. |
| * ELIBEXEC: (libc)Error Codes. |
| * ELIBMAX: (libc)Error Codes. |
| * ELIBSCN: (libc)Error Codes. |
| * ELNRNG: (libc)Error Codes. |
| * ELOOP: (libc)Error Codes. |
| * EMEDIUMTYPE: (libc)Error Codes. |
| * EMFILE: (libc)Error Codes. |
| * EMLINK: (libc)Error Codes. |
| * EMSGSIZE: (libc)Error Codes. |
| * EMULTIHOP: (libc)Error Codes. |
| * ENAMETOOLONG: (libc)Error Codes. |
| * ENAVAIL: (libc)Error Codes. |
| * ENEEDAUTH: (libc)Error Codes. |
| * ENETDOWN: (libc)Error Codes. |
| * ENETRESET: (libc)Error Codes. |
| * ENETUNREACH: (libc)Error Codes. |
| * ENFILE: (libc)Error Codes. |
| * ENOANO: (libc)Error Codes. |
| * ENOBUFS: (libc)Error Codes. |
| * ENOCSI: (libc)Error Codes. |
| * ENODATA: (libc)Error Codes. |
| * ENODEV: (libc)Error Codes. |
| * ENOENT: (libc)Error Codes. |
| * ENOEXEC: (libc)Error Codes. |
| * ENOKEY: (libc)Error Codes. |
| * ENOLCK: (libc)Error Codes. |
| * ENOLINK: (libc)Error Codes. |
| * ENOMEDIUM: (libc)Error Codes. |
| * ENOMEM: (libc)Error Codes. |
| * ENOMSG: (libc)Error Codes. |
| * ENONET: (libc)Error Codes. |
| * ENOPKG: (libc)Error Codes. |
| * ENOPROTOOPT: (libc)Error Codes. |
| * ENOSPC: (libc)Error Codes. |
| * ENOSR: (libc)Error Codes. |
| * ENOSTR: (libc)Error Codes. |
| * ENOSYS: (libc)Error Codes. |
| * ENOTBLK: (libc)Error Codes. |
| * ENOTCONN: (libc)Error Codes. |
| * ENOTDIR: (libc)Error Codes. |
| * ENOTEMPTY: (libc)Error Codes. |
| * ENOTNAM: (libc)Error Codes. |
| * ENOTRECOVERABLE: (libc)Error Codes. |
| * ENOTSOCK: (libc)Error Codes. |
| * ENOTSUP: (libc)Error Codes. |
| * ENOTTY: (libc)Error Codes. |
| * ENOTUNIQ: (libc)Error Codes. |
| * ENXIO: (libc)Error Codes. |
| * EOF: (libc)EOF and Errors. |
| * EOPNOTSUPP: (libc)Error Codes. |
| * EOVERFLOW: (libc)Error Codes. |
| * EOWNERDEAD: (libc)Error Codes. |
| * EPERM: (libc)Error Codes. |
| * EPFNOSUPPORT: (libc)Error Codes. |
| * EPIPE: (libc)Error Codes. |
| * EPROCLIM: (libc)Error Codes. |
| * EPROCUNAVAIL: (libc)Error Codes. |
| * EPROGMISMATCH: (libc)Error Codes. |
| * EPROGUNAVAIL: (libc)Error Codes. |
| * EPROTO: (libc)Error Codes. |
| * EPROTONOSUPPORT: (libc)Error Codes. |
| * EPROTOTYPE: (libc)Error Codes. |
| * EQUIV_CLASS_MAX: (libc)Utility Limits. |
| * ERANGE: (libc)Error Codes. |
| * EREMCHG: (libc)Error Codes. |
| * EREMOTE: (libc)Error Codes. |
| * EREMOTEIO: (libc)Error Codes. |
| * ERESTART: (libc)Error Codes. |
| * ERFKILL: (libc)Error Codes. |
| * EROFS: (libc)Error Codes. |
| * ERPCMISMATCH: (libc)Error Codes. |
| * ESHUTDOWN: (libc)Error Codes. |
| * ESOCKTNOSUPPORT: (libc)Error Codes. |
| * ESPIPE: (libc)Error Codes. |
| * ESRCH: (libc)Error Codes. |
| * ESRMNT: (libc)Error Codes. |
| * ESTALE: (libc)Error Codes. |
| * ESTRPIPE: (libc)Error Codes. |
| * ETIME: (libc)Error Codes. |
| * ETIMEDOUT: (libc)Error Codes. |
| * ETOOMANYREFS: (libc)Error Codes. |
| * ETXTBSY: (libc)Error Codes. |
| * EUCLEAN: (libc)Error Codes. |
| * EUNATCH: (libc)Error Codes. |
| * EUSERS: (libc)Error Codes. |
| * EWOULDBLOCK: (libc)Error Codes. |
| * EXDEV: (libc)Error Codes. |
| * EXFULL: (libc)Error Codes. |
| * EXIT_FAILURE: (libc)Exit Status. |
| * EXIT_SUCCESS: (libc)Exit Status. |
| * EXPR_NEST_MAX: (libc)Utility Limits. |
| * FD_CLOEXEC: (libc)Descriptor Flags. |
| * FD_CLR: (libc)Waiting for I/O. |
| * FD_ISSET: (libc)Waiting for I/O. |
| * FD_SET: (libc)Waiting for I/O. |
| * FD_SETSIZE: (libc)Waiting for I/O. |
| * FD_ZERO: (libc)Waiting for I/O. |
| * FE_SNANS_ALWAYS_SIGNAL: (libc)Infinity and NaN. |
| * FILENAME_MAX: (libc)Limits for Files. |
| * FLUSHO: (libc)Local Modes. |
| * FOPEN_MAX: (libc)Opening Streams. |
| * FP_ILOGB0: (libc)Exponents and Logarithms. |
| * FP_ILOGBNAN: (libc)Exponents and Logarithms. |
| * FP_LLOGB0: (libc)Exponents and Logarithms. |
| * FP_LLOGBNAN: (libc)Exponents and Logarithms. |
| * F_DUPFD: (libc)Duplicating Descriptors. |
| * F_GETFD: (libc)Descriptor Flags. |
| * F_GETFL: (libc)Getting File Status Flags. |
| * F_GETLK: (libc)File Locks. |
| * F_GETOWN: (libc)Interrupt Input. |
| * F_OFD_GETLK: (libc)Open File Description Locks. |
| * F_OFD_SETLK: (libc)Open File Description Locks. |
| * F_OFD_SETLKW: (libc)Open File Description Locks. |
| * F_OK: (libc)Testing File Access. |
| * F_SETFD: (libc)Descriptor Flags. |
| * F_SETFL: (libc)Getting File Status Flags. |
| * F_SETLK: (libc)File Locks. |
| * F_SETLKW: (libc)File Locks. |
| * F_SETOWN: (libc)Interrupt Input. |
| * HUGE_VAL: (libc)Math Error Reporting. |
| * HUGE_VALF: (libc)Math Error Reporting. |
| * HUGE_VALL: (libc)Math Error Reporting. |
| * HUGE_VAL_FN: (libc)Math Error Reporting. |
| * HUGE_VAL_FNx: (libc)Math Error Reporting. |
| * HUPCL: (libc)Control Modes. |
| * I: (libc)Complex Numbers. |
| * ICANON: (libc)Local Modes. |
| * ICRNL: (libc)Input Modes. |
| * IEXTEN: (libc)Local Modes. |
| * IFNAMSIZ: (libc)Interface Naming. |
| * IFTODT: (libc)Directory Entries. |
| * IGNBRK: (libc)Input Modes. |
| * IGNCR: (libc)Input Modes. |
| * IGNPAR: (libc)Input Modes. |
| * IMAXBEL: (libc)Input Modes. |
| * INADDR_ANY: (libc)Host Address Data Type. |
| * INADDR_BROADCAST: (libc)Host Address Data Type. |
| * INADDR_LOOPBACK: (libc)Host Address Data Type. |
| * INADDR_NONE: (libc)Host Address Data Type. |
| * INFINITY: (libc)Infinity and NaN. |
| * INLCR: (libc)Input Modes. |
| * INPCK: (libc)Input Modes. |
| * IPPORT_RESERVED: (libc)Ports. |
| * IPPORT_USERRESERVED: (libc)Ports. |
| * ISIG: (libc)Local Modes. |
| * ISTRIP: (libc)Input Modes. |
| * IXANY: (libc)Input Modes. |
| * IXOFF: (libc)Input Modes. |
| * IXON: (libc)Input Modes. |
| * LINE_MAX: (libc)Utility Limits. |
| * LINK_MAX: (libc)Limits for Files. |
| * L_ctermid: (libc)Identifying the Terminal. |
| * L_cuserid: (libc)Who Logged In. |
| * L_tmpnam: (libc)Temporary Files. |
| * MAXNAMLEN: (libc)Limits for Files. |
| * MAXSYMLINKS: (libc)Symbolic Links. |
| * MAX_CANON: (libc)Limits for Files. |
| * MAX_INPUT: (libc)Limits for Files. |
| * MB_CUR_MAX: (libc)Selecting the Conversion. |
| * MB_LEN_MAX: (libc)Selecting the Conversion. |
| * MDMBUF: (libc)Control Modes. |
| * MSG_DONTROUTE: (libc)Socket Data Options. |
| * MSG_OOB: (libc)Socket Data Options. |
| * MSG_PEEK: (libc)Socket Data Options. |
| * NAME_MAX: (libc)Limits for Files. |
| * NAN: (libc)Infinity and NaN. |
| * NCCS: (libc)Mode Data Types. |
| * NGROUPS_MAX: (libc)General Limits. |
| * NOFLSH: (libc)Local Modes. |
| * NOKERNINFO: (libc)Local Modes. |
| * NSIG: (libc)Standard Signals. |
| * NULL: (libc)Null Pointer Constant. |
| * ONLCR: (libc)Output Modes. |
| * ONOEOT: (libc)Output Modes. |
| * OPEN_MAX: (libc)General Limits. |
| * OPOST: (libc)Output Modes. |
| * OXTABS: (libc)Output Modes. |
| * O_ACCMODE: (libc)Access Modes. |
| * O_APPEND: (libc)Operating Modes. |
| * O_ASYNC: (libc)Operating Modes. |
| * O_CREAT: (libc)Open-time Flags. |
| * O_DIRECTORY: (libc)Open-time Flags. |
| * O_EXCL: (libc)Open-time Flags. |
| * O_EXEC: (libc)Access Modes. |
| * O_EXLOCK: (libc)Open-time Flags. |
| * O_FSYNC: (libc)Operating Modes. |
| * O_IGNORE_CTTY: (libc)Open-time Flags. |
| * O_NDELAY: (libc)Operating Modes. |
| * O_NOATIME: (libc)Operating Modes. |
| * O_NOCTTY: (libc)Open-time Flags. |
| * O_NOLINK: (libc)Open-time Flags. |
| * O_NONBLOCK: (libc)Open-time Flags. |
| * O_NONBLOCK: (libc)Operating Modes. |
| * O_NOTRANS: (libc)Open-time Flags. |
| * O_RDONLY: (libc)Access Modes. |
| * O_RDWR: (libc)Access Modes. |
| * O_READ: (libc)Access Modes. |
| * O_SHLOCK: (libc)Open-time Flags. |
| * O_SYNC: (libc)Operating Modes. |
| * O_TMPFILE: (libc)Open-time Flags. |
| * O_TRUNC: (libc)Open-time Flags. |
| * O_WRITE: (libc)Access Modes. |
| * O_WRONLY: (libc)Access Modes. |
| * PARENB: (libc)Control Modes. |
| * PARMRK: (libc)Input Modes. |
| * PARODD: (libc)Control Modes. |
| * PATH_MAX: (libc)Limits for Files. |
| * PA_FLAG_MASK: (libc)Parsing a Template String. |
| * PENDIN: (libc)Local Modes. |
| * PF_FILE: (libc)Local Namespace Details. |
| * PF_INET6: (libc)Internet Namespace. |
| * PF_INET: (libc)Internet Namespace. |
| * PF_LOCAL: (libc)Local Namespace Details. |
| * PF_UNIX: (libc)Local Namespace Details. |
| * PIPE_BUF: (libc)Limits for Files. |
| * P_tmpdir: (libc)Temporary Files. |
| * RAND_MAX: (libc)ISO Random. |
| * RE_DUP_MAX: (libc)General Limits. |
| * RLIM_INFINITY: (libc)Limits on Resources. |
| * R_OK: (libc)Testing File Access. |
| * SA_NOCLDSTOP: (libc)Flags for Sigaction. |
| * SA_ONSTACK: (libc)Flags for Sigaction. |
| * SA_RESTART: (libc)Flags for Sigaction. |
| * SEEK_CUR: (libc)File Positioning. |
| * SEEK_END: (libc)File Positioning. |
| * SEEK_SET: (libc)File Positioning. |
| * SIGABRT: (libc)Program Error Signals. |
| * SIGALRM: (libc)Alarm Signals. |
| * SIGBUS: (libc)Program Error Signals. |
| * SIGCHLD: (libc)Job Control Signals. |
| * SIGCLD: (libc)Job Control Signals. |
| * SIGCONT: (libc)Job Control Signals. |
| * SIGEMT: (libc)Program Error Signals. |
| * SIGFPE: (libc)Program Error Signals. |
| * SIGHUP: (libc)Termination Signals. |
| * SIGILL: (libc)Program Error Signals. |
| * SIGINFO: (libc)Miscellaneous Signals. |
| * SIGINT: (libc)Termination Signals. |
| * SIGIO: (libc)Asynchronous I/O Signals. |
| * SIGIOT: (libc)Program Error Signals. |
| * SIGKILL: (libc)Termination Signals. |
| * SIGLOST: (libc)Operation Error Signals. |
| * SIGPIPE: (libc)Operation Error Signals. |
| * SIGPOLL: (libc)Asynchronous I/O Signals. |
| * SIGPROF: (libc)Alarm Signals. |
| * SIGQUIT: (libc)Termination Signals. |
| * SIGSEGV: (libc)Program Error Signals. |
| * SIGSTOP: (libc)Job Control Signals. |
| * SIGSYS: (libc)Program Error Signals. |
| * SIGTERM: (libc)Termination Signals. |
| * SIGTRAP: (libc)Program Error Signals. |
| * SIGTSTP: (libc)Job Control Signals. |
| * SIGTTIN: (libc)Job Control Signals. |
| * SIGTTOU: (libc)Job Control Signals. |
| * SIGURG: (libc)Asynchronous I/O Signals. |
| * SIGUSR1: (libc)Miscellaneous Signals. |
| * SIGUSR2: (libc)Miscellaneous Signals. |
| * SIGVTALRM: (libc)Alarm Signals. |
| * SIGWINCH: (libc)Miscellaneous Signals. |
| * SIGXCPU: (libc)Operation Error Signals. |
| * SIGXFSZ: (libc)Operation Error Signals. |
| * SIG_ERR: (libc)Basic Signal Handling. |
| * SNAN: (libc)Infinity and NaN. |
| * SNANF: (libc)Infinity and NaN. |
| * SNANFN: (libc)Infinity and NaN. |
| * SNANFNx: (libc)Infinity and NaN. |
| * SNANL: (libc)Infinity and NaN. |
| * SOCK_DGRAM: (libc)Communication Styles. |
| * SOCK_RAW: (libc)Communication Styles. |
| * SOCK_RDM: (libc)Communication Styles. |
| * SOCK_SEQPACKET: (libc)Communication Styles. |
| * SOCK_STREAM: (libc)Communication Styles. |
| * SOL_SOCKET: (libc)Socket-Level Options. |
| * SSIZE_MAX: (libc)General Limits. |
| * STREAM_MAX: (libc)General Limits. |
| * SUN_LEN: (libc)Local Namespace Details. |
| * S_IFMT: (libc)Testing File Type. |
| * S_ISBLK: (libc)Testing File Type. |
| * S_ISCHR: (libc)Testing File Type. |
| * S_ISDIR: (libc)Testing File Type. |
| * S_ISFIFO: (libc)Testing File Type. |
| * S_ISLNK: (libc)Testing File Type. |
| * S_ISREG: (libc)Testing File Type. |
| * S_ISSOCK: (libc)Testing File Type. |
| * S_TYPEISMQ: (libc)Testing File Type. |
| * S_TYPEISSEM: (libc)Testing File Type. |
| * S_TYPEISSHM: (libc)Testing File Type. |
| * TMP_MAX: (libc)Temporary Files. |
| * TOSTOP: (libc)Local Modes. |
| * TZNAME_MAX: (libc)General Limits. |
| * VDISCARD: (libc)Other Special. |
| * VDSUSP: (libc)Signal Characters. |
| * VEOF: (libc)Editing Characters. |
| * VEOL2: (libc)Editing Characters. |
| * VEOL: (libc)Editing Characters. |
| * VERASE: (libc)Editing Characters. |
| * VINTR: (libc)Signal Characters. |
| * VKILL: (libc)Editing Characters. |
| * VLNEXT: (libc)Other Special. |
| * VMIN: (libc)Noncanonical Input. |
| * VQUIT: (libc)Signal Characters. |
| * VREPRINT: (libc)Editing Characters. |
| * VSTART: (libc)Start/Stop Characters. |
| * VSTATUS: (libc)Other Special. |
| * VSTOP: (libc)Start/Stop Characters. |
| * VSUSP: (libc)Signal Characters. |
| * VTIME: (libc)Noncanonical Input. |
| * VWERASE: (libc)Editing Characters. |
| * WCHAR_MAX: (libc)Extended Char Intro. |
| * WCHAR_MIN: (libc)Extended Char Intro. |
| * WCOREDUMP: (libc)Process Completion Status. |
| * WEOF: (libc)EOF and Errors. |
| * WEOF: (libc)Extended Char Intro. |
| * WEXITSTATUS: (libc)Process Completion Status. |
| * WIFEXITED: (libc)Process Completion Status. |
| * WIFSIGNALED: (libc)Process Completion Status. |
| * WIFSTOPPED: (libc)Process Completion Status. |
| * WSTOPSIG: (libc)Process Completion Status. |
| * WTERMSIG: (libc)Process Completion Status. |
| * W_OK: (libc)Testing File Access. |
| * X_OK: (libc)Testing File Access. |
| * _Complex_I: (libc)Complex Numbers. |
| * _Exit: (libc)Termination Internals. |
| * _IOFBF: (libc)Controlling Buffering. |
| * _IOLBF: (libc)Controlling Buffering. |
| * _IONBF: (libc)Controlling Buffering. |
| * _Imaginary_I: (libc)Complex Numbers. |
| * _PATH_UTMP: (libc)Manipulating the Database. |
| * _PATH_WTMP: (libc)Manipulating the Database. |
| * _POSIX2_C_DEV: (libc)System Options. |
| * _POSIX2_C_VERSION: (libc)Version Supported. |
| * _POSIX2_FORT_DEV: (libc)System Options. |
| * _POSIX2_FORT_RUN: (libc)System Options. |
| * _POSIX2_LOCALEDEF: (libc)System Options. |
| * _POSIX2_SW_DEV: (libc)System Options. |
| * _POSIX_CHOWN_RESTRICTED: (libc)Options for Files. |
| * _POSIX_JOB_CONTROL: (libc)System Options. |
| * _POSIX_NO_TRUNC: (libc)Options for Files. |
| * _POSIX_SAVED_IDS: (libc)System Options. |
| * _POSIX_VDISABLE: (libc)Options for Files. |
| * _POSIX_VERSION: (libc)Version Supported. |
| * __fbufsize: (libc)Controlling Buffering. |
| * __flbf: (libc)Controlling Buffering. |
| * __fpending: (libc)Controlling Buffering. |
| * __fpurge: (libc)Flushing Buffers. |
| * __freadable: (libc)Opening Streams. |
| * __freading: (libc)Opening Streams. |
| * __fsetlocking: (libc)Streams and Threads. |
| * __fwritable: (libc)Opening Streams. |
| * __fwriting: (libc)Opening Streams. |
| * __gconv_end_fct: (libc)glibc iconv Implementation. |
| * __gconv_fct: (libc)glibc iconv Implementation. |
| * __gconv_init_fct: (libc)glibc iconv Implementation. |
| * __ppc_get_timebase: (libc)PowerPC. |
| * __ppc_get_timebase_freq: (libc)PowerPC. |
| * __ppc_mdoio: (libc)PowerPC. |
| * __ppc_mdoom: (libc)PowerPC. |
| * __ppc_set_ppr_low: (libc)PowerPC. |
| * __ppc_set_ppr_med: (libc)PowerPC. |
| * __ppc_set_ppr_med_high: (libc)PowerPC. |
| * __ppc_set_ppr_med_low: (libc)PowerPC. |
| * __ppc_set_ppr_very_low: (libc)PowerPC. |
| * __ppc_yield: (libc)PowerPC. |
| * __riscv_flush_icache: (libc)RISC-V. |
| * __va_copy: (libc)Argument Macros. |
| * _exit: (libc)Termination Internals. |
| * _flushlbf: (libc)Flushing Buffers. |
| * _tolower: (libc)Case Conversion. |
| * _toupper: (libc)Case Conversion. |
| * a64l: (libc)Encode Binary Data. |
| * abort: (libc)Aborting a Program. |
| * abs: (libc)Absolute Value. |
| * accept: (libc)Accepting Connections. |
| * access: (libc)Testing File Access. |
| * acos: (libc)Inverse Trig Functions. |
| * acosf: (libc)Inverse Trig Functions. |
| * acosfN: (libc)Inverse Trig Functions. |
| * acosfNx: (libc)Inverse Trig Functions. |
| * acosh: (libc)Hyperbolic Functions. |
| * acoshf: (libc)Hyperbolic Functions. |
| * acoshfN: (libc)Hyperbolic Functions. |
| * acoshfNx: (libc)Hyperbolic Functions. |
| * acoshl: (libc)Hyperbolic Functions. |
| * acosl: (libc)Inverse Trig Functions. |
| * addmntent: (libc)mtab. |
| * addseverity: (libc)Adding Severity Classes. |
| * adjtime: (libc)High-Resolution Calendar. |
| * adjtimex: (libc)High-Resolution Calendar. |
| * aio_cancel64: (libc)Cancel AIO Operations. |
| * aio_cancel: (libc)Cancel AIO Operations. |
| * aio_error64: (libc)Status of AIO Operations. |
| * aio_error: (libc)Status of AIO Operations. |
| * aio_fsync64: (libc)Synchronizing AIO Operations. |
| * aio_fsync: (libc)Synchronizing AIO Operations. |
| * aio_init: (libc)Configuration of AIO. |
| * aio_read64: (libc)Asynchronous Reads/Writes. |
| * aio_read: (libc)Asynchronous Reads/Writes. |
| * aio_return64: (libc)Status of AIO Operations. |
| * aio_return: (libc)Status of AIO Operations. |
| * aio_suspend64: (libc)Synchronizing AIO Operations. |
| * aio_suspend: (libc)Synchronizing AIO Operations. |
| * aio_write64: (libc)Asynchronous Reads/Writes. |
| * aio_write: (libc)Asynchronous Reads/Writes. |
| * alarm: (libc)Setting an Alarm. |
| * aligned_alloc: (libc)Aligned Memory Blocks. |
| * alloca: (libc)Variable Size Automatic. |
| * alphasort64: (libc)Scanning Directory Content. |
| * alphasort: (libc)Scanning Directory Content. |
| * argp_error: (libc)Argp Helper Functions. |
| * argp_failure: (libc)Argp Helper Functions. |
| * argp_help: (libc)Argp Help. |
| * argp_parse: (libc)Argp. |
| * argp_state_help: (libc)Argp Helper Functions. |
| * argp_usage: (libc)Argp Helper Functions. |
| * argz_add: (libc)Argz Functions. |
| * argz_add_sep: (libc)Argz Functions. |
| * argz_append: (libc)Argz Functions. |
| * argz_count: (libc)Argz Functions. |
| * argz_create: (libc)Argz Functions. |
| * argz_create_sep: (libc)Argz Functions. |
| * argz_delete: (libc)Argz Functions. |
| * argz_extract: (libc)Argz Functions. |
| * argz_insert: (libc)Argz Functions. |
| * argz_next: (libc)Argz Functions. |
| * argz_replace: (libc)Argz Functions. |
| * argz_stringify: (libc)Argz Functions. |
| * asctime: (libc)Formatting Calendar Time. |
| * asctime_r: (libc)Formatting Calendar Time. |
| * asin: (libc)Inverse Trig Functions. |
| * asinf: (libc)Inverse Trig Functions. |
| * asinfN: (libc)Inverse Trig Functions. |
| * asinfNx: (libc)Inverse Trig Functions. |
| * asinh: (libc)Hyperbolic Functions. |
| * asinhf: (libc)Hyperbolic Functions. |
| * asinhfN: (libc)Hyperbolic Functions. |
| * asinhfNx: (libc)Hyperbolic Functions. |
| * asinhl: (libc)Hyperbolic Functions. |
| * asinl: (libc)Inverse Trig Functions. |
| * asprintf: (libc)Dynamic Output. |
| * assert: (libc)Consistency Checking. |
| * assert_perror: (libc)Consistency Checking. |
| * atan2: (libc)Inverse Trig Functions. |
| * atan2f: (libc)Inverse Trig Functions. |
| * atan2fN: (libc)Inverse Trig Functions. |
| * atan2fNx: (libc)Inverse Trig Functions. |
| * atan2l: (libc)Inverse Trig Functions. |
| * atan: (libc)Inverse Trig Functions. |
| * atanf: (libc)Inverse Trig Functions. |
| * atanfN: (libc)Inverse Trig Functions. |
| * atanfNx: (libc)Inverse Trig Functions. |
| * atanh: (libc)Hyperbolic Functions. |
| * atanhf: (libc)Hyperbolic Functions. |
| * atanhfN: (libc)Hyperbolic Functions. |
| * atanhfNx: (libc)Hyperbolic Functions. |
| * atanhl: (libc)Hyperbolic Functions. |
| * atanl: (libc)Inverse Trig Functions. |
| * atexit: (libc)Cleanups on Exit. |
| * atof: (libc)Parsing of Floats. |
| * atoi: (libc)Parsing of Integers. |
| * atol: (libc)Parsing of Integers. |
| * atoll: (libc)Parsing of Integers. |
| * backtrace: (libc)Backtraces. |
| * backtrace_symbols: (libc)Backtraces. |
| * backtrace_symbols_fd: (libc)Backtraces. |
| * basename: (libc)Finding Tokens in a String. |
| * basename: (libc)Finding Tokens in a String. |
| * bcmp: (libc)String/Array Comparison. |
| * bcopy: (libc)Copying Strings and Arrays. |
| * bind: (libc)Setting Address. |
| * bind_textdomain_codeset: (libc)Charset conversion in gettext. |
| * bindtextdomain: (libc)Locating gettext catalog. |
| * brk: (libc)Resizing the Data Segment. |
| * bsearch: (libc)Array Search Function. |
| * btowc: (libc)Converting a Character. |
| * bzero: (libc)Copying Strings and Arrays. |
| * cabs: (libc)Absolute Value. |
| * cabsf: (libc)Absolute Value. |
| * cabsfN: (libc)Absolute Value. |
| * cabsfNx: (libc)Absolute Value. |
| * cabsl: (libc)Absolute Value. |
| * cacos: (libc)Inverse Trig Functions. |
| * cacosf: (libc)Inverse Trig Functions. |
| * cacosfN: (libc)Inverse Trig Functions. |
| * cacosfNx: (libc)Inverse Trig Functions. |
| * cacosh: (libc)Hyperbolic Functions. |
| * cacoshf: (libc)Hyperbolic Functions. |
| * cacoshfN: (libc)Hyperbolic Functions. |
| * cacoshfNx: (libc)Hyperbolic Functions. |
| * cacoshl: (libc)Hyperbolic Functions. |
| * cacosl: (libc)Inverse Trig Functions. |
| * call_once: (libc)Call Once. |
| * calloc: (libc)Allocating Cleared Space. |
| * canonicalize: (libc)FP Bit Twiddling. |
| * canonicalize_file_name: (libc)Symbolic Links. |
| * canonicalizef: (libc)FP Bit Twiddling. |
| * canonicalizefN: (libc)FP Bit Twiddling. |
| * canonicalizefNx: (libc)FP Bit Twiddling. |
| * canonicalizel: (libc)FP Bit Twiddling. |
| * carg: (libc)Operations on Complex. |
| * cargf: (libc)Operations on Complex. |
| * cargfN: (libc)Operations on Complex. |
| * cargfNx: (libc)Operations on Complex. |
| * cargl: (libc)Operations on Complex. |
| * casin: (libc)Inverse Trig Functions. |
| * casinf: (libc)Inverse Trig Functions. |
| * casinfN: (libc)Inverse Trig Functions. |
| * casinfNx: (libc)Inverse Trig Functions. |
| * casinh: (libc)Hyperbolic Functions. |
| * casinhf: (libc)Hyperbolic Functions. |
| * casinhfN: (libc)Hyperbolic Functions. |
| * casinhfNx: (libc)Hyperbolic Functions. |
| * casinhl: (libc)Hyperbolic Functions. |
| * casinl: (libc)Inverse Trig Functions. |
| * catan: (libc)Inverse Trig Functions. |
| * catanf: (libc)Inverse Trig Functions. |
| * catanfN: (libc)Inverse Trig Functions. |
| * catanfNx: (libc)Inverse Trig Functions. |
| * catanh: (libc)Hyperbolic Functions. |
| * catanhf: (libc)Hyperbolic Functions. |
| * catanhfN: (libc)Hyperbolic Functions. |
| * catanhfNx: (libc)Hyperbolic Functions. |
| * catanhl: (libc)Hyperbolic Functions. |
| * catanl: (libc)Inverse Trig Functions. |
| * catclose: (libc)The catgets Functions. |
| * catgets: (libc)The catgets Functions. |
| * catopen: (libc)The catgets Functions. |
| * cbrt: (libc)Exponents and Logarithms. |
| * cbrtf: (libc)Exponents and Logarithms. |
| * cbrtfN: (libc)Exponents and Logarithms. |
| * cbrtfNx: (libc)Exponents and Logarithms. |
| * cbrtl: (libc)Exponents and Logarithms. |
| * ccos: (libc)Trig Functions. |
| * ccosf: (libc)Trig Functions. |
| * ccosfN: (libc)Trig Functions. |
| * ccosfNx: (libc)Trig Functions. |
| * ccosh: (libc)Hyperbolic Functions. |
| * ccoshf: (libc)Hyperbolic Functions. |
| * ccoshfN: (libc)Hyperbolic Functions. |
| * ccoshfNx: (libc)Hyperbolic Functions. |
| * ccoshl: (libc)Hyperbolic Functions. |
| * ccosl: (libc)Trig Functions. |
| * ceil: (libc)Rounding Functions. |
| * ceilf: (libc)Rounding Functions. |
| * ceilfN: (libc)Rounding Functions. |
| * ceilfNx: (libc)Rounding Functions. |
| * ceill: (libc)Rounding Functions. |
| * cexp: (libc)Exponents and Logarithms. |
| * cexpf: (libc)Exponents and Logarithms. |
| * cexpfN: (libc)Exponents and Logarithms. |
| * cexpfNx: (libc)Exponents and Logarithms. |
| * cexpl: (libc)Exponents and Logarithms. |
| * cfgetispeed: (libc)Line Speed. |
| * cfgetospeed: (libc)Line Speed. |
| * cfmakeraw: (libc)Noncanonical Input. |
| * cfsetispeed: (libc)Line Speed. |
| * cfsetospeed: (libc)Line Speed. |
| * cfsetspeed: (libc)Line Speed. |
| * chdir: (libc)Working Directory. |
| * chmod: (libc)Setting Permissions. |
| * chown: (libc)File Owner. |
| * cimag: (libc)Operations on Complex. |
| * cimagf: (libc)Operations on Complex. |
| * cimagfN: (libc)Operations on Complex. |
| * cimagfNx: (libc)Operations on Complex. |
| * cimagl: (libc)Operations on Complex. |
| * clearenv: (libc)Environment Access. |
| * clearerr: (libc)Error Recovery. |
| * clearerr_unlocked: (libc)Error Recovery. |
| * clock: (libc)CPU Time. |
| * clog10: (libc)Exponents and Logarithms. |
| * clog10f: (libc)Exponents and Logarithms. |
| * clog10fN: (libc)Exponents and Logarithms. |
| * clog10fNx: (libc)Exponents and Logarithms. |
| * clog10l: (libc)Exponents and Logarithms. |
| * clog: (libc)Exponents and Logarithms. |
| * clogf: (libc)Exponents and Logarithms. |
| * clogfN: (libc)Exponents and Logarithms. |
| * clogfNx: (libc)Exponents and Logarithms. |
| * clogl: (libc)Exponents and Logarithms. |
| * close: (libc)Opening and Closing Files. |
| * closedir: (libc)Reading/Closing Directory. |
| * closelog: (libc)closelog. |
| * cnd_broadcast: (libc)ISO C Condition Variables. |
| * cnd_destroy: (libc)ISO C Condition Variables. |
| * cnd_init: (libc)ISO C Condition Variables. |
| * cnd_signal: (libc)ISO C Condition Variables. |
| * cnd_timedwait: (libc)ISO C Condition Variables. |
| * cnd_wait: (libc)ISO C Condition Variables. |
| * confstr: (libc)String Parameters. |
| * conj: (libc)Operations on Complex. |
| * conjf: (libc)Operations on Complex. |
| * conjfN: (libc)Operations on Complex. |
| * conjfNx: (libc)Operations on Complex. |
| * conjl: (libc)Operations on Complex. |
| * connect: (libc)Connecting. |
| * copy_file_range: (libc)Copying File Data. |
| * copysign: (libc)FP Bit Twiddling. |
| * copysignf: (libc)FP Bit Twiddling. |
| * copysignfN: (libc)FP Bit Twiddling. |
| * copysignfNx: (libc)FP Bit Twiddling. |
| * copysignl: (libc)FP Bit Twiddling. |
| * cos: (libc)Trig Functions. |
| * cosf: (libc)Trig Functions. |
| * cosfN: (libc)Trig Functions. |
| * cosfNx: (libc)Trig Functions. |
| * cosh: (libc)Hyperbolic Functions. |
| * coshf: (libc)Hyperbolic Functions. |
| * coshfN: (libc)Hyperbolic Functions. |
| * coshfNx: (libc)Hyperbolic Functions. |
| * coshl: (libc)Hyperbolic Functions. |
| * cosl: (libc)Trig Functions. |
| * cpow: (libc)Exponents and Logarithms. |
| * cpowf: (libc)Exponents and Logarithms. |
| * cpowfN: (libc)Exponents and Logarithms. |
| * cpowfNx: (libc)Exponents and Logarithms. |
| * cpowl: (libc)Exponents and Logarithms. |
| * cproj: (libc)Operations on Complex. |
| * cprojf: (libc)Operations on Complex. |
| * cprojfN: (libc)Operations on Complex. |
| * cprojfNx: (libc)Operations on Complex. |
| * cprojl: (libc)Operations on Complex. |
| * creal: (libc)Operations on Complex. |
| * crealf: (libc)Operations on Complex. |
| * crealfN: (libc)Operations on Complex. |
| * crealfNx: (libc)Operations on Complex. |
| * creall: (libc)Operations on Complex. |
| * creat64: (libc)Opening and Closing Files. |
| * creat: (libc)Opening and Closing Files. |
| * crypt: (libc)Passphrase Storage. |
| * crypt_r: (libc)Passphrase Storage. |
| * csin: (libc)Trig Functions. |
| * csinf: (libc)Trig Functions. |
| * csinfN: (libc)Trig Functions. |
| * csinfNx: (libc)Trig Functions. |
| * csinh: (libc)Hyperbolic Functions. |
| * csinhf: (libc)Hyperbolic Functions. |
| * csinhfN: (libc)Hyperbolic Functions. |
| * csinhfNx: (libc)Hyperbolic Functions. |
| * csinhl: (libc)Hyperbolic Functions. |
| * csinl: (libc)Trig Functions. |
| * csqrt: (libc)Exponents and Logarithms. |
| * csqrtf: (libc)Exponents and Logarithms. |
| * csqrtfN: (libc)Exponents and Logarithms. |
| * csqrtfNx: (libc)Exponents and Logarithms. |
| * csqrtl: (libc)Exponents and Logarithms. |
| * ctan: (libc)Trig Functions. |
| * ctanf: (libc)Trig Functions. |
| * ctanfN: (libc)Trig Functions. |
| * ctanfNx: (libc)Trig Functions. |
| * ctanh: (libc)Hyperbolic Functions. |
| * ctanhf: (libc)Hyperbolic Functions. |
| * ctanhfN: (libc)Hyperbolic Functions. |
| * ctanhfNx: (libc)Hyperbolic Functions. |
| * ctanhl: (libc)Hyperbolic Functions. |
| * ctanl: (libc)Trig Functions. |
| * ctermid: (libc)Identifying the Terminal. |
| * ctime: (libc)Formatting Calendar Time. |
| * ctime_r: (libc)Formatting Calendar Time. |
| * cuserid: (libc)Who Logged In. |
| * daddl: (libc)Misc FP Arithmetic. |
| * dcgettext: (libc)Translation with gettext. |
| * dcngettext: (libc)Advanced gettext functions. |
| * ddivl: (libc)Misc FP Arithmetic. |
| * dgettext: (libc)Translation with gettext. |
| * difftime: (libc)Elapsed Time. |
| * dirfd: (libc)Opening a Directory. |
| * dirname: (libc)Finding Tokens in a String. |
| * div: (libc)Integer Division. |
| * dmull: (libc)Misc FP Arithmetic. |
| * dngettext: (libc)Advanced gettext functions. |
| * drand48: (libc)SVID Random. |
| * drand48_r: (libc)SVID Random. |
| * drem: (libc)Remainder Functions. |
| * dremf: (libc)Remainder Functions. |
| * dreml: (libc)Remainder Functions. |
| * dsubl: (libc)Misc FP Arithmetic. |
| * dup2: (libc)Duplicating Descriptors. |
| * dup: (libc)Duplicating Descriptors. |
| * ecvt: (libc)System V Number Conversion. |
| * ecvt_r: (libc)System V Number Conversion. |
| * endfsent: (libc)fstab. |
| * endgrent: (libc)Scanning All Groups. |
| * endhostent: (libc)Host Names. |
| * endmntent: (libc)mtab. |
| * endnetent: (libc)Networks Database. |
| * endnetgrent: (libc)Lookup Netgroup. |
| * endprotoent: (libc)Protocols Database. |
| * endpwent: (libc)Scanning All Users. |
| * endservent: (libc)Services Database. |
| * endutent: (libc)Manipulating the Database. |
| * endutxent: (libc)XPG Functions. |
| * envz_add: (libc)Envz Functions. |
| * envz_entry: (libc)Envz Functions. |
| * envz_get: (libc)Envz Functions. |
| * envz_merge: (libc)Envz Functions. |
| * envz_remove: (libc)Envz Functions. |
| * envz_strip: (libc)Envz Functions. |
| * erand48: (libc)SVID Random. |
| * erand48_r: (libc)SVID Random. |
| * erf: (libc)Special Functions. |
| * erfc: (libc)Special Functions. |
| * erfcf: (libc)Special Functions. |
| * erfcfN: (libc)Special Functions. |
| * erfcfNx: (libc)Special Functions. |
| * erfcl: (libc)Special Functions. |
| * erff: (libc)Special Functions. |
| * erffN: (libc)Special Functions. |
| * erffNx: (libc)Special Functions. |
| * erfl: (libc)Special Functions. |
| * err: (libc)Error Messages. |
| * errno: (libc)Checking for Errors. |
| * error: (libc)Error Messages. |
| * error_at_line: (libc)Error Messages. |
| * errx: (libc)Error Messages. |
| * execl: (libc)Executing a File. |
| * execle: (libc)Executing a File. |
| * execlp: (libc)Executing a File. |
| * execv: (libc)Executing a File. |
| * execve: (libc)Executing a File. |
| * execvp: (libc)Executing a File. |
| * exit: (libc)Normal Termination. |
| * exp10: (libc)Exponents and Logarithms. |
| * exp10f: (libc)Exponents and Logarithms. |
| * exp10fN: (libc)Exponents and Logarithms. |
| * exp10fNx: (libc)Exponents and Logarithms. |
| * exp10l: (libc)Exponents and Logarithms. |
| * exp2: (libc)Exponents and Logarithms. |
| * exp2f: (libc)Exponents and Logarithms. |
| * exp2fN: (libc)Exponents and Logarithms. |
| * exp2fNx: (libc)Exponents and Logarithms. |
| * exp2l: (libc)Exponents and Logarithms. |
| * exp: (libc)Exponents and Logarithms. |
| * expf: (libc)Exponents and Logarithms. |
| * expfN: (libc)Exponents and Logarithms. |
| * expfNx: (libc)Exponents and Logarithms. |
| * expl: (libc)Exponents and Logarithms. |
| * explicit_bzero: (libc)Erasing Sensitive Data. |
| * expm1: (libc)Exponents and Logarithms. |
| * expm1f: (libc)Exponents and Logarithms. |
| * expm1fN: (libc)Exponents and Logarithms. |
| * expm1fNx: (libc)Exponents and Logarithms. |
| * expm1l: (libc)Exponents and Logarithms. |
| * fMaddfN: (libc)Misc FP Arithmetic. |
| * fMaddfNx: (libc)Misc FP Arithmetic. |
| * fMdivfN: (libc)Misc FP Arithmetic. |
| * fMdivfNx: (libc)Misc FP Arithmetic. |
| * fMmulfN: (libc)Misc FP Arithmetic. |
| * fMmulfNx: (libc)Misc FP Arithmetic. |
| * fMsubfN: (libc)Misc FP Arithmetic. |
| * fMsubfNx: (libc)Misc FP Arithmetic. |
| * fMxaddfN: (libc)Misc FP Arithmetic. |
| * fMxaddfNx: (libc)Misc FP Arithmetic. |
| * fMxdivfN: (libc)Misc FP Arithmetic. |
| * fMxdivfNx: (libc)Misc FP Arithmetic. |
| * fMxmulfN: (libc)Misc FP Arithmetic. |
| * fMxmulfNx: (libc)Misc FP Arithmetic. |
| * fMxsubfN: (libc)Misc FP Arithmetic. |
| * fMxsubfNx: (libc)Misc FP Arithmetic. |
| * fabs: (libc)Absolute Value. |
| * fabsf: (libc)Absolute Value. |
| * fabsfN: (libc)Absolute Value. |
| * fabsfNx: (libc)Absolute Value. |
| * fabsl: (libc)Absolute Value. |
| * fadd: (libc)Misc FP Arithmetic. |
| * faddl: (libc)Misc FP Arithmetic. |
| * fchdir: (libc)Working Directory. |
| * fchmod: (libc)Setting Permissions. |
| * fchown: (libc)File Owner. |
| * fclose: (libc)Closing Streams. |
| * fcloseall: (libc)Closing Streams. |
| * fcntl: (libc)Control Operations. |
| * fcvt: (libc)System V Number Conversion. |
| * fcvt_r: (libc)System V Number Conversion. |
| * fdatasync: (libc)Synchronizing I/O. |
| * fdim: (libc)Misc FP Arithmetic. |
| * fdimf: (libc)Misc FP Arithmetic. |
| * fdimfN: (libc)Misc FP Arithmetic. |
| * fdimfNx: (libc)Misc FP Arithmetic. |
| * fdiml: (libc)Misc FP Arithmetic. |
| * fdiv: (libc)Misc FP Arithmetic. |
| * fdivl: (libc)Misc FP Arithmetic. |
| * fdopen: (libc)Descriptors and Streams. |
| * fdopendir: (libc)Opening a Directory. |
| * feclearexcept: (libc)Status bit operations. |
| * fedisableexcept: (libc)Control Functions. |
| * feenableexcept: (libc)Control Functions. |
| * fegetenv: (libc)Control Functions. |
| * fegetexcept: (libc)Control Functions. |
| * fegetexceptflag: (libc)Status bit operations. |
| * fegetmode: (libc)Control Functions. |
| * fegetround: (libc)Rounding. |
| * feholdexcept: (libc)Control Functions. |
| * feof: (libc)EOF and Errors. |
| * feof_unlocked: (libc)EOF and Errors. |
| * feraiseexcept: (libc)Status bit operations. |
| * ferror: (libc)EOF and Errors. |
| * ferror_unlocked: (libc)EOF and Errors. |
| * fesetenv: (libc)Control Functions. |
| * fesetexcept: (libc)Status bit operations. |
| * fesetexceptflag: (libc)Status bit operations. |
| * fesetmode: (libc)Control Functions. |
| * fesetround: (libc)Rounding. |
| * fetestexcept: (libc)Status bit operations. |
| * fetestexceptflag: (libc)Status bit operations. |
| * feupdateenv: (libc)Control Functions. |
| * fflush: (libc)Flushing Buffers. |
| * fflush_unlocked: (libc)Flushing Buffers. |
| * fgetc: (libc)Character Input. |
| * fgetc_unlocked: (libc)Character Input. |
| * fgetgrent: (libc)Scanning All Groups. |
| * fgetgrent_r: (libc)Scanning All Groups. |
| * fgetpos64: (libc)Portable Positioning. |
| * fgetpos: (libc)Portable Positioning. |
| * fgetpwent: (libc)Scanning All Users. |
| * fgetpwent_r: (libc)Scanning All Users. |
| * fgets: (libc)Line Input. |
| * fgets_unlocked: (libc)Line Input. |
| * fgetwc: (libc)Character Input. |
| * fgetwc_unlocked: (libc)Character Input. |
| * fgetws: (libc)Line Input. |
| * fgetws_unlocked: (libc)Line Input. |
| * fileno: (libc)Descriptors and Streams. |
| * fileno_unlocked: (libc)Descriptors and Streams. |
| * finite: (libc)Floating Point Classes. |
| * finitef: (libc)Floating Point Classes. |
| * finitel: (libc)Floating Point Classes. |
| * flockfile: (libc)Streams and Threads. |
| * floor: (libc)Rounding Functions. |
| * floorf: (libc)Rounding Functions. |
| * floorfN: (libc)Rounding Functions. |
| * floorfNx: (libc)Rounding Functions. |
| * floorl: (libc)Rounding Functions. |
| * fma: (libc)Misc FP Arithmetic. |
| * fmaf: (libc)Misc FP Arithmetic. |
| * fmafN: (libc)Misc FP Arithmetic. |
| * fmafNx: (libc)Misc FP Arithmetic. |
| * fmal: (libc)Misc FP Arithmetic. |
| * fmax: (libc)Misc FP Arithmetic. |
| * fmaxf: (libc)Misc FP Arithmetic. |
| * fmaxfN: (libc)Misc FP Arithmetic. |
| * fmaxfNx: (libc)Misc FP Arithmetic. |
| * fmaxl: (libc)Misc FP Arithmetic. |
| * fmaxmag: (libc)Misc FP Arithmetic. |
| * fmaxmagf: (libc)Misc FP Arithmetic. |
| * fmaxmagfN: (libc)Misc FP Arithmetic. |
| * fmaxmagfNx: (libc)Misc FP Arithmetic. |
| * fmaxmagl: (libc)Misc FP Arithmetic. |
| * fmemopen: (libc)String Streams. |
| * fmin: (libc)Misc FP Arithmetic. |
| * fminf: (libc)Misc FP Arithmetic. |
| * fminfN: (libc)Misc FP Arithmetic. |
| * fminfNx: (libc)Misc FP Arithmetic. |
| * fminl: (libc)Misc FP Arithmetic. |
| * fminmag: (libc)Misc FP Arithmetic. |
| * fminmagf: (libc)Misc FP Arithmetic. |
| * fminmagfN: (libc)Misc FP Arithmetic. |
| * fminmagfNx: (libc)Misc FP Arithmetic. |
| * fminmagl: (libc)Misc FP Arithmetic. |
| * fmod: (libc)Remainder Functions. |
| * fmodf: (libc)Remainder Functions. |
| * fmodfN: (libc)Remainder Functions. |
| * fmodfNx: (libc)Remainder Functions. |
| * fmodl: (libc)Remainder Functions. |
| * fmtmsg: (libc)Printing Formatted Messages. |
| * fmul: (libc)Misc FP Arithmetic. |
| * fmull: (libc)Misc FP Arithmetic. |
| * fnmatch: (libc)Wildcard Matching. |
| * fopen64: (libc)Opening Streams. |
| * fopen: (libc)Opening Streams. |
| * fopencookie: (libc)Streams and Cookies. |
| * fork: (libc)Creating a Process. |
| * forkpty: (libc)Pseudo-Terminal Pairs. |
| * fpathconf: (libc)Pathconf. |
| * fpclassify: (libc)Floating Point Classes. |
| * fprintf: (libc)Formatted Output Functions. |
| * fputc: (libc)Simple Output. |
| * fputc_unlocked: (libc)Simple Output. |
| * fputs: (libc)Simple Output. |
| * fputs_unlocked: (libc)Simple Output. |
| * fputwc: (libc)Simple Output. |
| * fputwc_unlocked: (libc)Simple Output. |
| * fputws: (libc)Simple Output. |
| * fputws_unlocked: (libc)Simple Output. |
| * fread: (libc)Block Input/Output. |
| * fread_unlocked: (libc)Block Input/Output. |
| * free: (libc)Freeing after Malloc. |
| * freopen64: (libc)Opening Streams. |
| * freopen: (libc)Opening Streams. |
| * frexp: (libc)Normalization Functions. |
| * frexpf: (libc)Normalization Functions. |
| * frexpfN: (libc)Normalization Functions. |
| * frexpfNx: (libc)Normalization Functions. |
| * frexpl: (libc)Normalization Functions. |
| * fromfp: (libc)Rounding Functions. |
| * fromfpf: (libc)Rounding Functions. |
| * fromfpfN: (libc)Rounding Functions. |
| * fromfpfNx: (libc)Rounding Functions. |
| * fromfpl: (libc)Rounding Functions. |
| * fromfpx: (libc)Rounding Functions. |
| * fromfpxf: (libc)Rounding Functions. |
| * fromfpxfN: (libc)Rounding Functions. |
| * fromfpxfNx: (libc)Rounding Functions. |
| * fromfpxl: (libc)Rounding Functions. |
| * fscanf: (libc)Formatted Input Functions. |
| * fseek: (libc)File Positioning. |
| * fseeko64: (libc)File Positioning. |
| * fseeko: (libc)File Positioning. |
| * fsetpos64: (libc)Portable Positioning. |
| * fsetpos: (libc)Portable Positioning. |
| * fstat64: (libc)Reading Attributes. |
| * fstat: (libc)Reading Attributes. |
| * fsub: (libc)Misc FP Arithmetic. |
| * fsubl: (libc)Misc FP Arithmetic. |
| * fsync: (libc)Synchronizing I/O. |
| * ftell: (libc)File Positioning. |
| * ftello64: (libc)File Positioning. |
| * ftello: (libc)File Positioning. |
| * ftruncate64: (libc)File Size. |
| * ftruncate: (libc)File Size. |
| * ftrylockfile: (libc)Streams and Threads. |
| * ftw64: (libc)Working with Directory Trees. |
| * ftw: (libc)Working with Directory Trees. |
| * funlockfile: (libc)Streams and Threads. |
| * futimes: (libc)File Times. |
| * fwide: (libc)Streams and I18N. |
| * fwprintf: (libc)Formatted Output Functions. |
| * fwrite: (libc)Block Input/Output. |
| * fwrite_unlocked: (libc)Block Input/Output. |
| * fwscanf: (libc)Formatted Input Functions. |
| * gamma: (libc)Special Functions. |
| * gammaf: (libc)Special Functions. |
| * gammal: (libc)Special Functions. |
| * gcvt: (libc)System V Number Conversion. |
| * get_avphys_pages: (libc)Query Memory Parameters. |
| * get_current_dir_name: (libc)Working Directory. |
| * get_nprocs: (libc)Processor Resources. |
| * get_nprocs_conf: (libc)Processor Resources. |
| * get_phys_pages: (libc)Query Memory Parameters. |
| * getauxval: (libc)Auxiliary Vector. |
| * getc: (libc)Character Input. |
| * getc_unlocked: (libc)Character Input. |
| * getchar: (libc)Character Input. |
| * getchar_unlocked: (libc)Character Input. |
| * getcontext: (libc)System V contexts. |
| * getcpu: (libc)CPU Affinity. |
| * getcwd: (libc)Working Directory. |
| * getdate: (libc)General Time String Parsing. |
| * getdate_r: (libc)General Time String Parsing. |
| * getdelim: (libc)Line Input. |
| * getdents64: (libc)Low-level Directory Access. |
| * getdomainnname: (libc)Host Identification. |
| * getegid: (libc)Reading Persona. |
| * getentropy: (libc)Unpredictable Bytes. |
| * getenv: (libc)Environment Access. |
| * geteuid: (libc)Reading Persona. |
| * getfsent: (libc)fstab. |
| * getfsfile: (libc)fstab. |
| * getfsspec: (libc)fstab. |
| * getgid: (libc)Reading Persona. |
| * getgrent: (libc)Scanning All Groups. |
| * getgrent_r: (libc)Scanning All Groups. |
| * getgrgid: (libc)Lookup Group. |
| * getgrgid_r: (libc)Lookup Group. |
| * getgrnam: (libc)Lookup Group. |
| * getgrnam_r: (libc)Lookup Group. |
| * getgrouplist: (libc)Setting Groups. |
| * getgroups: (libc)Reading Persona. |
| * gethostbyaddr: (libc)Host Names. |
| * gethostbyaddr_r: (libc)Host Names. |
| * gethostbyname2: (libc)Host Names. |
| * gethostbyname2_r: (libc)Host Names. |
| * gethostbyname: (libc)Host Names. |
| * gethostbyname_r: (libc)Host Names. |
| * gethostent: (libc)Host Names. |
| * gethostid: (libc)Host Identification. |
| * gethostname: (libc)Host Identification. |
| * getitimer: (libc)Setting an Alarm. |
| * getline: (libc)Line Input. |
| * getloadavg: (libc)Processor Resources. |
| * getlogin: (libc)Who Logged In. |
| * getmntent: (libc)mtab. |
| * getmntent_r: (libc)mtab. |
| * getnetbyaddr: (libc)Networks Database. |
| * getnetbyname: (libc)Networks Database. |
| * getnetent: (libc)Networks Database. |
| * getnetgrent: (libc)Lookup Netgroup. |
| * getnetgrent_r: (libc)Lookup Netgroup. |
| * getopt: (libc)Using Getopt. |
| * getopt_long: (libc)Getopt Long Options. |
| * getopt_long_only: (libc)Getopt Long Options. |
| * getpagesize: (libc)Query Memory Parameters. |
| * getpass: (libc)getpass. |
| * getpayload: (libc)FP Bit Twiddling. |
| * getpayloadf: (libc)FP Bit Twiddling. |
| * getpayloadfN: (libc)FP Bit Twiddling. |
| * getpayloadfNx: (libc)FP Bit Twiddling. |
| * getpayloadl: (libc)FP Bit Twiddling. |
| * getpeername: (libc)Who is Connected. |
| * getpgid: (libc)Process Group Functions. |
| * getpgrp: (libc)Process Group Functions. |
| * getpid: (libc)Process Identification. |
| * getppid: (libc)Process Identification. |
| * getpriority: (libc)Traditional Scheduling Functions. |
| * getprotobyname: (libc)Protocols Database. |
| * getprotobynumber: (libc)Protocols Database. |
| * getprotoent: (libc)Protocols Database. |
| * getpt: (libc)Allocation. |
| * getpwent: (libc)Scanning All Users. |
| * getpwent_r: (libc)Scanning All Users. |
| * getpwnam: (libc)Lookup User. |
| * getpwnam_r: (libc)Lookup User. |
| * getpwuid: (libc)Lookup User. |
| * getpwuid_r: (libc)Lookup User. |
| * getrandom: (libc)Unpredictable Bytes. |
| * getrlimit64: (libc)Limits on Resources. |
| * getrlimit: (libc)Limits on Resources. |
| * getrusage: (libc)Resource Usage. |
| * gets: (libc)Line Input. |
| * getservbyname: (libc)Services Database. |
| * getservbyport: (libc)Services Database. |
| * getservent: (libc)Services Database. |
| * getsid: (libc)Process Group Functions. |
| * getsockname: (libc)Reading Address. |
| * getsockopt: (libc)Socket Option Functions. |
| * getsubopt: (libc)Suboptions. |
| * gettext: (libc)Translation with gettext. |
| * gettid: (libc)Process Identification. |
| * gettimeofday: (libc)High-Resolution Calendar. |
| * getuid: (libc)Reading Persona. |
| * getumask: (libc)Setting Permissions. |
| * getutent: (libc)Manipulating the Database. |
| * getutent_r: (libc)Manipulating the Database. |
| * getutid: (libc)Manipulating the Database. |
| * getutid_r: (libc)Manipulating the Database. |
| * getutline: (libc)Manipulating the Database. |
| * getutline_r: (libc)Manipulating the Database. |
| * getutmp: (libc)XPG Functions. |
| * getutmpx: (libc)XPG Functions. |
| * getutxent: (libc)XPG Functions. |
| * getutxid: (libc)XPG Functions. |
| * getutxline: (libc)XPG Functions. |
| * getw: (libc)Character Input. |
| * getwc: (libc)Character Input. |
| * getwc_unlocked: (libc)Character Input. |
| * getwchar: (libc)Character Input. |
| * getwchar_unlocked: (libc)Character Input. |
| * getwd: (libc)Working Directory. |
| * glob64: (libc)Calling Glob. |
| * glob: (libc)Calling Glob. |
| * globfree64: (libc)More Flags for Globbing. |
| * globfree: (libc)More Flags for Globbing. |
| * gmtime: (libc)Broken-down Time. |
| * gmtime_r: (libc)Broken-down Time. |
| * grantpt: (libc)Allocation. |
| * gsignal: (libc)Signaling Yourself. |
| * gtty: (libc)BSD Terminal Modes. |
| * hasmntopt: (libc)mtab. |
| * hcreate: (libc)Hash Search Function. |
| * hcreate_r: (libc)Hash Search Function. |
| * hdestroy: (libc)Hash Search Function. |
| * hdestroy_r: (libc)Hash Search Function. |
| * hsearch: (libc)Hash Search Function. |
| * hsearch_r: (libc)Hash Search Function. |
| * htonl: (libc)Byte Order. |
| * htons: (libc)Byte Order. |
| * hypot: (libc)Exponents and Logarithms. |
| * hypotf: (libc)Exponents and Logarithms. |
| * hypotfN: (libc)Exponents and Logarithms. |
| * hypotfNx: (libc)Exponents and Logarithms. |
| * hypotl: (libc)Exponents and Logarithms. |
| * iconv: (libc)Generic Conversion Interface. |
| * iconv_close: (libc)Generic Conversion Interface. |
| * iconv_open: (libc)Generic Conversion Interface. |
| * if_freenameindex: (libc)Interface Naming. |
| * if_indextoname: (libc)Interface Naming. |
| * if_nameindex: (libc)Interface Naming. |
| * if_nametoindex: (libc)Interface Naming. |
| * ilogb: (libc)Exponents and Logarithms. |
| * ilogbf: (libc)Exponents and Logarithms. |
| * ilogbfN: (libc)Exponents and Logarithms. |
| * ilogbfNx: (libc)Exponents and Logarithms. |
| * ilogbl: (libc)Exponents and Logarithms. |
| * imaxabs: (libc)Absolute Value. |
| * imaxdiv: (libc)Integer Division. |
| * in6addr_any: (libc)Host Address Data Type. |
| * in6addr_loopback: (libc)Host Address Data Type. |
| * index: (libc)Search Functions. |
| * inet_addr: (libc)Host Address Functions. |
| * inet_aton: (libc)Host Address Functions. |
| * inet_lnaof: (libc)Host Address Functions. |
| * inet_makeaddr: (libc)Host Address Functions. |
| * inet_netof: (libc)Host Address Functions. |
| * inet_network: (libc)Host Address Functions. |
| * inet_ntoa: (libc)Host Address Functions. |
| * inet_ntop: (libc)Host Address Functions. |
| * inet_pton: (libc)Host Address Functions. |
| * initgroups: (libc)Setting Groups. |
| * initstate: (libc)BSD Random. |
| * initstate_r: (libc)BSD Random. |
| * innetgr: (libc)Netgroup Membership. |
| * ioctl: (libc)IOCTLs. |
| * isalnum: (libc)Classification of Characters. |
| * isalpha: (libc)Classification of Characters. |
| * isascii: (libc)Classification of Characters. |
| * isatty: (libc)Is It a Terminal. |
| * isblank: (libc)Classification of Characters. |
| * iscanonical: (libc)Floating Point Classes. |
| * iscntrl: (libc)Classification of Characters. |
| * isdigit: (libc)Classification of Characters. |
| * iseqsig: (libc)FP Comparison Functions. |
| * isfinite: (libc)Floating Point Classes. |
| * isgraph: (libc)Classification of Characters. |
| * isgreater: (libc)FP Comparison Functions. |
| * isgreaterequal: (libc)FP Comparison Functions. |
| * isinf: (libc)Floating Point Classes. |
| * isinff: (libc)Floating Point Classes. |
| * isinfl: (libc)Floating Point Classes. |
| * isless: (libc)FP Comparison Functions. |
| * islessequal: (libc)FP Comparison Functions. |
| * islessgreater: (libc)FP Comparison Functions. |
| * islower: (libc)Classification of Characters. |
| * isnan: (libc)Floating Point Classes. |
| * isnan: (libc)Floating Point Classes. |
| * isnanf: (libc)Floating Point Classes. |
| * isnanl: (libc)Floating Point Classes. |
| * isnormal: (libc)Floating Point Classes. |
| * isprint: (libc)Classification of Characters. |
| * ispunct: (libc)Classification of Characters. |
| * issignaling: (libc)Floating Point Classes. |
| * isspace: (libc)Classification of Characters. |
| * issubnormal: (libc)Floating Point Classes. |
| * isunordered: (libc)FP Comparison Functions. |
| * isupper: (libc)Classification of Characters. |
| * iswalnum: (libc)Classification of Wide Characters. |
| * iswalpha: (libc)Classification of Wide Characters. |
| * iswblank: (libc)Classification of Wide Characters. |
| * iswcntrl: (libc)Classification of Wide Characters. |
| * iswctype: (libc)Classification of Wide Characters. |
| * iswdigit: (libc)Classification of Wide Characters. |
| * iswgraph: (libc)Classification of Wide Characters. |
| * iswlower: (libc)Classification of Wide Characters. |
| * iswprint: (libc)Classification of Wide Characters. |
| * iswpunct: (libc)Classification of Wide Characters. |
| * iswspace: (libc)Classification of Wide Characters. |
| * iswupper: (libc)Classification of Wide Characters. |
| * iswxdigit: (libc)Classification of Wide Characters. |
| * isxdigit: (libc)Classification of Characters. |
| * iszero: (libc)Floating Point Classes. |
| * j0: (libc)Special Functions. |
| * j0f: (libc)Special Functions. |
| * j0fN: (libc)Special Functions. |
| * j0fNx: (libc)Special Functions. |
| * j0l: (libc)Special Functions. |
| * j1: (libc)Special Functions. |
| * j1f: (libc)Special Functions. |
| * j1fN: (libc)Special Functions. |
| * j1fNx: (libc)Special Functions. |
| * j1l: (libc)Special Functions. |
| * jn: (libc)Special Functions. |
| * jnf: (libc)Special Functions. |
| * jnfN: (libc)Special Functions. |
| * jnfNx: (libc)Special Functions. |
| * jnl: (libc)Special Functions. |
| * jrand48: (libc)SVID Random. |
| * jrand48_r: (libc)SVID Random. |
| * kill: (libc)Signaling Another Process. |
| * killpg: (libc)Signaling Another Process. |
| * l64a: (libc)Encode Binary Data. |
| * labs: (libc)Absolute Value. |
| * lcong48: (libc)SVID Random. |
| * lcong48_r: (libc)SVID Random. |
| * ldexp: (libc)Normalization Functions. |
| * ldexpf: (libc)Normalization Functions. |
| * ldexpfN: (libc)Normalization Functions. |
| * ldexpfNx: (libc)Normalization Functions. |
| * ldexpl: (libc)Normalization Functions. |
| * ldiv: (libc)Integer Division. |
| * lfind: (libc)Array Search Function. |
| * lgamma: (libc)Special Functions. |
| * lgamma_r: (libc)Special Functions. |
| * lgammaf: (libc)Special Functions. |
| * lgammafN: (libc)Special Functions. |
| * lgammafN_r: (libc)Special Functions. |
| * lgammafNx: (libc)Special Functions. |
| * lgammafNx_r: (libc)Special Functions. |
| * lgammaf_r: (libc)Special Functions. |
| * lgammal: (libc)Special Functions. |
| * lgammal_r: (libc)Special Functions. |
| * link: (libc)Hard Links. |
| * linkat: (libc)Hard Links. |
| * lio_listio64: (libc)Asynchronous Reads/Writes. |
| * lio_listio: (libc)Asynchronous Reads/Writes. |
| * listen: (libc)Listening. |
| * llabs: (libc)Absolute Value. |
| * lldiv: (libc)Integer Division. |
| * llogb: (libc)Exponents and Logarithms. |
| * llogbf: (libc)Exponents and Logarithms. |
| * llogbfN: (libc)Exponents and Logarithms. |
| * llogbfNx: (libc)Exponents and Logarithms. |
| * llogbl: (libc)Exponents and Logarithms. |
| * llrint: (libc)Rounding Functions. |
| * llrintf: (libc)Rounding Functions. |
| * llrintfN: (libc)Rounding Functions. |
| * llrintfNx: (libc)Rounding Functions. |
| * llrintl: (libc)Rounding Functions. |
| * llround: (libc)Rounding Functions. |
| * llroundf: (libc)Rounding Functions. |
| * llroundfN: (libc)Rounding Functions. |
| * llroundfNx: (libc)Rounding Functions. |
| * llroundl: (libc)Rounding Functions. |
| * localeconv: (libc)The Lame Way to Locale Data. |
| * localtime: (libc)Broken-down Time. |
| * localtime_r: (libc)Broken-down Time. |
| * log10: (libc)Exponents and Logarithms. |
| * log10f: (libc)Exponents and Logarithms. |
| * log10fN: (libc)Exponents and Logarithms. |
| * log10fNx: (libc)Exponents and Logarithms. |
| * log10l: (libc)Exponents and Logarithms. |
| * log1p: (libc)Exponents and Logarithms. |
| * log1pf: (libc)Exponents and Logarithms. |
| * log1pfN: (libc)Exponents and Logarithms. |
| * log1pfNx: (libc)Exponents and Logarithms. |
| * log1pl: (libc)Exponents and Logarithms. |
| * log2: (libc)Exponents and Logarithms. |
| * log2f: (libc)Exponents and Logarithms. |
| * log2fN: (libc)Exponents and Logarithms. |
| * log2fNx: (libc)Exponents and Logarithms. |
| * log2l: (libc)Exponents and Logarithms. |
| * log: (libc)Exponents and Logarithms. |
| * logb: (libc)Exponents and Logarithms. |
| * logbf: (libc)Exponents and Logarithms. |
| * logbfN: (libc)Exponents and Logarithms. |
| * logbfNx: (libc)Exponents and Logarithms. |
| * logbl: (libc)Exponents and Logarithms. |
| * logf: (libc)Exponents and Logarithms. |
| * logfN: (libc)Exponents and Logarithms. |
| * logfNx: (libc)Exponents and Logarithms. |
| * login: (libc)Logging In and Out. |
| * login_tty: (libc)Logging In and Out. |
| * logl: (libc)Exponents and Logarithms. |
| * logout: (libc)Logging In and Out. |
| * logwtmp: (libc)Logging In and Out. |
| * longjmp: (libc)Non-Local Details. |
| * lrand48: (libc)SVID Random. |
| * lrand48_r: (libc)SVID Random. |
| * lrint: (libc)Rounding Functions. |
| * lrintf: (libc)Rounding Functions. |
| * lrintfN: (libc)Rounding Functions. |
| * lrintfNx: (libc)Rounding Functions. |
| * lrintl: (libc)Rounding Functions. |
| * lround: (libc)Rounding Functions. |
| * lroundf: (libc)Rounding Functions. |
| * lroundfN: (libc)Rounding Functions. |
| * lroundfNx: (libc)Rounding Functions. |
| * lroundl: (libc)Rounding Functions. |
| * lsearch: (libc)Array Search Function. |
| * lseek64: (libc)File Position Primitive. |
| * lseek: (libc)File Position Primitive. |
| * lstat64: (libc)Reading Attributes. |
| * lstat: (libc)Reading Attributes. |
| * lutimes: (libc)File Times. |
| * madvise: (libc)Memory-mapped I/O. |
| * makecontext: (libc)System V contexts. |
| * mallinfo: (libc)Statistics of Malloc. |
| * malloc: (libc)Basic Allocation. |
| * mallopt: (libc)Malloc Tunable Parameters. |
| * mblen: (libc)Non-reentrant Character Conversion. |
| * mbrlen: (libc)Converting a Character. |
| * mbrtowc: (libc)Converting a Character. |
| * mbsinit: (libc)Keeping the state. |
| * mbsnrtowcs: (libc)Converting Strings. |
| * mbsrtowcs: (libc)Converting Strings. |
| * mbstowcs: (libc)Non-reentrant String Conversion. |
| * mbtowc: (libc)Non-reentrant Character Conversion. |
| * mcheck: (libc)Heap Consistency Checking. |
| * memalign: (libc)Aligned Memory Blocks. |
| * memccpy: (libc)Copying Strings and Arrays. |
| * memchr: (libc)Search Functions. |
| * memcmp: (libc)String/Array Comparison. |
| * memcpy: (libc)Copying Strings and Arrays. |
| * memfd_create: (libc)Memory-mapped I/O. |
| * memfrob: (libc)Obfuscating Data. |
| * memmem: (libc)Search Functions. |
| * memmove: (libc)Copying Strings and Arrays. |
| * mempcpy: (libc)Copying Strings and Arrays. |
| * memrchr: (libc)Search Functions. |
| * memset: (libc)Copying Strings and Arrays. |
| * mkdir: (libc)Creating Directories. |
| * mkdtemp: (libc)Temporary Files. |
| * mkfifo: (libc)FIFO Special Files. |
| * mknod: (libc)Making Special Files. |
| * mkstemp: (libc)Temporary Files. |
| * mktemp: (libc)Temporary Files. |
| * mktime: (libc)Broken-down Time. |
| * mlock2: (libc)Page Lock Functions. |
| * mlock: (libc)Page Lock Functions. |
| * mlockall: (libc)Page Lock Functions. |
| * mmap64: (libc)Memory-mapped I/O. |
| * mmap: (libc)Memory-mapped I/O. |
| * modf: (libc)Rounding Functions. |
| * modff: (libc)Rounding Functions. |
| * modffN: (libc)Rounding Functions. |
| * modffNx: (libc)Rounding Functions. |
| * modfl: (libc)Rounding Functions. |
| * mount: (libc)Mount-Unmount-Remount. |
| * mprobe: (libc)Heap Consistency Checking. |
| * mprotect: (libc)Memory Protection. |
| * mrand48: (libc)SVID Random. |
| * mrand48_r: (libc)SVID Random. |
| * mremap: (libc)Memory-mapped I/O. |
| * msync: (libc)Memory-mapped I/O. |
| * mtrace: (libc)Tracing malloc. |
| * mtx_destroy: (libc)ISO C Mutexes. |
| * mtx_init: (libc)ISO C Mutexes. |
| * mtx_lock: (libc)ISO C Mutexes. |
| * mtx_timedlock: (libc)ISO C Mutexes. |
| * mtx_trylock: (libc)ISO C Mutexes. |
| * mtx_unlock: (libc)ISO C Mutexes. |
| * munlock: (libc)Page Lock Functions. |
| * munlockall: (libc)Page Lock Functions. |
| * munmap: (libc)Memory-mapped I/O. |
| * muntrace: (libc)Tracing malloc. |
| * nan: (libc)FP Bit Twiddling. |
| * nanf: (libc)FP Bit Twiddling. |
| * nanfN: (libc)FP Bit Twiddling. |
| * nanfNx: (libc)FP Bit Twiddling. |
| * nanl: (libc)FP Bit Twiddling. |
| * nanosleep: (libc)Sleeping. |
| * nearbyint: (libc)Rounding Functions. |
| * nearbyintf: (libc)Rounding Functions. |
| * nearbyintfN: (libc)Rounding Functions. |
| * nearbyintfNx: (libc)Rounding Functions. |
| * nearbyintl: (libc)Rounding Functions. |
| * nextafter: (libc)FP Bit Twiddling. |
| * nextafterf: (libc)FP Bit Twiddling. |
| * nextafterfN: (libc)FP Bit Twiddling. |
| * nextafterfNx: (libc)FP Bit Twiddling. |
| * nextafterl: (libc)FP Bit Twiddling. |
| * nextdown: (libc)FP Bit Twiddling. |
| * nextdownf: (libc)FP Bit Twiddling. |
| * nextdownfN: (libc)FP Bit Twiddling. |
| * nextdownfNx: (libc)FP Bit Twiddling. |
| * nextdownl: (libc)FP Bit Twiddling. |
| * nexttoward: (libc)FP Bit Twiddling. |
| * nexttowardf: (libc)FP Bit Twiddling. |
| * nexttowardl: (libc)FP Bit Twiddling. |
| * nextup: (libc)FP Bit Twiddling. |
| * nextupf: (libc)FP Bit Twiddling. |
| * nextupfN: (libc)FP Bit Twiddling. |
| * nextupfNx: (libc)FP Bit Twiddling. |
| * nextupl: (libc)FP Bit Twiddling. |
| * nftw64: (libc)Working with Directory Trees. |
| * nftw: (libc)Working with Directory Trees. |
| * ngettext: (libc)Advanced gettext functions. |
| * nice: (libc)Traditional Scheduling Functions. |
| * nl_langinfo: (libc)The Elegant and Fast Way. |
| * nrand48: (libc)SVID Random. |
| * nrand48_r: (libc)SVID Random. |
| * ntohl: (libc)Byte Order. |
| * ntohs: (libc)Byte Order. |
| * ntp_adjtime: (libc)High Accuracy Clock. |
| * ntp_gettime: (libc)High Accuracy Clock. |
| * obstack_1grow: (libc)Growing Objects. |
| * obstack_1grow_fast: (libc)Extra Fast Growing. |
| * obstack_alignment_mask: (libc)Obstacks Data Alignment. |
| * obstack_alloc: (libc)Allocation in an Obstack. |
| * obstack_base: (libc)Status of an Obstack. |
| * obstack_blank: (libc)Growing Objects. |
| * obstack_blank_fast: (libc)Extra Fast Growing. |
| * obstack_chunk_size: (libc)Obstack Chunks. |
| * obstack_copy0: (libc)Allocation in an Obstack. |
| * obstack_copy: (libc)Allocation in an Obstack. |
| * obstack_finish: (libc)Growing Objects. |
| * obstack_free: (libc)Freeing Obstack Objects. |
| * obstack_grow0: (libc)Growing Objects. |
| * obstack_grow: (libc)Growing Objects. |
| * obstack_init: (libc)Preparing for Obstacks. |
| * obstack_int_grow: (libc)Growing Objects. |
| * obstack_int_grow_fast: (libc)Extra Fast Growing. |
| * obstack_next_free: (libc)Status of an Obstack. |
| * obstack_object_size: (libc)Growing Objects. |
| * obstack_object_size: (libc)Status of an Obstack. |
| * obstack_printf: (libc)Dynamic Output. |
| * obstack_ptr_grow: (libc)Growing Objects. |
| * obstack_ptr_grow_fast: (libc)Extra Fast Growing. |
| * obstack_room: (libc)Extra Fast Growing. |
| * obstack_vprintf: (libc)Variable Arguments Output. |
| * offsetof: (libc)Structure Measurement. |
| * on_exit: (libc)Cleanups on Exit. |
| * open64: (libc)Opening and Closing Files. |
| * open: (libc)Opening and Closing Files. |
| * open_memstream: (libc)String Streams. |
| * opendir: (libc)Opening a Directory. |
| * openlog: (libc)openlog. |
| * openpty: (libc)Pseudo-Terminal Pairs. |
| * parse_printf_format: (libc)Parsing a Template String. |
| * pathconf: (libc)Pathconf. |
| * pause: (libc)Using Pause. |
| * pclose: (libc)Pipe to a Subprocess. |
| * perror: (libc)Error Messages. |
| * pipe: (libc)Creating a Pipe. |
| * pkey_alloc: (libc)Memory Protection. |
| * pkey_free: (libc)Memory Protection. |
| * pkey_get: (libc)Memory Protection. |
| * pkey_mprotect: (libc)Memory Protection. |
| * pkey_set: (libc)Memory Protection. |
| * popen: (libc)Pipe to a Subprocess. |
| * posix_fallocate64: (libc)Storage Allocation. |
| * posix_fallocate: (libc)Storage Allocation. |
| * posix_memalign: (libc)Aligned Memory Blocks. |
| * pow: (libc)Exponents and Logarithms. |
| * powf: (libc)Exponents and Logarithms. |
| * powfN: (libc)Exponents and Logarithms. |
| * powfNx: (libc)Exponents and Logarithms. |
| * powl: (libc)Exponents and Logarithms. |
| * pread64: (libc)I/O Primitives. |
| * pread: (libc)I/O Primitives. |
| * preadv2: (libc)Scatter-Gather. |
| * preadv64: (libc)Scatter-Gather. |
| * preadv64v2: (libc)Scatter-Gather. |
| * preadv: (libc)Scatter-Gather. |
| * printf: (libc)Formatted Output Functions. |
| * printf_size: (libc)Predefined Printf Handlers. |
| * printf_size_info: (libc)Predefined Printf Handlers. |
| * psignal: (libc)Signal Messages. |
| * pthread_cond_clockwait: (libc)Default Thread Attributes. |
| * pthread_getattr_default_np: (libc)Default Thread Attributes. |
| * pthread_getspecific: (libc)Thread-specific Data. |
| * pthread_key_create: (libc)Thread-specific Data. |
| * pthread_key_delete: (libc)Thread-specific Data. |
| * pthread_rwlock_clockrdlock: (libc)Default Thread Attributes. |
| * pthread_rwlock_clockwrlock: (libc)Default Thread Attributes. |
| * pthread_setattr_default_np: (libc)Default Thread Attributes. |
| * pthread_setspecific: (libc)Thread-specific Data. |
| * ptsname: (libc)Allocation. |
| * ptsname_r: (libc)Allocation. |
| * putc: (libc)Simple Output. |
| * putc_unlocked: (libc)Simple Output. |
| * putchar: (libc)Simple Output. |
| * putchar_unlocked: (libc)Simple Output. |
| * putenv: (libc)Environment Access. |
| * putpwent: (libc)Writing a User Entry. |
| * puts: (libc)Simple Output. |
| * pututline: (libc)Manipulating the Database. |
| * pututxline: (libc)XPG Functions. |
| * putw: (libc)Simple Output. |
| * putwc: (libc)Simple Output. |
| * putwc_unlocked: (libc)Simple Output. |
| * putwchar: (libc)Simple Output. |
| * putwchar_unlocked: (libc)Simple Output. |
| * pwrite64: (libc)I/O Primitives. |
| * pwrite: (libc)I/O Primitives. |
| * pwritev2: (libc)Scatter-Gather. |
| * pwritev64: (libc)Scatter-Gather. |
| * pwritev64v2: (libc)Scatter-Gather. |
| * pwritev: (libc)Scatter-Gather. |
| * qecvt: (libc)System V Number Conversion. |
| * qecvt_r: (libc)System V Number Conversion. |
| * qfcvt: (libc)System V Number Conversion. |
| * qfcvt_r: (libc)System V Number Conversion. |
| * qgcvt: (libc)System V Number Conversion. |
| * qsort: (libc)Array Sort Function. |
| * raise: (libc)Signaling Yourself. |
| * rand: (libc)ISO Random. |
| * rand_r: (libc)ISO Random. |
| * random: (libc)BSD Random. |
| * random_r: (libc)BSD Random. |
| * rawmemchr: (libc)Search Functions. |
| * read: (libc)I/O Primitives. |
| * readdir64: (libc)Reading/Closing Directory. |
| * readdir64_r: (libc)Reading/Closing Directory. |
| * readdir: (libc)Reading/Closing Directory. |
| * readdir_r: (libc)Reading/Closing Directory. |
| * readlink: (libc)Symbolic Links. |
| * readv: (libc)Scatter-Gather. |
| * realloc: (libc)Changing Block Size. |
| * reallocarray: (libc)Changing Block Size. |
| * realpath: (libc)Symbolic Links. |
| * recv: (libc)Receiving Data. |
| * recvfrom: (libc)Receiving Datagrams. |
| * recvmsg: (libc)Receiving Datagrams. |
| * regcomp: (libc)POSIX Regexp Compilation. |
| * regerror: (libc)Regexp Cleanup. |
| * regexec: (libc)Matching POSIX Regexps. |
| * regfree: (libc)Regexp Cleanup. |
| * register_printf_function: (libc)Registering New Conversions. |
| * remainder: (libc)Remainder Functions. |
| * remainderf: (libc)Remainder Functions. |
| * remainderfN: (libc)Remainder Functions. |
| * remainderfNx: (libc)Remainder Functions. |
| * remainderl: (libc)Remainder Functions. |
| * remove: (libc)Deleting Files. |
| * rename: (libc)Renaming Files. |
| * rewind: (libc)File Positioning. |
| * rewinddir: (libc)Random Access Directory. |
| * rindex: (libc)Search Functions. |
| * rint: (libc)Rounding Functions. |
| * rintf: (libc)Rounding Functions. |
| * rintfN: (libc)Rounding Functions. |
| * rintfNx: (libc)Rounding Functions. |
| * rintl: (libc)Rounding Functions. |
| * rmdir: (libc)Deleting Files. |
| * round: (libc)Rounding Functions. |
| * roundeven: (libc)Rounding Functions. |
| * roundevenf: (libc)Rounding Functions. |
| * roundevenfN: (libc)Rounding Functions. |
| * roundevenfNx: (libc)Rounding Functions. |
| * roundevenl: (libc)Rounding Functions. |
| * roundf: (libc)Rounding Functions. |
| * roundfN: (libc)Rounding Functions. |
| * roundfNx: (libc)Rounding Functions. |
| * roundl: (libc)Rounding Functions. |
| * rpmatch: (libc)Yes-or-No Questions. |
| * sbrk: (libc)Resizing the Data Segment. |
| * scalb: (libc)Normalization Functions. |
| * scalbf: (libc)Normalization Functions. |
| * scalbl: (libc)Normalization Functions. |
| * scalbln: (libc)Normalization Functions. |
| * scalblnf: (libc)Normalization Functions. |
| * scalblnfN: (libc)Normalization Functions. |
| * scalblnfNx: (libc)Normalization Functions. |
| * scalblnl: (libc)Normalization Functions. |
| * scalbn: (libc)Normalization Functions. |
| * scalbnf: (libc)Normalization Functions. |
| * scalbnfN: (libc)Normalization Functions. |
| * scalbnfNx: (libc)Normalization Functions. |
| * scalbnl: (libc)Normalization Functions. |
| * scandir64: (libc)Scanning Directory Content. |
| * scandir: (libc)Scanning Directory Content. |
| * scanf: (libc)Formatted Input Functions. |
| * sched_get_priority_max: (libc)Basic Scheduling Functions. |
| * sched_get_priority_min: (libc)Basic Scheduling Functions. |
| * sched_getaffinity: (libc)CPU Affinity. |
| * sched_getparam: (libc)Basic Scheduling Functions. |
| * sched_getscheduler: (libc)Basic Scheduling Functions. |
| * sched_rr_get_interval: (libc)Basic Scheduling Functions. |
| * sched_setaffinity: (libc)CPU Affinity. |
| * sched_setparam: (libc)Basic Scheduling Functions. |
| * sched_setscheduler: (libc)Basic Scheduling Functions. |
| * sched_yield: (libc)Basic Scheduling Functions. |
| * secure_getenv: (libc)Environment Access. |
| * seed48: (libc)SVID Random. |
| * seed48_r: (libc)SVID Random. |
| * seekdir: (libc)Random Access Directory. |
| * select: (libc)Waiting for I/O. |
| * sem_clockwait: (libc)Default Thread Attributes. |
| * sem_close: (libc)Semaphores. |
| * sem_destroy: (libc)Semaphores. |
| * sem_getvalue: (libc)Semaphores. |
| * sem_init: (libc)Semaphores. |
| * sem_open: (libc)Semaphores. |
| * sem_post: (libc)Semaphores. |
| * sem_timedwait: (libc)Semaphores. |
| * sem_trywait: (libc)Semaphores. |
| * sem_unlink: (libc)Semaphores. |
| * sem_wait: (libc)Semaphores. |
| * semctl: (libc)Semaphores. |
| * semget: (libc)Semaphores. |
| * semop: (libc)Semaphores. |
| * semtimedop: (libc)Semaphores. |
| * send: (libc)Sending Data. |
| * sendmsg: (libc)Receiving Datagrams. |
| * sendto: (libc)Sending Datagrams. |
| * setbuf: (libc)Controlling Buffering. |
| * setbuffer: (libc)Controlling Buffering. |
| * setcontext: (libc)System V contexts. |
| * setdomainname: (libc)Host Identification. |
| * setegid: (libc)Setting Groups. |
| * setenv: (libc)Environment Access. |
| * seteuid: (libc)Setting User ID. |
| * setfsent: (libc)fstab. |
| * setgid: (libc)Setting Groups. |
| * setgrent: (libc)Scanning All Groups. |
| * setgroups: (libc)Setting Groups. |
| * sethostent: (libc)Host Names. |
| * sethostid: (libc)Host Identification. |
| * sethostname: (libc)Host Identification. |
| * setitimer: (libc)Setting an Alarm. |
| * setjmp: (libc)Non-Local Details. |
| * setlinebuf: (libc)Controlling Buffering. |
| * setlocale: (libc)Setting the Locale. |
| * setlogmask: (libc)setlogmask. |
| * setmntent: (libc)mtab. |
| * setnetent: (libc)Networks Database. |
| * setnetgrent: (libc)Lookup Netgroup. |
| * setpayload: (libc)FP Bit Twiddling. |
| * setpayloadf: (libc)FP Bit Twiddling. |
| * setpayloadfN: (libc)FP Bit Twiddling. |
| * setpayloadfNx: (libc)FP Bit Twiddling. |
| * setpayloadl: (libc)FP Bit Twiddling. |
| * setpayloadsig: (libc)FP Bit Twiddling. |
| * setpayloadsigf: (libc)FP Bit Twiddling. |
| * setpayloadsigfN: (libc)FP Bit Twiddling. |
| * setpayloadsigfNx: (libc)FP Bit Twiddling. |
| * setpayloadsigl: (libc)FP Bit Twiddling. |
| * setpgid: (libc)Process Group Functions. |
| * setpgrp: (libc)Process Group Functions. |
| * setpriority: (libc)Traditional Scheduling Functions. |
| * setprotoent: (libc)Protocols Database. |
| * setpwent: (libc)Scanning All Users. |
| * setregid: (libc)Setting Groups. |
| * setreuid: (libc)Setting User ID. |
| * setrlimit64: (libc)Limits on Resources. |
| * setrlimit: (libc)Limits on Resources. |
| * setservent: (libc)Services Database. |
| * setsid: (libc)Process Group Functions. |
| * setsockopt: (libc)Socket Option Functions. |
| * setstate: (libc)BSD Random. |
| * setstate_r: (libc)BSD Random. |
| * settimeofday: (libc)High-Resolution Calendar. |
| * setuid: (libc)Setting User ID. |
| * setutent: (libc)Manipulating the Database. |
| * setutxent: (libc)XPG Functions. |
| * setvbuf: (libc)Controlling Buffering. |
| * shm_open: (libc)Memory-mapped I/O. |
| * shm_unlink: (libc)Memory-mapped I/O. |
| * shutdown: (libc)Closing a Socket. |
| * sigaction: (libc)Advanced Signal Handling. |
| * sigaddset: (libc)Signal Sets. |
| * sigaltstack: (libc)Signal Stack. |
| * sigblock: (libc)BSD Signal Handling. |
| * sigdelset: (libc)Signal Sets. |
| * sigemptyset: (libc)Signal Sets. |
| * sigfillset: (libc)Signal Sets. |
| * siginterrupt: (libc)BSD Signal Handling. |
| * sigismember: (libc)Signal Sets. |
| * siglongjmp: (libc)Non-Local Exits and Signals. |
| * sigmask: (libc)BSD Signal Handling. |
| * signal: (libc)Basic Signal Handling. |
| * signbit: (libc)FP Bit Twiddling. |
| * significand: (libc)Normalization Functions. |
| * significandf: (libc)Normalization Functions. |
| * significandl: (libc)Normalization Functions. |
| * sigpause: (libc)BSD Signal Handling. |
| * sigpending: (libc)Checking for Pending Signals. |
| * sigprocmask: (libc)Process Signal Mask. |
| * sigsetjmp: (libc)Non-Local Exits and Signals. |
| * sigsetmask: (libc)BSD Signal Handling. |
| * sigstack: (libc)Signal Stack. |
| * sigsuspend: (libc)Sigsuspend. |
| * sin: (libc)Trig Functions. |
| * sincos: (libc)Trig Functions. |
| * sincosf: (libc)Trig Functions. |
| * sincosfN: (libc)Trig Functions. |
| * sincosfNx: (libc)Trig Functions. |
| * sincosl: (libc)Trig Functions. |
| * sinf: (libc)Trig Functions. |
| * sinfN: (libc)Trig Functions. |
| * sinfNx: (libc)Trig Functions. |
| * sinh: (libc)Hyperbolic Functions. |
| * sinhf: (libc)Hyperbolic Functions. |
| * sinhfN: (libc)Hyperbolic Functions. |
| * sinhfNx: (libc)Hyperbolic Functions. |
| * sinhl: (libc)Hyperbolic Functions. |
| * sinl: (libc)Trig Functions. |
| * sleep: (libc)Sleeping. |
| * snprintf: (libc)Formatted Output Functions. |
| * socket: (libc)Creating a Socket. |
| * socketpair: (libc)Socket Pairs. |
| * sprintf: (libc)Formatted Output Functions. |
| * sqrt: (libc)Exponents and Logarithms. |
| * sqrtf: (libc)Exponents and Logarithms. |
| * sqrtfN: (libc)Exponents and Logarithms. |
| * sqrtfNx: (libc)Exponents and Logarithms. |
| * sqrtl: (libc)Exponents and Logarithms. |
| * srand48: (libc)SVID Random. |
| * srand48_r: (libc)SVID Random. |
| * srand: (libc)ISO Random. |
| * srandom: (libc)BSD Random. |
| * srandom_r: (libc)BSD Random. |
| * sscanf: (libc)Formatted Input Functions. |
| * ssignal: (libc)Basic Signal Handling. |
| * stat64: (libc)Reading Attributes. |
| * stat: (libc)Reading Attributes. |
| * stime: (libc)Simple Calendar Time. |
| * stpcpy: (libc)Copying Strings and Arrays. |
| * stpncpy: (libc)Truncating Strings. |
| * strcasecmp: (libc)String/Array Comparison. |
| * strcasestr: (libc)Search Functions. |
| * strcat: (libc)Concatenating Strings. |
| * strchr: (libc)Search Functions. |
| * strchrnul: (libc)Search Functions. |
| * strcmp: (libc)String/Array Comparison. |
| * strcoll: (libc)Collation Functions. |
| * strcpy: (libc)Copying Strings and Arrays. |
| * strcspn: (libc)Search Functions. |
| * strdup: (libc)Copying Strings and Arrays. |
| * strdupa: (libc)Copying Strings and Arrays. |
| * strerror: (libc)Error Messages. |
| * strerror_r: (libc)Error Messages. |
| * strfmon: (libc)Formatting Numbers. |
| * strfromd: (libc)Printing of Floats. |
| * strfromf: (libc)Printing of Floats. |
| * strfromfN: (libc)Printing of Floats. |
| * strfromfNx: (libc)Printing of Floats. |
| * strfroml: (libc)Printing of Floats. |
| * strfry: (libc)Shuffling Bytes. |
| * strftime: (libc)Formatting Calendar Time. |
| * strlen: (libc)String Length. |
| * strncasecmp: (libc)String/Array Comparison. |
| * strncat: (libc)Truncating Strings. |
| * strncmp: (libc)String/Array Comparison. |
| * strncpy: (libc)Truncating Strings. |
| * strndup: (libc)Truncating Strings. |
| * strndupa: (libc)Truncating Strings. |
| * strnlen: (libc)String Length. |
| * strpbrk: (libc)Search Functions. |
| * strptime: (libc)Low-Level Time String Parsing. |
| * strrchr: (libc)Search Functions. |
| * strsep: (libc)Finding Tokens in a String. |
| * strsignal: (libc)Signal Messages. |
| * strspn: (libc)Search Functions. |
| * strstr: (libc)Search Functions. |
| * strtod: (libc)Parsing of Floats. |
| * strtof: (libc)Parsing of Floats. |
| * strtofN: (libc)Parsing of Floats. |
| * strtofNx: (libc)Parsing of Floats. |
| * strtoimax: (libc)Parsing of Integers. |
| * strtok: (libc)Finding Tokens in a String. |
| * strtok_r: (libc)Finding Tokens in a String. |
| * strtol: (libc)Parsing of Integers. |
| * strtold: (libc)Parsing of Floats. |
| * strtoll: (libc)Parsing of Integers. |
| * strtoq: (libc)Parsing of Integers. |
| * strtoul: (libc)Parsing of Integers. |
| * strtoull: (libc)Parsing of Integers. |
| * strtoumax: (libc)Parsing of Integers. |
| * strtouq: (libc)Parsing of Integers. |
| * strverscmp: (libc)String/Array Comparison. |
| * strxfrm: (libc)Collation Functions. |
| * stty: (libc)BSD Terminal Modes. |
| * swapcontext: (libc)System V contexts. |
| * swprintf: (libc)Formatted Output Functions. |
| * swscanf: (libc)Formatted Input Functions. |
| * symlink: (libc)Symbolic Links. |
| * sync: (libc)Synchronizing I/O. |
| * syscall: (libc)System Calls. |
| * sysconf: (libc)Sysconf Definition. |
| * sysctl: (libc)System Parameters. |
| * syslog: (libc)syslog; vsyslog. |
| * system: (libc)Running a Command. |
| * sysv_signal: (libc)Basic Signal Handling. |
| * tan: (libc)Trig Functions. |
| * tanf: (libc)Trig Functions. |
| * tanfN: (libc)Trig Functions. |
| * tanfNx: (libc)Trig Functions. |
| * tanh: (libc)Hyperbolic Functions. |
| * tanhf: (libc)Hyperbolic Functions. |
| * tanhfN: (libc)Hyperbolic Functions. |
| * tanhfNx: (libc)Hyperbolic Functions. |
| * tanhl: (libc)Hyperbolic Functions. |
| * tanl: (libc)Trig Functions. |
| * tcdrain: (libc)Line Control. |
| * tcflow: (libc)Line Control. |
| * tcflush: (libc)Line Control. |
| * tcgetattr: (libc)Mode Functions. |
| * tcgetpgrp: (libc)Terminal Access Functions. |
| * tcgetsid: (libc)Terminal Access Functions. |
| * tcsendbreak: (libc)Line Control. |
| * tcsetattr: (libc)Mode Functions. |
| * tcsetpgrp: (libc)Terminal Access Functions. |
| * tdelete: (libc)Tree Search Function. |
| * tdestroy: (libc)Tree Search Function. |
| * telldir: (libc)Random Access Directory. |
| * tempnam: (libc)Temporary Files. |
| * textdomain: (libc)Locating gettext catalog. |
| * tfind: (libc)Tree Search Function. |
| * tgamma: (libc)Special Functions. |
| * tgammaf: (libc)Special Functions. |
| * tgammafN: (libc)Special Functions. |
| * tgammafNx: (libc)Special Functions. |
| * tgammal: (libc)Special Functions. |
| * tgkill: (libc)Signaling Another Process. |
| * thrd_create: (libc)ISO C Thread Management. |
| * thrd_current: (libc)ISO C Thread Management. |
| * thrd_detach: (libc)ISO C Thread Management. |
| * thrd_equal: (libc)ISO C Thread Management. |
| * thrd_exit: (libc)ISO C Thread Management. |
| * thrd_join: (libc)ISO C Thread Management. |
| * thrd_sleep: (libc)ISO C Thread Management. |
| * thrd_yield: (libc)ISO C Thread Management. |
| * time: (libc)Simple Calendar Time. |
| * timegm: (libc)Broken-down Time. |
| * timelocal: (libc)Broken-down Time. |
| * times: (libc)Processor Time. |
| * tmpfile64: (libc)Temporary Files. |
| * tmpfile: (libc)Temporary Files. |
| * tmpnam: (libc)Temporary Files. |
| * tmpnam_r: (libc)Temporary Files. |
| * toascii: (libc)Case Conversion. |
| * tolower: (libc)Case Conversion. |
| * totalorder: (libc)FP Comparison Functions. |
| * totalorderf: (libc)FP Comparison Functions. |
| * totalorderfN: (libc)FP Comparison Functions. |
| * totalorderfNx: (libc)FP Comparison Functions. |
| * totalorderl: (libc)FP Comparison Functions. |
| * totalordermag: (libc)FP Comparison Functions. |
| * totalordermagf: (libc)FP Comparison Functions. |
| * totalordermagfN: (libc)FP Comparison Functions. |
| * totalordermagfNx: (libc)FP Comparison Functions. |
| * totalordermagl: (libc)FP Comparison Functions. |
| * toupper: (libc)Case Conversion. |
| * towctrans: (libc)Wide Character Case Conversion. |
| * towlower: (libc)Wide Character Case Conversion. |
| * towupper: (libc)Wide Character Case Conversion. |
| * trunc: (libc)Rounding Functions. |
| * truncate64: (libc)File Size. |
| * truncate: (libc)File Size. |
| * truncf: (libc)Rounding Functions. |
| * truncfN: (libc)Rounding Functions. |
| * truncfNx: (libc)Rounding Functions. |
| * truncl: (libc)Rounding Functions. |
| * tsearch: (libc)Tree Search Function. |
| * tss_create: (libc)ISO C Thread-local Storage. |
| * tss_delete: (libc)ISO C Thread-local Storage. |
| * tss_get: (libc)ISO C Thread-local Storage. |
| * tss_set: (libc)ISO C Thread-local Storage. |
| * ttyname: (libc)Is It a Terminal. |
| * ttyname_r: (libc)Is It a Terminal. |
| * twalk: (libc)Tree Search Function. |
| * twalk_r: (libc)Tree Search Function. |
| * tzset: (libc)Time Zone Functions. |
| * ufromfp: (libc)Rounding Functions. |
| * ufromfpf: (libc)Rounding Functions. |
| * ufromfpfN: (libc)Rounding Functions. |
| * ufromfpfNx: (libc)Rounding Functions. |
| * ufromfpl: (libc)Rounding Functions. |
| * ufromfpx: (libc)Rounding Functions. |
| * ufromfpxf: (libc)Rounding Functions. |
| * ufromfpxfN: (libc)Rounding Functions. |
| * ufromfpxfNx: (libc)Rounding Functions. |
| * ufromfpxl: (libc)Rounding Functions. |
| * ulimit: (libc)Limits on Resources. |
| * umask: (libc)Setting Permissions. |
| * umount2: (libc)Mount-Unmount-Remount. |
| * umount: (libc)Mount-Unmount-Remount. |
| * uname: (libc)Platform Type. |
| * ungetc: (libc)How Unread. |
| * ungetwc: (libc)How Unread. |
| * unlink: (libc)Deleting Files. |
| * unlockpt: (libc)Allocation. |
| * unsetenv: (libc)Environment Access. |
| * updwtmp: (libc)Manipulating the Database. |
| * utime: (libc)File Times. |
| * utimes: (libc)File Times. |
| * utmpname: (libc)Manipulating the Database. |
| * utmpxname: (libc)XPG Functions. |
| * va_arg: (libc)Argument Macros. |
| * va_copy: (libc)Argument Macros. |
| * va_end: (libc)Argument Macros. |
| * va_start: (libc)Argument Macros. |
| * valloc: (libc)Aligned Memory Blocks. |
| * vasprintf: (libc)Variable Arguments Output. |
| * verr: (libc)Error Messages. |
| * verrx: (libc)Error Messages. |
| * versionsort64: (libc)Scanning Directory Content. |
| * versionsort: (libc)Scanning Directory Content. |
| * vfork: (libc)Creating a Process. |
| * vfprintf: (libc)Variable Arguments Output. |
| * vfscanf: (libc)Variable Arguments Input. |
| * vfwprintf: (libc)Variable Arguments Output. |
| * vfwscanf: (libc)Variable Arguments Input. |
| * vlimit: (libc)Limits on Resources. |
| * vprintf: (libc)Variable Arguments Output. |
| * vscanf: (libc)Variable Arguments Input. |
| * vsnprintf: (libc)Variable Arguments Output. |
| * vsprintf: (libc)Variable Arguments Output. |
| * vsscanf: (libc)Variable Arguments Input. |
| * vswprintf: (libc)Variable Arguments Output. |
| * vswscanf: (libc)Variable Arguments Input. |
| * vsyslog: (libc)syslog; vsyslog. |
| * vtimes: (libc)Resource Usage. |
| * vwarn: (libc)Error Messages. |
| * vwarnx: (libc)Error Messages. |
| * vwprintf: (libc)Variable Arguments Output. |
| * vwscanf: (libc)Variable Arguments Input. |
| * wait3: (libc)BSD Wait Functions. |
| * wait4: (libc)Process Completion. |
| * wait: (libc)Process Completion. |
| * waitpid: (libc)Process Completion. |
| * warn: (libc)Error Messages. |
| * warnx: (libc)Error Messages. |
| * wcpcpy: (libc)Copying Strings and Arrays. |
| * wcpncpy: (libc)Truncating Strings. |
| * wcrtomb: (libc)Converting a Character. |
| * wcscasecmp: (libc)String/Array Comparison. |
| * wcscat: (libc)Concatenating Strings. |
| * wcschr: (libc)Search Functions. |
| * wcschrnul: (libc)Search Functions. |
| * wcscmp: (libc)String/Array Comparison. |
| * wcscoll: (libc)Collation Functions. |
| * wcscpy: (libc)Copying Strings and Arrays. |
| * wcscspn: (libc)Search Functions. |
| * wcsdup: (libc)Copying Strings and Arrays. |
| * wcsftime: (libc)Formatting Calendar Time. |
| * wcslen: (libc)String Length. |
| * wcsncasecmp: (libc)String/Array Comparison. |
| * wcsncat: (libc)Truncating Strings. |
| * wcsncmp: (libc)String/Array Comparison. |
| * wcsncpy: (libc)Truncating Strings. |
| * wcsnlen: (libc)String Length. |
| * wcsnrtombs: (libc)Converting Strings. |
| * wcspbrk: (libc)Search Functions. |
| * wcsrchr: (libc)Search Functions. |
| * wcsrtombs: (libc)Converting Strings. |
| * wcsspn: (libc)Search Functions. |
| * wcsstr: (libc)Search Functions. |
| * wcstod: (libc)Parsing of Floats. |
| * wcstof: (libc)Parsing of Floats. |
| * wcstofN: (libc)Parsing of Floats. |
| * wcstofNx: (libc)Parsing of Floats. |
| * wcstoimax: (libc)Parsing of Integers. |
| * wcstok: (libc)Finding Tokens in a String. |
| * wcstol: (libc)Parsing of Integers. |
| * wcstold: (libc)Parsing of Floats. |
| * wcstoll: (libc)Parsing of Integers. |
| * wcstombs: (libc)Non-reentrant String Conversion. |
| * wcstoq: (libc)Parsing of Integers. |
| * wcstoul: (libc)Parsing of Integers. |
| * wcstoull: (libc)Parsing of Integers. |
| * wcstoumax: (libc)Parsing of Integers. |
| * wcstouq: (libc)Parsing of Integers. |
| * wcswcs: (libc)Search Functions. |
| * wcsxfrm: (libc)Collation Functions. |
| * wctob: (libc)Converting a Character. |
| * wctomb: (libc)Non-reentrant Character Conversion. |
| * wctrans: (libc)Wide Character Case Conversion. |
| * wctype: (libc)Classification of Wide Characters. |
| * wmemchr: (libc)Search Functions. |
| * wmemcmp: (libc)String/Array Comparison. |
| * wmemcpy: (libc)Copying Strings and Arrays. |
| * wmemmove: (libc)Copying Strings and Arrays. |
| * wmempcpy: (libc)Copying Strings and Arrays. |
| * wmemset: (libc)Copying Strings and Arrays. |
| * wordexp: (libc)Calling Wordexp. |
| * wordfree: (libc)Calling Wordexp. |
| * wprintf: (libc)Formatted Output Functions. |
| * write: (libc)I/O Primitives. |
| * writev: (libc)Scatter-Gather. |
| * wscanf: (libc)Formatted Input Functions. |
| * y0: (libc)Special Functions. |
| * y0f: (libc)Special Functions. |
| * y0fN: (libc)Special Functions. |
| * y0fNx: (libc)Special Functions. |
| * y0l: (libc)Special Functions. |
| * y1: (libc)Special Functions. |
| * y1f: (libc)Special Functions. |
| * y1fN: (libc)Special Functions. |
| * y1fNx: (libc)Special Functions. |
| * y1l: (libc)Special Functions. |
| * yn: (libc)Special Functions. |
| * ynf: (libc)Special Functions. |
| * ynfN: (libc)Special Functions. |
| * ynfNx: (libc)Special Functions. |
| * ynl: (libc)Special Functions. |
| END-INFO-DIR-ENTRY |
| |
| This file documents the GNU C Library. |
| |
| This is `The GNU C Library Reference Manual', for version 2.30 |
| (GNU Toolchain for the A-profile Architecture 9.2-2019.12 (arm-9.10)). |
| |
| Copyright (C) 1993-2019 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version |
| 1.3 or any later version published by the Free Software Foundation; |
| with the Invariant Sections being "Free Software Needs Free |
| Documentation" and "GNU Lesser General Public License", the Front-Cover |
| texts being "A GNU Manual", and with the Back-Cover Texts as in (a) |
| below. A copy of the license is included in the section entitled "GNU |
| Free Documentation License". |
| |
| (a) The FSF's Back-Cover Text is: "You have the freedom to copy and |
| modify this GNU manual. Buying copies from the FSF supports it in |
| developing GNU and promoting software freedom." |
| |
| |
| File: libc.info, Node: File Locks, Next: Open File Description Locks, Prev: File Status Flags, Up: Low-Level I/O |
| |
| 13.16 File Locks |
| ================ |
| |
| This section describes record locks that are associated with the |
| process. There is also a different type of record lock that is |
| associated with the open file description instead of the process. |
| *Note Open File Description Locks::. |
| |
| The remaining `fcntl' commands are used to support "record locking", |
| which permits multiple cooperating programs to prevent each other from |
| simultaneously accessing parts of a file in error-prone ways. |
| |
| An "exclusive" or "write" lock gives a process exclusive access for |
| writing to the specified part of the file. While a write lock is in |
| place, no other process can lock that part of the file. |
| |
| A "shared" or "read" lock prohibits any other process from |
| requesting a write lock on the specified part of the file. However, |
| other processes can request read locks. |
| |
| The `read' and `write' functions do not actually check to see |
| whether there are any locks in place. If you want to implement a |
| locking protocol for a file shared by multiple processes, your |
| application must do explicit `fcntl' calls to request and clear locks |
| at the appropriate points. |
| |
| Locks are associated with processes. A process can only have one |
| kind of lock set for each byte of a given file. When any file |
| descriptor for that file is closed by the process, all of the locks |
| that process holds on that file are released, even if the locks were |
| made using other descriptors that remain open. Likewise, locks are |
| released when a process exits, and are not inherited by child processes |
| created using `fork' (*note Creating a Process::). |
| |
| When making a lock, use a `struct flock' to specify what kind of |
| lock and where. This data type and the associated macros for the |
| `fcntl' function are declared in the header file `fcntl.h'. |
| |
| -- Data Type: struct flock |
| This structure is used with the `fcntl' function to describe a file |
| lock. It has these members: |
| |
| `short int l_type' |
| Specifies the type of the lock; one of `F_RDLCK', `F_WRLCK', |
| or `F_UNLCK'. |
| |
| `short int l_whence' |
| This corresponds to the WHENCE argument to `fseek' or |
| `lseek', and specifies what the offset is relative to. Its |
| value can be one of `SEEK_SET', `SEEK_CUR', or `SEEK_END'. |
| |
| `off_t l_start' |
| This specifies the offset of the start of the region to which |
| the lock applies, and is given in bytes relative to the point |
| specified by the `l_whence' member. |
| |
| `off_t l_len' |
| This specifies the length of the region to be locked. A |
| value of `0' is treated specially; it means the region |
| extends to the end of the file. |
| |
| `pid_t l_pid' |
| This field is the process ID (*note Process Creation |
| Concepts::) of the process holding the lock. It is filled in |
| by calling `fcntl' with the `F_GETLK' command, but is ignored |
| when making a lock. If the conflicting lock is an open file |
| description lock (*note Open File Description Locks::), then |
| this field will be set to -1. |
| |
| -- Macro: int F_GETLK |
| This macro is used as the COMMAND argument to `fcntl', to specify |
| that it should get information about a lock. This command |
| requires a third argument of type `struct flock *' to be passed to |
| `fcntl', so that the form of the call is: |
| |
| fcntl (FILEDES, F_GETLK, LOCKP) |
| |
| If there is a lock already in place that would block the lock |
| described by the LOCKP argument, information about that lock |
| overwrites `*LOCKP'. Existing locks are not reported if they are |
| compatible with making a new lock as specified. Thus, you should |
| specify a lock type of `F_WRLCK' if you want to find out about both |
| read and write locks, or `F_RDLCK' if you want to find out about |
| write locks only. |
| |
| There might be more than one lock affecting the region specified |
| by the LOCKP argument, but `fcntl' only returns information about |
| one of them. The `l_whence' member of the LOCKP structure is set |
| to `SEEK_SET' and the `l_start' and `l_len' fields set to identify |
| the locked region. |
| |
| If no lock applies, the only change to the LOCKP structure is to |
| update the `l_type' to a value of `F_UNLCK'. |
| |
| The normal return value from `fcntl' with this command is an |
| unspecified value other than -1, which is reserved to indicate an |
| error. The following `errno' error conditions are defined for |
| this command: |
| |
| `EBADF' |
| The FILEDES argument is invalid. |
| |
| `EINVAL' |
| Either the LOCKP argument doesn't specify valid lock |
| information, or the file associated with FILEDES doesn't |
| support locks. |
| |
| -- Macro: int F_SETLK |
| This macro is used as the COMMAND argument to `fcntl', to specify |
| that it should set or clear a lock. This command requires a third |
| argument of type `struct flock *' to be passed to `fcntl', so that |
| the form of the call is: |
| |
| fcntl (FILEDES, F_SETLK, LOCKP) |
| |
| If the process already has a lock on any part of the region, the |
| old lock on that part is replaced with the new lock. You can |
| remove a lock by specifying a lock type of `F_UNLCK'. |
| |
| If the lock cannot be set, `fcntl' returns immediately with a value |
| of -1. This function does not block while waiting for other |
| processes to release locks. If `fcntl' succeeds, it returns a |
| value other than -1. |
| |
| The following `errno' error conditions are defined for this |
| function: |
| |
| `EAGAIN' |
| `EACCES' |
| The lock cannot be set because it is blocked by an existing |
| lock on the file. Some systems use `EAGAIN' in this case, |
| and other systems use `EACCES'; your program should treat |
| them alike, after `F_SETLK'. (GNU/Linux and GNU/Hurd systems |
| always use `EAGAIN'.) |
| |
| `EBADF' |
| Either: the FILEDES argument is invalid; you requested a read |
| lock but the FILEDES is not open for read access; or, you |
| requested a write lock but the FILEDES is not open for write |
| access. |
| |
| `EINVAL' |
| Either the LOCKP argument doesn't specify valid lock |
| information, or the file associated with FILEDES doesn't |
| support locks. |
| |
| `ENOLCK' |
| The system has run out of file lock resources; there are |
| already too many file locks in place. |
| |
| Well-designed file systems never report this error, because |
| they have no limitation on the number of locks. However, you |
| must still take account of the possibility of this error, as |
| it could result from network access to a file system on |
| another machine. |
| |
| -- Macro: int F_SETLKW |
| This macro is used as the COMMAND argument to `fcntl', to specify |
| that it should set or clear a lock. It is just like the `F_SETLK' |
| command, but causes the process to block (or wait) until the |
| request can be specified. |
| |
| This command requires a third argument of type `struct flock *', as |
| for the `F_SETLK' command. |
| |
| The `fcntl' return values and errors are the same as for the |
| `F_SETLK' command, but these additional `errno' error conditions |
| are defined for this command: |
| |
| `EINTR' |
| The function was interrupted by a signal while it was waiting. |
| *Note Interrupted Primitives::. |
| |
| `EDEADLK' |
| The specified region is being locked by another process. But |
| that process is waiting to lock a region which the current |
| process has locked, so waiting for the lock would result in |
| deadlock. The system does not guarantee that it will detect |
| all such conditions, but it lets you know if it notices one. |
| |
| The following macros are defined for use as values for the `l_type' |
| member of the `flock' structure. The values are integer constants. |
| |
| `F_RDLCK' |
| This macro is used to specify a read (or shared) lock. |
| |
| `F_WRLCK' |
| This macro is used to specify a write (or exclusive) lock. |
| |
| `F_UNLCK' |
| This macro is used to specify that the region is unlocked. |
| |
| As an example of a situation where file locking is useful, consider a |
| program that can be run simultaneously by several different users, that |
| logs status information to a common file. One example of such a program |
| might be a game that uses a file to keep track of high scores. Another |
| example might be a program that records usage or accounting information |
| for billing purposes. |
| |
| Having multiple copies of the program simultaneously writing to the |
| file could cause the contents of the file to become mixed up. But you |
| can prevent this kind of problem by setting a write lock on the file |
| before actually writing to the file. |
| |
| If the program also needs to read the file and wants to make sure |
| that the contents of the file are in a consistent state, then it can |
| also use a read lock. While the read lock is set, no other process can |
| lock that part of the file for writing. |
| |
| Remember that file locks are only an _advisory_ protocol for |
| controlling access to a file. There is still potential for access to |
| the file by programs that don't use the lock protocol. |
| |
| |
| File: libc.info, Node: Open File Description Locks, Next: Open File Description Locks Example, Prev: File Locks, Up: Low-Level I/O |
| |
| 13.17 Open File Description Locks |
| ================================= |
| |
| In contrast to process-associated record locks (*note File Locks::), |
| open file description record locks are associated with an open file |
| description rather than a process. |
| |
| Using `fcntl' to apply an open file description lock on a region that |
| already has an existing open file description lock that was created via |
| the same file descriptor will never cause a lock conflict. |
| |
| Open file description locks are also inherited by child processes |
| across `fork', or `clone' with `CLONE_FILES' set (*note Creating a |
| Process::), along with the file descriptor. |
| |
| It is important to distinguish between the open file _description_ |
| (an instance of an open file, usually created by a call to `open') and |
| an open file _descriptor_, which is a numeric value that refers to the |
| open file description. The locks described here are associated with the |
| open file _description_ and not the open file _descriptor_. |
| |
| Using `dup' (*note Duplicating Descriptors::) to copy a file |
| descriptor does not give you a new open file description, but rather |
| copies a reference to an existing open file description and assigns it |
| to a new file descriptor. Thus, open file description locks set on a |
| file descriptor cloned by `dup' will never conflict with open file |
| description locks set on the original descriptor since they refer to the |
| same open file description. Depending on the range and type of lock |
| involved, the original lock may be modified by a `F_OFD_SETLK' or |
| `F_OFD_SETLKW' command in this situation however. |
| |
| Open file description locks always conflict with process-associated |
| locks, even if acquired by the same process or on the same open file |
| descriptor. |
| |
| Open file description locks use the same `struct flock' as |
| process-associated locks as an argument (*note File Locks::) and the |
| macros for the `command' values are also declared in the header file |
| `fcntl.h'. To use them, the macro `_GNU_SOURCE' must be defined prior |
| to including any header file. |
| |
| In contrast to process-associated locks, any `struct flock' used as |
| an argument to open file description lock commands must have the `l_pid' |
| value set to 0. Also, when returning information about an open file |
| description lock in a `F_GETLK' or `F_OFD_GETLK' request, the `l_pid' |
| field in `struct flock' will be set to -1 to indicate that the lock is |
| not associated with a process. |
| |
| When the same `struct flock' is reused as an argument to a |
| `F_OFD_SETLK' or `F_OFD_SETLKW' request after being used for an |
| `F_OFD_GETLK' request, it is necessary to inspect and reset the `l_pid' |
| field to 0. |
| |
| -- Macro: int F_OFD_GETLK |
| This macro is used as the COMMAND argument to `fcntl', to specify |
| that it should get information about a lock. This command |
| requires a third argument of type `struct flock *' to be passed to |
| `fcntl', so that the form of the call is: |
| |
| fcntl (FILEDES, F_OFD_GETLK, LOCKP) |
| |
| If there is a lock already in place that would block the lock |
| described by the LOCKP argument, information about that lock is |
| written to `*LOCKP'. Existing locks are not reported if they are |
| compatible with making a new lock as specified. Thus, you should |
| specify a lock type of `F_WRLCK' if you want to find out about both |
| read and write locks, or `F_RDLCK' if you want to find out about |
| write locks only. |
| |
| There might be more than one lock affecting the region specified |
| by the LOCKP argument, but `fcntl' only returns information about |
| one of them. Which lock is returned in this situation is undefined. |
| |
| The `l_whence' member of the LOCKP structure are set to `SEEK_SET' |
| and the `l_start' and `l_len' fields are set to identify the |
| locked region. |
| |
| If no conflicting lock exists, the only change to the LOCKP |
| structure is to update the `l_type' field to the value `F_UNLCK'. |
| |
| The normal return value from `fcntl' with this command is either 0 |
| on success or -1, which indicates an error. The following `errno' |
| error conditions are defined for this command: |
| |
| `EBADF' |
| The FILEDES argument is invalid. |
| |
| `EINVAL' |
| Either the LOCKP argument doesn't specify valid lock |
| information, the operating system kernel doesn't support open |
| file description locks, or the file associated with FILEDES |
| doesn't support locks. |
| |
| -- Macro: int F_OFD_SETLK |
| This macro is used as the COMMAND argument to `fcntl', to specify |
| that it should set or clear a lock. This command requires a third |
| argument of type `struct flock *' to be passed to `fcntl', so that |
| the form of the call is: |
| |
| fcntl (FILEDES, F_OFD_SETLK, LOCKP) |
| |
| If the open file already has a lock on any part of the region, the |
| old lock on that part is replaced with the new lock. You can |
| remove a lock by specifying a lock type of `F_UNLCK'. |
| |
| If the lock cannot be set, `fcntl' returns immediately with a value |
| of -1. This command does not wait for other tasks to release |
| locks. If `fcntl' succeeds, it returns 0. |
| |
| The following `errno' error conditions are defined for this |
| command: |
| |
| `EAGAIN' |
| The lock cannot be set because it is blocked by an existing |
| lock on the file. |
| |
| `EBADF' |
| Either: the FILEDES argument is invalid; you requested a read |
| lock but the FILEDES is not open for read access; or, you |
| requested a write lock but the FILEDES is not open for write |
| access. |
| |
| `EINVAL' |
| Either the LOCKP argument doesn't specify valid lock |
| information, the operating system kernel doesn't support open |
| file description locks, or the file associated with FILEDES |
| doesn't support locks. |
| |
| `ENOLCK' |
| The system has run out of file lock resources; there are |
| already too many file locks in place. |
| |
| Well-designed file systems never report this error, because |
| they have no limitation on the number of locks. However, you |
| must still take account of the possibility of this error, as |
| it could result from network access to a file system on |
| another machine. |
| |
| -- Macro: int F_OFD_SETLKW |
| This macro is used as the COMMAND argument to `fcntl', to specify |
| that it should set or clear a lock. It is just like the |
| `F_OFD_SETLK' command, but causes the process to wait until the |
| request can be completed. |
| |
| This command requires a third argument of type `struct flock *', as |
| for the `F_OFD_SETLK' command. |
| |
| The `fcntl' return values and errors are the same as for the |
| `F_OFD_SETLK' command, but these additional `errno' error |
| conditions are defined for this command: |
| |
| `EINTR' |
| The function was interrupted by a signal while it was waiting. |
| *Note Interrupted Primitives::. |
| |
| |
| Open file description locks are useful in the same sorts of |
| situations as process-associated locks. They can also be used to |
| synchronize file access between threads within the same process by |
| having each thread perform its own `open' of the file, to obtain its |
| own open file description. |
| |
| Because open file description locks are automatically freed only upon |
| closing the last file descriptor that refers to the open file |
| description, this locking mechanism avoids the possibility that locks |
| are inadvertently released due to a library routine opening and closing |
| a file without the application being aware. |
| |
| As with process-associated locks, open file description locks are |
| advisory. |
| |
| |
| File: libc.info, Node: Open File Description Locks Example, Next: Interrupt Input, Prev: Open File Description Locks, Up: Low-Level I/O |
| |
| 13.18 Open File Description Locks Example |
| ========================================= |
| |
| Here is an example of using open file description locks in a threaded |
| program. If this program used process-associated locks, then it would be |
| subject to data corruption because process-associated locks are shared |
| by the threads inside a process, and thus cannot be used by one thread |
| to lock out another thread in the same process. |
| |
| Proper error handling has been omitted in the following program for |
| brevity. |
| |
| |
| #define _GNU_SOURCE |
| #include <stdio.h> |
| #include <sys/types.h> |
| #include <sys/stat.h> |
| #include <unistd.h> |
| #include <fcntl.h> |
| #include <pthread.h> |
| |
| #define FILENAME "/tmp/foo" |
| #define NUM_THREADS 3 |
| #define ITERATIONS 5 |
| |
| void * |
| thread_start (void *arg) |
| { |
| int i, fd, len; |
| long tid = (long) arg; |
| char buf[256]; |
| struct flock lck = { |
| .l_whence = SEEK_SET, |
| .l_start = 0, |
| .l_len = 1, |
| }; |
| |
| fd = open ("/tmp/foo", O_RDWR | O_CREAT, 0666); |
| |
| for (i = 0; i < ITERATIONS; i++) |
| { |
| lck.l_type = F_WRLCK; |
| fcntl (fd, F_OFD_SETLKW, &lck); |
| |
| len = sprintf (buf, "%d: tid=%ld fd=%d\n", i, tid, fd); |
| |
| lseek (fd, 0, SEEK_END); |
| write (fd, buf, len); |
| fsync (fd); |
| |
| lck.l_type = F_UNLCK; |
| fcntl (fd, F_OFD_SETLK, &lck); |
| |
| /* sleep to ensure lock is yielded to another thread */ |
| usleep (1); |
| } |
| pthread_exit (NULL); |
| } |
| |
| int |
| main (int argc, char **argv) |
| { |
| long i; |
| pthread_t threads[NUM_THREADS]; |
| |
| truncate (FILENAME, 0); |
| |
| for (i = 0; i < NUM_THREADS; i++) |
| pthread_create (&threads[i], NULL, thread_start, (void *) i); |
| |
| pthread_exit (NULL); |
| return 0; |
| } |
| |
| This example creates three threads each of which loops five times, |
| appending to the file. Access to the file is serialized via open file |
| description locks. If we compile and run the above program, we'll end up |
| with /tmp/foo that has 15 lines in it. |
| |
| If we, however, were to replace the `F_OFD_SETLK' and `F_OFD_SETLKW' |
| commands with their process-associated lock equivalents, the locking |
| essentially becomes a noop since it is all done within the context of |
| the same process. That leads to data corruption (typically manifested |
| as missing lines) as some threads race in and overwrite the data |
| written by others. |
| |
| |
| File: libc.info, Node: Interrupt Input, Next: IOCTLs, Prev: Open File Description Locks Example, Up: Low-Level I/O |
| |
| 13.19 Interrupt-Driven Input |
| ============================ |
| |
| If you set the `O_ASYNC' status flag on a file descriptor (*note File |
| Status Flags::), a `SIGIO' signal is sent whenever input or output |
| becomes possible on that file descriptor. The process or process group |
| to receive the signal can be selected by using the `F_SETOWN' command |
| to the `fcntl' function. If the file descriptor is a socket, this also |
| selects the recipient of `SIGURG' signals that are delivered when |
| out-of-band data arrives on that socket; see *note Out-of-Band Data::. |
| (`SIGURG' is sent in any situation where `select' would report the |
| socket as having an "exceptional condition". *Note Waiting for I/O::.) |
| |
| If the file descriptor corresponds to a terminal device, then `SIGIO' |
| signals are sent to the foreground process group of the terminal. |
| *Note Job Control::. |
| |
| The symbols in this section are defined in the header file `fcntl.h'. |
| |
| -- Macro: int F_GETOWN |
| This macro is used as the COMMAND argument to `fcntl', to specify |
| that it should get information about the process or process group |
| to which `SIGIO' signals are sent. (For a terminal, this is |
| actually the foreground process group ID, which you can get using |
| `tcgetpgrp'; see *note Terminal Access Functions::.) |
| |
| The return value is interpreted as a process ID; if negative, its |
| absolute value is the process group ID. |
| |
| The following `errno' error condition is defined for this command: |
| |
| `EBADF' |
| The FILEDES argument is invalid. |
| |
| -- Macro: int F_SETOWN |
| This macro is used as the COMMAND argument to `fcntl', to specify |
| that it should set the process or process group to which `SIGIO' |
| signals are sent. This command requires a third argument of type |
| `pid_t' to be passed to `fcntl', so that the form of the call is: |
| |
| fcntl (FILEDES, F_SETOWN, PID) |
| |
| The PID argument should be a process ID. You can also pass a |
| negative number whose absolute value is a process group ID. |
| |
| The return value from `fcntl' with this command is -1 in case of |
| error and some other value if successful. The following `errno' |
| error conditions are defined for this command: |
| |
| `EBADF' |
| The FILEDES argument is invalid. |
| |
| `ESRCH' |
| There is no process or process group corresponding to PID. |
| |
| |
| File: libc.info, Node: IOCTLs, Prev: Interrupt Input, Up: Low-Level I/O |
| |
| 13.20 Generic I/O Control operations |
| ==================================== |
| |
| GNU systems can handle most input/output operations on many different |
| devices and objects in terms of a few file primitives - `read', `write' |
| and `lseek'. However, most devices also have a few peculiar operations |
| which do not fit into this model. Such as: |
| |
| * Changing the character font used on a terminal. |
| |
| * Telling a magnetic tape system to rewind or fast forward. (Since |
| they cannot move in byte increments, `lseek' is inapplicable). |
| |
| * Ejecting a disk from a drive. |
| |
| * Playing an audio track from a CD-ROM drive. |
| |
| * Maintaining routing tables for a network. |
| |
| |
| Although some such objects such as sockets and terminals (1) have |
| special functions of their own, it would not be practical to create |
| functions for all these cases. |
| |
| Instead these minor operations, known as "IOCTL"s, are assigned code |
| numbers and multiplexed through the `ioctl' function, defined in |
| `sys/ioctl.h'. The code numbers themselves are defined in many |
| different headers. |
| |
| -- Function: int ioctl (int FILEDES, int COMMAND, ...) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `ioctl' function performs the generic I/O operation COMMAND on |
| FILEDES. |
| |
| A third argument is usually present, either a single number or a |
| pointer to a structure. The meaning of this argument, the |
| returned value, and any error codes depends upon the command used. |
| Often -1 is returned for a failure. |
| |
| |
| On some systems, IOCTLs used by different devices share the same |
| numbers. Thus, although use of an inappropriate IOCTL _usually_ only |
| produces an error, you should not attempt to use device-specific IOCTLs |
| on an unknown device. |
| |
| Most IOCTLs are OS-specific and/or only used in special system |
| utilities, and are thus beyond the scope of this document. For an |
| example of the use of an IOCTL, see *note Out-of-Band Data::. |
| |
| ---------- Footnotes ---------- |
| |
| (1) Actually, the terminal-specific functions are implemented with |
| IOCTLs on many platforms. |
| |
| |
| File: libc.info, Node: File System Interface, Next: Pipes and FIFOs, Prev: Low-Level I/O, Up: Top |
| |
| 14 File System Interface |
| ************************ |
| |
| This chapter describes the GNU C Library's functions for manipulating |
| files. Unlike the input and output functions (*note I/O on Streams::; |
| *note Low-Level I/O::), these functions are concerned with operating on |
| the files themselves rather than on their contents. |
| |
| Among the facilities described in this chapter are functions for |
| examining or modifying directories, functions for renaming and deleting |
| files, and functions for examining and setting file attributes such as |
| access permissions and modification times. |
| |
| * Menu: |
| |
| * 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. |
| |
| |
| File: libc.info, Node: Working Directory, Next: Accessing Directories, Up: File System Interface |
| |
| 14.1 Working Directory |
| ====================== |
| |
| Each process has associated with it a directory, called its "current |
| working directory" or simply "working directory", that is used in the |
| resolution of relative file names (*note File Name Resolution::). |
| |
| When you log in and begin a new session, your working directory is |
| initially set to the home directory associated with your login account |
| in the system user database. You can find any user's home directory |
| using the `getpwuid' or `getpwnam' functions; see *note User Database::. |
| |
| Users can change the working directory using shell commands like |
| `cd'. The functions described in this section are the primitives used |
| by those commands and by other programs for examining and changing the |
| working directory. |
| |
| Prototypes for these functions are declared in the header file |
| `unistd.h'. |
| |
| -- Function: char * getcwd (char *BUFFER, size_t SIZE) |
| Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | *Note |
| POSIX Safety Concepts::. |
| |
| The `getcwd' function returns an absolute file name representing |
| the current working directory, storing it in the character array |
| BUFFER that you provide. The SIZE argument is how you tell the |
| system the allocation size of BUFFER. |
| |
| The GNU C Library version of this function also permits you to |
| specify a null pointer for the BUFFER argument. Then `getcwd' |
| allocates a buffer automatically, as with `malloc' (*note |
| Unconstrained Allocation::). If the SIZE is greater than zero, |
| then the buffer is that large; otherwise, the buffer is as large |
| as necessary to hold the result. |
| |
| The return value is BUFFER on success and a null pointer on |
| failure. The following `errno' error conditions are defined for |
| this function: |
| |
| `EINVAL' |
| The SIZE argument is zero and BUFFER is not a null pointer. |
| |
| `ERANGE' |
| The SIZE argument is less than the length of the working |
| directory name. You need to allocate a bigger array and try |
| again. |
| |
| `EACCES' |
| Permission to read or search a component of the file name was |
| denied. |
| |
| You could implement the behavior of GNU's `getcwd (NULL, 0)' using |
| only the standard behavior of `getcwd': |
| |
| char * |
| gnu_getcwd () |
| { |
| size_t size = 100; |
| |
| while (1) |
| { |
| char *buffer = (char *) xmalloc (size); |
| if (getcwd (buffer, size) == buffer) |
| return buffer; |
| free (buffer); |
| if (errno != ERANGE) |
| return 0; |
| size *= 2; |
| } |
| } |
| |
| *Note Malloc Examples::, for information about `xmalloc', which is not |
| a library function but is a customary name used in most GNU software. |
| |
| -- Deprecated Function: char * getwd (char *BUFFER) |
| Preliminary: | MT-Safe | AS-Unsafe heap i18n | AC-Unsafe mem fd | |
| *Note POSIX Safety Concepts::. |
| |
| This is similar to `getcwd', but has no way to specify the size of |
| the buffer. The GNU C Library provides `getwd' only for backwards |
| compatibility with BSD. |
| |
| The BUFFER argument should be a pointer to an array at least |
| `PATH_MAX' bytes long (*note Limits for Files::). On GNU/Hurd |
| systems there is no limit to the size of a file name, so this is |
| not necessarily enough space to contain the directory name. That |
| is why this function is deprecated. |
| |
| -- Function: char * get_current_dir_name (void) |
| Preliminary: | MT-Safe env | AS-Unsafe heap | AC-Unsafe mem fd | |
| *Note POSIX Safety Concepts::. |
| |
| The `get_current_dir_name' function is basically equivalent to |
| `getcwd (NULL, 0)', except the value of the `PWD' environment |
| variable is first examined, and if it does in fact correspond to |
| the current directory, that value is returned. This is a subtle |
| difference which is visible if the path described by the value in |
| `PWD' is using one or more symbolic links, in which case the value |
| returned by `getcwd' would resolve the symbolic links and |
| therefore yield a different result. |
| |
| This function is a GNU extension. |
| |
| -- Function: int chdir (const char *FILENAME) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is used to set the process's working directory to |
| FILENAME. |
| |
| The normal, successful return value from `chdir' is `0'. A value |
| of `-1' is returned to indicate an error. The `errno' error |
| conditions defined for this function are the usual file name |
| syntax errors (*note File Name Errors::), plus `ENOTDIR' if the |
| file FILENAME is not a directory. |
| |
| -- Function: int fchdir (int FILEDES) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is used to set the process's working directory to |
| directory associated with the file descriptor FILEDES. |
| |
| The normal, successful return value from `fchdir' is `0'. A value |
| of `-1' is returned to indicate an error. The following `errno' |
| error conditions are defined for this function: |
| |
| `EACCES' |
| Read permission is denied for the directory named by |
| `dirname'. |
| |
| `EBADF' |
| The FILEDES argument is not a valid file descriptor. |
| |
| `ENOTDIR' |
| The file descriptor FILEDES is not associated with a |
| directory. |
| |
| `EINTR' |
| The function call was interrupt by a signal. |
| |
| `EIO' |
| An I/O error occurred. |
| |
| |
| File: libc.info, Node: Accessing Directories, Next: Working with Directory Trees, Prev: Working Directory, Up: File System Interface |
| |
| 14.2 Accessing Directories |
| ========================== |
| |
| The facilities described in this section let you read the contents of a |
| directory file. This is useful if you want your program to list all the |
| files in a directory, perhaps as part of a menu. |
| |
| The `opendir' function opens a "directory stream" whose elements are |
| directory entries. Alternatively `fdopendir' can be used which can |
| have advantages if the program needs to have more control over the way |
| the directory is opened for reading. This allows, for instance, to |
| pass the `O_NOATIME' flag to `open'. |
| |
| You use the `readdir' function on the directory stream to retrieve |
| these entries, represented as `struct dirent' objects. The name of the |
| file for each entry is stored in the `d_name' member of this structure. |
| There are obvious parallels here to the stream facilities for ordinary |
| files, described in *note I/O on Streams::. |
| |
| * Menu: |
| |
| * 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. |
| * Low-level Directory Access:: AS-Safe functions for directory access. |
| |
| |
| File: libc.info, Node: Directory Entries, Next: Opening a Directory, Up: Accessing Directories |
| |
| 14.2.1 Format of a Directory Entry |
| ---------------------------------- |
| |
| This section describes what you find in a single directory entry, as you |
| might obtain it from a directory stream. All the symbols are declared |
| in the header file `dirent.h'. |
| |
| -- Data Type: struct dirent |
| This is a structure type used to return information about directory |
| entries. It contains the following fields: |
| |
| `char d_name[]' |
| This is the null-terminated file name component. This is the |
| only field you can count on in all POSIX systems. |
| |
| `ino_t d_fileno' |
| This is the file serial number. For BSD compatibility, you |
| can also refer to this member as `d_ino'. On GNU/Linux and |
| GNU/Hurd systems and most POSIX systems, for most files this |
| the same as the `st_ino' member that `stat' will return for |
| the file. *Note File Attributes::. |
| |
| `unsigned char d_namlen' |
| This is the length of the file name, not including the |
| terminating null character. Its type is `unsigned char' |
| because that is the integer type of the appropriate size. |
| This member is a BSD extension. The symbol |
| `_DIRENT_HAVE_D_NAMLEN' is defined if this member is |
| available. |
| |
| `unsigned char d_type' |
| This is the type of the file, possibly unknown. The |
| following constants are defined for its value: |
| |
| `DT_UNKNOWN' |
| The type is unknown. Only some filesystems have full |
| support to return the type of the file, others might |
| always return this value. |
| |
| `DT_REG' |
| A regular file. |
| |
| `DT_DIR' |
| A directory. |
| |
| `DT_FIFO' |
| A named pipe, or FIFO. *Note FIFO Special Files::. |
| |
| `DT_SOCK' |
| A local-domain socket. |
| |
| `DT_CHR' |
| A character device. |
| |
| `DT_BLK' |
| A block device. |
| |
| `DT_LNK' |
| A symbolic link. |
| |
| This member is a BSD extension. The symbol |
| `_DIRENT_HAVE_D_TYPE' is defined if this member is available. |
| On systems where it is used, it corresponds to the file type |
| bits in the `st_mode' member of `struct stat'. If the value |
| cannot be determined the member value is DT_UNKNOWN. These |
| two macros convert between `d_type' values and `st_mode' |
| values: |
| |
| -- Function: int IFTODT (mode_t MODE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| This returns the `d_type' value corresponding to MODE. |
| |
| -- Function: mode_t DTTOIF (int DTYPE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| This returns the `st_mode' value corresponding to DTYPE. |
| |
| This structure may contain additional members in the future. Their |
| availability is always announced in the compilation environment by |
| a macro named `_DIRENT_HAVE_D_XXX' where XXX is replaced by the |
| name of the new member. For instance, the member `d_reclen' |
| available on some systems is announced through the macro |
| `_DIRENT_HAVE_D_RECLEN'. |
| |
| When a file has multiple names, each name has its own directory |
| entry. The only way you can tell that the directory entries |
| belong to a single file is that they have the same value for the |
| `d_fileno' field. |
| |
| File attributes such as size, modification times etc., are part of |
| the file itself, not of any particular directory entry. *Note |
| File Attributes::. |
| |
| |
| File: libc.info, Node: Opening a Directory, Next: Reading/Closing Directory, Prev: Directory Entries, Up: Accessing Directories |
| |
| 14.2.2 Opening a Directory Stream |
| --------------------------------- |
| |
| This section describes how to open a directory stream. All the symbols |
| are declared in the header file `dirent.h'. |
| |
| -- Data Type: DIR |
| The `DIR' data type represents a directory stream. |
| |
| You shouldn't ever allocate objects of the `struct dirent' or `DIR' |
| data types, since the directory access functions do that for you. |
| Instead, you refer to these objects using the pointers returned by the |
| following functions. |
| |
| Directory streams are a high-level interface. On Linux, alternative |
| interfaces for accessing directories using file descriptors are |
| available. *Note Low-level Directory Access::. |
| |
| -- Function: DIR * opendir (const char *DIRNAME) |
| Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | *Note |
| POSIX Safety Concepts::. |
| |
| The `opendir' function opens and returns a directory stream for |
| reading the directory whose file name is DIRNAME. The stream has |
| type `DIR *'. |
| |
| If unsuccessful, `opendir' returns a null pointer. In addition to |
| the usual file name errors (*note File Name Errors::), the |
| following `errno' error conditions are defined for this function: |
| |
| `EACCES' |
| Read permission is denied for the directory named by |
| `dirname'. |
| |
| `EMFILE' |
| The process has too many files open. |
| |
| `ENFILE' |
| The entire system, or perhaps the file system which contains |
| the directory, cannot support any additional open files at |
| the moment. (This problem cannot happen on GNU/Hurd systems.) |
| |
| `ENOMEM' |
| Not enough memory available. |
| |
| The `DIR' type is typically implemented using a file descriptor, |
| and the `opendir' function in terms of the `open' function. *Note |
| Low-Level I/O::. Directory streams and the underlying file |
| descriptors are closed on `exec' (*note Executing a File::). |
| |
| The directory which is opened for reading by `opendir' is identified |
| by the name. In some situations this is not sufficient. Or the way |
| `opendir' implicitly creates a file descriptor for the directory is not |
| the way a program might want it. In these cases an alternative |
| interface can be used. |
| |
| -- Function: DIR * fdopendir (int FD) |
| Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | *Note |
| POSIX Safety Concepts::. |
| |
| The `fdopendir' function works just like `opendir' but instead of |
| taking a file name and opening a file descriptor for the directory |
| the caller is required to provide a file descriptor. This file |
| descriptor is then used in subsequent uses of the returned |
| directory stream object. |
| |
| The caller must make sure the file descriptor is associated with a |
| directory and it allows reading. |
| |
| If the `fdopendir' call returns successfully the file descriptor |
| is now under the control of the system. It can be used in the same |
| way the descriptor implicitly created by `opendir' can be used but |
| the program must not close the descriptor. |
| |
| In case the function is unsuccessful it returns a null pointer and |
| the file descriptor remains to be usable by the program. The |
| following `errno' error conditions are defined for this function: |
| |
| `EBADF' |
| The file descriptor is not valid. |
| |
| `ENOTDIR' |
| The file descriptor is not associated with a directory. |
| |
| `EINVAL' |
| The descriptor does not allow reading the directory content. |
| |
| `ENOMEM' |
| Not enough memory available. |
| |
| In some situations it can be desirable to get hold of the file |
| descriptor which is created by the `opendir' call. For instance, to |
| switch the current working directory to the directory just read the |
| `fchdir' function could be used. Historically the `DIR' type was |
| exposed and programs could access the fields. This does not happen in |
| the GNU C Library. Instead a separate function is provided to allow |
| access. |
| |
| -- Function: int dirfd (DIR *DIRSTREAM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The function `dirfd' returns the file descriptor associated with |
| the directory stream DIRSTREAM. This descriptor can be used until |
| the directory is closed with `closedir'. If the directory stream |
| implementation is not using file descriptors the return value is |
| `-1'. |
| |
| |
| File: libc.info, Node: Reading/Closing Directory, Next: Simple Directory Lister, Prev: Opening a Directory, Up: Accessing Directories |
| |
| 14.2.3 Reading and Closing a Directory Stream |
| --------------------------------------------- |
| |
| This section describes how to read directory entries from a directory |
| stream, and how to close the stream when you are done with it. All the |
| symbols are declared in the header file `dirent.h'. |
| |
| -- Function: struct dirent * readdir (DIR *DIRSTREAM) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| This function reads the next entry from the directory. It normally |
| returns a pointer to a structure containing information about the |
| file. This structure is associated with the DIRSTREAM handle and |
| can be rewritten by a subsequent call. |
| |
| *Portability Note:* On some systems `readdir' may not return |
| entries for `.' and `..', even though these are always valid file |
| names in any directory. *Note File Name Resolution::. |
| |
| If there are no more entries in the directory or an error is |
| detected, `readdir' returns a null pointer. The following `errno' |
| error conditions are defined for this function: |
| |
| `EBADF' |
| The DIRSTREAM argument is not valid. |
| |
| To distinguish between an end-of-directory condition or an error, |
| you must set `errno' to zero before calling `readdir'. To avoid |
| entering an infinite loop, you should stop reading from the |
| directory after the first error. |
| |
| *Caution:* The pointer returned by `readdir' points to a buffer |
| within the `DIR' object. The data in that buffer will be |
| overwritten by the next call to `readdir'. You must take care, |
| for instance, to copy the `d_name' string if you need it later. |
| |
| Because of this, it is not safe to share a `DIR' object among |
| multiple threads, unless you use your own locking to ensure that |
| no thread calls `readdir' while another thread is still using the |
| data from the previous call. In the GNU C Library, it is safe to |
| call `readdir' from multiple threads as long as each thread uses |
| its own `DIR' object. POSIX.1-2008 does not require this to be |
| safe, but we are not aware of any operating systems where it does |
| not work. |
| |
| `readdir_r' allows you to provide your own buffer for the `struct |
| dirent', but it is less portable than `readdir', and has problems |
| with very long filenames (see below). We recommend you use |
| `readdir', but do not share `DIR' objects. |
| |
| -- Function: int readdir_r (DIR *DIRSTREAM, struct dirent *ENTRY, |
| struct dirent **RESULT) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| This function is a version of `readdir' which performs internal |
| locking. Like `readdir' it returns the next entry from the |
| directory. To prevent conflicts between simultaneously running |
| threads the result is stored inside the ENTRY object. |
| |
| *Portability Note:* `readdir_r' is deprecated. It is recommended |
| to use `readdir' instead of `readdir_r' for the following reasons: |
| |
| * On systems which do not define `NAME_MAX', it may not be |
| possible to use `readdir_r' safely because the caller does |
| not specify the length of the buffer for the directory entry. |
| |
| * On some systems, `readdir_r' cannot read directory entries |
| with very long names. If such a name is encountered, the GNU |
| C Library implementation of `readdir_r' returns with an error |
| code of `ENAMETOOLONG' after the final directory entry has |
| been read. On other systems, `readdir_r' may return |
| successfully, but the `d_name' member may not be |
| NUL-terminated or may be truncated. |
| |
| * POSIX-1.2008 does not guarantee that `readdir' is thread-safe, |
| even when access to the same DIRSTREAM is serialized. But in |
| current implementations (including the GNU C Library), it is |
| safe to call `readdir' concurrently on different DIRSTREAMs, |
| so there is no need to use `readdir_r' in most multi-threaded |
| programs. In the rare case that multiple threads need to |
| read from the same DIRSTREAM, it is still better to use |
| `readdir' and external synchronization. |
| |
| * It is expected that future versions of POSIX will obsolete |
| `readdir_r' and mandate the level of thread safety for |
| `readdir' which is provided by the GNU C Library and other |
| implementations today. |
| |
| Normally `readdir_r' returns zero and sets `*RESULT' to ENTRY. If |
| there are no more entries in the directory or an error is |
| detected, `readdir_r' sets `*RESULT' to a null pointer and returns |
| a nonzero error code, also stored in `errno', as described for |
| `readdir'. |
| |
| It is also important to look at the definition of the `struct |
| dirent' type. Simply passing a pointer to an object of this type |
| for the second parameter of `readdir_r' might not be enough. Some |
| systems don't define the `d_name' element sufficiently long. In |
| this case the user has to provide additional space. There must be |
| room for at least `NAME_MAX + 1' characters in the `d_name' array. |
| Code to call `readdir_r' could look like this: |
| |
| union |
| { |
| struct dirent d; |
| char b[offsetof (struct dirent, d_name) + NAME_MAX + 1]; |
| } u; |
| |
| if (readdir_r (dir, &u.d, &res) == 0) |
| ... |
| |
| To support large filesystems on 32-bit machines there are LFS |
| variants of the last two functions. |
| |
| -- Function: struct dirent64 * readdir64 (DIR *DIRSTREAM) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| The `readdir64' function is just like the `readdir' function |
| except that it returns a pointer to a record of type `struct |
| dirent64'. Some of the members of this data type (notably `d_ino') |
| might have a different size to allow large filesystems. |
| |
| In all other aspects this function is equivalent to `readdir'. |
| |
| -- Function: int readdir64_r (DIR *DIRSTREAM, struct dirent64 *ENTRY, |
| struct dirent64 **RESULT) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| The deprecated `readdir64_r' function is equivalent to the |
| `readdir_r' function except that it takes parameters of base type |
| `struct dirent64' instead of `struct dirent' in the second and |
| third position. The same precautions mentioned in the |
| documentation of `readdir_r' also apply here. |
| |
| -- Function: int closedir (DIR *DIRSTREAM) |
| Preliminary: | MT-Safe | AS-Unsafe heap lock/hurd | AC-Unsafe mem |
| fd lock/hurd | *Note POSIX Safety Concepts::. |
| |
| This function closes the directory stream DIRSTREAM. It returns |
| `0' on success and `-1' on failure. |
| |
| The following `errno' error conditions are defined for this |
| function: |
| |
| `EBADF' |
| The DIRSTREAM argument is not valid. |
| |
| |
| File: libc.info, Node: Simple Directory Lister, Next: Random Access Directory, Prev: Reading/Closing Directory, Up: Accessing Directories |
| |
| 14.2.4 Simple Program to List a Directory |
| ----------------------------------------- |
| |
| Here's a simple program that prints the names of the files in the |
| current working directory: |
| |
| |
| #include <stdio.h> |
| #include <sys/types.h> |
| #include <dirent.h> |
| |
| int |
| main (void) |
| { |
| DIR *dp; |
| struct dirent *ep; |
| |
| dp = opendir ("./"); |
| if (dp != NULL) |
| { |
| while (ep = readdir (dp)) |
| puts (ep->d_name); |
| (void) closedir (dp); |
| } |
| else |
| perror ("Couldn't open the directory"); |
| |
| return 0; |
| } |
| |
| The order in which files appear in a directory tends to be fairly |
| random. A more useful program would sort the entries (perhaps by |
| alphabetizing them) before printing them; see *note Scanning Directory |
| Content::, and *note Array Sort Function::. |
| |
| |
| File: libc.info, Node: Random Access Directory, Next: Scanning Directory Content, Prev: Simple Directory Lister, Up: Accessing Directories |
| |
| 14.2.5 Random Access in a Directory Stream |
| ------------------------------------------ |
| |
| This section describes how to reread parts of a directory that you have |
| already read from an open directory stream. All the symbols are |
| declared in the header file `dirent.h'. |
| |
| -- Function: void rewinddir (DIR *DIRSTREAM) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| The `rewinddir' function is used to reinitialize the directory |
| stream DIRSTREAM, so that if you call `readdir' it returns |
| information about the first entry in the directory again. This |
| function also notices if files have been added or removed to the |
| directory since it was opened with `opendir'. (Entries for these |
| files might or might not be returned by `readdir' if they were |
| added or removed since you last called `opendir' or `rewinddir'.) |
| |
| -- Function: long int telldir (DIR *DIRSTREAM) |
| Preliminary: | MT-Safe | AS-Unsafe heap/bsd lock/bsd | AC-Unsafe |
| mem/bsd lock/bsd | *Note POSIX Safety Concepts::. |
| |
| The `telldir' function returns the file position of the directory |
| stream DIRSTREAM. You can use this value with `seekdir' to |
| restore the directory stream to that position. |
| |
| -- Function: void seekdir (DIR *DIRSTREAM, long int POS) |
| Preliminary: | MT-Safe | AS-Unsafe heap/bsd lock/bsd | AC-Unsafe |
| mem/bsd lock/bsd | *Note POSIX Safety Concepts::. |
| |
| The `seekdir' function sets the file position of the directory |
| stream DIRSTREAM to POS. The value POS must be the result of a |
| previous call to `telldir' on this particular stream; closing and |
| reopening the directory can invalidate values returned by |
| `telldir'. |
| |
| |
| File: libc.info, Node: Scanning Directory Content, Next: Simple Directory Lister Mark II, Prev: Random Access Directory, Up: Accessing Directories |
| |
| 14.2.6 Scanning the Content of a Directory |
| ------------------------------------------ |
| |
| A higher-level interface to the directory handling functions is the |
| `scandir' function. With its help one can select a subset of the |
| entries in a directory, possibly sort them and get a list of names as |
| the result. |
| |
| -- Function: int scandir (const char *DIR, struct dirent ***NAMELIST, |
| int (*SELECTOR) (const struct dirent *), int (*CMP) (const |
| struct dirent **, const struct dirent **)) |
| Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | *Note |
| POSIX Safety Concepts::. |
| |
| The `scandir' function scans the contents of the directory selected |
| by DIR. The result in *NAMELIST is an array of pointers to |
| structures of type `struct dirent' which describe all selected |
| directory entries and which is allocated using `malloc'. Instead |
| of always getting all directory entries returned, the user supplied |
| function SELECTOR can be used to decide which entries are in the |
| result. Only the entries for which SELECTOR returns a non-zero |
| value are selected. |
| |
| Finally the entries in *NAMELIST are sorted using the |
| user-supplied function CMP. The arguments passed to the CMP |
| function are of type `struct dirent **', therefore one cannot |
| directly use the `strcmp' or `strcoll' functions; instead see the |
| functions `alphasort' and `versionsort' below. |
| |
| The return value of the function is the number of entries placed in |
| *NAMELIST. If it is `-1' an error occurred (either the directory |
| could not be opened for reading or the malloc call failed) and the |
| global variable `errno' contains more information on the error. |
| |
| As described above, the fourth argument to the `scandir' function |
| must be a pointer to a sorting function. For the convenience of the |
| programmer the GNU C Library contains implementations of functions which |
| are very helpful for this purpose. |
| |
| -- Function: int alphasort (const struct dirent **A, const struct |
| dirent **B) |
| Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem | |
| *Note POSIX Safety Concepts::. |
| |
| The `alphasort' function behaves like the `strcoll' function |
| (*note String/Array Comparison::). The difference is that the |
| arguments are not string pointers but instead they are of type |
| `struct dirent **'. |
| |
| The return value of `alphasort' is less than, equal to, or greater |
| than zero depending on the order of the two entries A and B. |
| |
| -- Function: int versionsort (const struct dirent **A, const struct |
| dirent **B) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The `versionsort' function is like `alphasort' except that it uses |
| the `strverscmp' function internally. |
| |
| If the filesystem supports large files we cannot use the `scandir' |
| anymore since the `dirent' structure might not able to contain all the |
| information. The LFS provides the new type `struct dirent64'. To use |
| this we need a new function. |
| |
| -- Function: int scandir64 (const char *DIR, struct dirent64 |
| ***NAMELIST, int (*SELECTOR) (const struct dirent64 *), int |
| (*CMP) (const struct dirent64 **, const struct dirent64 **)) |
| Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | *Note |
| POSIX Safety Concepts::. |
| |
| The `scandir64' function works like the `scandir' function except |
| that the directory entries it returns are described by elements of |
| type `struct dirent64'. The function pointed to by SELECTOR is |
| again used to select the desired entries, except that SELECTOR now |
| must point to a function which takes a `struct dirent64 *' |
| parameter. |
| |
| Similarly the CMP function should expect its two arguments to be |
| of type `struct dirent64 **'. |
| |
| As CMP is now a function of a different type, the functions |
| `alphasort' and `versionsort' cannot be supplied for that argument. |
| Instead we provide the two replacement functions below. |
| |
| -- Function: int alphasort64 (const struct dirent64 **A, const struct |
| dirent **B) |
| Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem | |
| *Note POSIX Safety Concepts::. |
| |
| The `alphasort64' function behaves like the `strcoll' function |
| (*note String/Array Comparison::). The difference is that the |
| arguments are not string pointers but instead they are of type |
| `struct dirent64 **'. |
| |
| Return value of `alphasort64' is less than, equal to, or greater |
| than zero depending on the order of the two entries A and B. |
| |
| -- Function: int versionsort64 (const struct dirent64 **A, const |
| struct dirent64 **B) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The `versionsort64' function is like `alphasort64', excepted that |
| it uses the `strverscmp' function internally. |
| |
| It is important not to mix the use of `scandir' and the 64-bit |
| comparison functions or vice versa. There are systems on which this |
| works but on others it will fail miserably. |
| |
| |
| File: libc.info, Node: Simple Directory Lister Mark II, Next: Low-level Directory Access, Prev: Scanning Directory Content, Up: Accessing Directories |
| |
| 14.2.7 Simple Program to List a Directory, Mark II |
| -------------------------------------------------- |
| |
| Here is a revised version of the directory lister found above (*note |
| Simple Directory Lister::). Using the `scandir' function we can avoid |
| the functions which work directly with the directory contents. After |
| the call the returned entries are available for direct use. |
| |
| |
| #include <stdio.h> |
| #include <dirent.h> |
| |
| static int |
| one (const struct dirent *unused) |
| { |
| return 1; |
| } |
| |
| int |
| main (void) |
| { |
| struct dirent **eps; |
| int n; |
| |
| n = scandir ("./", &eps, one, alphasort); |
| if (n >= 0) |
| { |
| int cnt; |
| for (cnt = 0; cnt < n; ++cnt) |
| puts (eps[cnt]->d_name); |
| } |
| else |
| perror ("Couldn't open the directory"); |
| |
| return 0; |
| } |
| |
| Note the simple selector function in this example. Since we want to |
| see all directory entries we always return `1'. |
| |
| |
| File: libc.info, Node: Low-level Directory Access, Prev: Simple Directory Lister Mark II, Up: Accessing Directories |
| |
| 14.2.8 Low-level Directory Access |
| --------------------------------- |
| |
| The stream-based directory functions are not AS-Safe and cannot be used |
| after `vfork'. *Note POSIX Safety Concepts::. The functions below |
| provide an alternative that can be used in these contexts. |
| |
| Directory data is obtained from a file descriptor, as created by the |
| `open' function, with or without the `O_DIRECTORY' flag. *Note Opening |
| and Closing Files::. |
| |
| -- Function: ssize_t getdents64 (int FD, void *BUFFER, size_t LENGTH) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `getdents64' function reads at most LENGTH bytes of directory |
| entry data from the file descriptor FD and stores it into the byte |
| array starting at BUFFER. |
| |
| On success, the function returns the number of bytes written to the |
| buffer. This number is zero if FD is already at the end of the |
| directory stream. On error, the function returns `-1' and sets |
| `errno' to the appropriate error code. |
| |
| The data is stored as a sequence of `struct dirent64' records, |
| which can be traversed using the `d_reclen' member. The buffer |
| should be large enough to hold the largest possible directory |
| entry. Note that some file systems support file names longer than |
| `NAME_MAX' bytes (e.g., because they support up to 255 Unicode |
| characters), so a buffer size of at least 1024 is recommended. |
| |
| This function is specific to Linux. |
| |
| |
| File: libc.info, Node: Working with Directory Trees, Next: Hard Links, Prev: Accessing Directories, Up: File System Interface |
| |
| 14.3 Working with Directory Trees |
| ================================= |
| |
| The functions described so far for handling the files in a directory |
| have allowed you to either retrieve the information bit by bit, or to |
| process all the files as a group (see `scandir'). Sometimes it is |
| useful to process whole hierarchies of directories and their contained |
| files. The X/Open specification defines two functions to do this. The |
| simpler form is derived from an early definition in System V systems |
| and therefore this function is available on SVID-derived systems. The |
| prototypes and required definitions can be found in the `ftw.h' header. |
| |
| There are four functions in this family: `ftw', `nftw' and their |
| 64-bit counterparts `ftw64' and `nftw64'. These functions take as one |
| of their arguments a pointer to a callback function of the appropriate |
| type. |
| |
| -- Data Type: __ftw_func_t |
| int (*) (const char *, const struct stat *, int) |
| |
| The type of callback functions given to the `ftw' function. The |
| first parameter points to the file name, the second parameter to an |
| object of type `struct stat' which is filled in for the file named |
| in the first parameter. |
| |
| The last parameter is a flag giving more information about the |
| current file. It can have the following values: |
| |
| `FTW_F' |
| The item is either a normal file or a file which does not fit |
| into one of the following categories. This could be special |
| files, sockets etc. |
| |
| `FTW_D' |
| The item is a directory. |
| |
| `FTW_NS' |
| The `stat' call failed and so the information pointed to by |
| the second parameter is invalid. |
| |
| `FTW_DNR' |
| The item is a directory which cannot be read. |
| |
| `FTW_SL' |
| The item is a symbolic link. Since symbolic links are |
| normally followed seeing this value in a `ftw' callback |
| function means the referenced file does not exist. The |
| situation for `nftw' is different. |
| |
| This value is only available if the program is compiled with |
| `_XOPEN_EXTENDED' defined before including the first header. |
| The original SVID systems do not have symbolic links. |
| |
| If the sources are compiled with `_FILE_OFFSET_BITS == 64' this |
| type is in fact `__ftw64_func_t' since this mode changes `struct |
| stat' to be `struct stat64'. |
| |
| For the LFS interface and for use in the function `ftw64', the |
| header `ftw.h' defines another function type. |
| |
| -- Data Type: __ftw64_func_t |
| int (*) (const char *, const struct stat64 *, int) |
| |
| This type is used just like `__ftw_func_t' for the callback |
| function, but this time is called from `ftw64'. The second |
| parameter to the function is a pointer to a variable of type |
| `struct stat64' which is able to represent the larger values. |
| |
| -- Data Type: __nftw_func_t |
| int (*) (const char *, const struct stat *, int, struct FTW *) |
| |
| The first three arguments are the same as for the `__ftw_func_t' |
| type. However for the third argument some additional values are |
| defined to allow finer differentiation: |
| `FTW_DP' |
| The current item is a directory and all subdirectories have |
| already been visited and reported. This flag is returned |
| instead of `FTW_D' if the `FTW_DEPTH' flag is passed to |
| `nftw' (see below). |
| |
| `FTW_SLN' |
| The current item is a stale symbolic link. The file it |
| points to does not exist. |
| |
| The last parameter of the callback function is a pointer to a |
| structure with some extra information as described below. |
| |
| If the sources are compiled with `_FILE_OFFSET_BITS == 64' this |
| type is in fact `__nftw64_func_t' since this mode changes `struct |
| stat' to be `struct stat64'. |
| |
| For the LFS interface there is also a variant of this data type |
| available which has to be used with the `nftw64' function. |
| |
| -- Data Type: __nftw64_func_t |
| int (*) (const char *, const struct stat64 *, int, struct FTW *) |
| |
| This type is used just like `__nftw_func_t' for the callback |
| function, but this time is called from `nftw64'. The second |
| parameter to the function is this time a pointer to a variable of |
| type `struct stat64' which is able to represent the larger values. |
| |
| -- Data Type: struct FTW |
| The information contained in this structure helps in interpreting |
| the name parameter and gives some information about the current |
| state of the traversal of the directory hierarchy. |
| |
| `int base' |
| The value is the offset into the string passed in the first |
| parameter to the callback function of the beginning of the |
| file name. The rest of the string is the path of the file. |
| This information is especially important if the `FTW_CHDIR' |
| flag was set in calling `nftw' since then the current |
| directory is the one the current item is found in. |
| |
| `int level' |
| Whilst processing, the code tracks how many directories down |
| it has gone to find the current file. This nesting level |
| starts at 0 for files in the initial directory (or is zero |
| for the initial file if a file was passed). |
| |
| -- Function: int ftw (const char *FILENAME, __ftw_func_t FUNC, int |
| DESCRIPTORS) |
| Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | *Note |
| POSIX Safety Concepts::. |
| |
| The `ftw' function calls the callback function given in the |
| parameter FUNC for every item which is found in the directory |
| specified by FILENAME and all directories below. The function |
| follows symbolic links if necessary but does not process an item |
| twice. If FILENAME is not a directory then it itself is the only |
| object returned to the callback function. |
| |
| The file name passed to the callback function is constructed by |
| taking the FILENAME parameter and appending the names of all passed |
| directories and then the local file name. So the callback |
| function can use this parameter to access the file. `ftw' also |
| calls `stat' for the file and passes that information on to the |
| callback function. If this `stat' call is not successful the |
| failure is indicated by setting the third argument of the callback |
| function to `FTW_NS'. Otherwise it is set according to the |
| description given in the account of `__ftw_func_t' above. |
| |
| The callback function is expected to return 0 to indicate that no |
| error occurred and that processing should continue. If an error |
| occurred in the callback function or it wants `ftw' to return |
| immediately, the callback function can return a value other than |
| 0. This is the only correct way to stop the function. The |
| program must not use `setjmp' or similar techniques to continue |
| from another place. This would leave resources allocated by the |
| `ftw' function unfreed. |
| |
| The DESCRIPTORS parameter to `ftw' specifies how many file |
| descriptors it is allowed to consume. The function runs faster |
| the more descriptors it can use. For each level in the directory |
| hierarchy at most one descriptor is used, but for very deep ones |
| any limit on open file descriptors for the process or the system |
| may be exceeded. Moreover, file descriptor limits in a |
| multi-threaded program apply to all the threads as a group, and |
| therefore it is a good idea to supply a reasonable limit to the |
| number of open descriptors. |
| |
| The return value of the `ftw' function is 0 if all callback |
| function calls returned 0 and all actions performed by the `ftw' |
| succeeded. If a function call failed (other than calling `stat' |
| on an item) the function returns -1. If a callback function |
| returns a value other than 0 this value is returned as the return |
| value of `ftw'. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' on a |
| 32-bit system this function is in fact `ftw64', i.e., the LFS |
| interface transparently replaces the old interface. |
| |
| -- Function: int ftw64 (const char *FILENAME, __ftw64_func_t FUNC, int |
| DESCRIPTORS) |
| Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | *Note |
| POSIX Safety Concepts::. |
| |
| This function is similar to `ftw' but it can work on filesystems |
| with large files. File information is reported using a variable |
| of type `struct stat64' which is passed by reference to the |
| callback function. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' on a |
| 32-bit system this function is available under the name `ftw' and |
| transparently replaces the old implementation. |
| |
| -- Function: int nftw (const char *FILENAME, __nftw_func_t FUNC, int |
| DESCRIPTORS, int FLAG) |
| Preliminary: | MT-Safe cwd | AS-Unsafe heap | AC-Unsafe mem fd cwd |
| | *Note POSIX Safety Concepts::. |
| |
| The `nftw' function works like the `ftw' functions. They call the |
| callback function FUNC for all items found in the directory |
| FILENAME and below. At most DESCRIPTORS file descriptors are |
| consumed during the `nftw' call. |
| |
| One difference is that the callback function is of a different |
| type. It is of type `struct FTW *' and provides the callback |
| function with the extra information described above. |
| |
| A second difference is that `nftw' takes a fourth argument, which |
| is 0 or a bitwise-OR combination of any of the following values. |
| |
| `FTW_PHYS' |
| While traversing the directory symbolic links are not |
| followed. Instead symbolic links are reported using the |
| `FTW_SL' value for the type parameter to the callback |
| function. If the file referenced by a symbolic link does not |
| exist `FTW_SLN' is returned instead. |
| |
| `FTW_MOUNT' |
| The callback function is only called for items which are on |
| the same mounted filesystem as the directory given by the |
| FILENAME parameter to `nftw'. |
| |
| `FTW_CHDIR' |
| If this flag is given the current working directory is |
| changed to the directory of the reported object before the |
| callback function is called. When `ntfw' finally returns the |
| current directory is restored to its original value. |
| |
| `FTW_DEPTH' |
| If this option is specified then all subdirectories and files |
| within them are processed before processing the top directory |
| itself (depth-first processing). This also means the type |
| flag given to the callback function is `FTW_DP' and not |
| `FTW_D'. |
| |
| `FTW_ACTIONRETVAL' |
| If this option is specified then return values from callbacks |
| are handled differently. If the callback returns |
| `FTW_CONTINUE', walking continues normally. `FTW_STOP' means |
| walking stops and `FTW_STOP' is returned to the caller. If |
| `FTW_SKIP_SUBTREE' is returned by the callback with `FTW_D' |
| argument, the subtree is skipped and walking continues with |
| next sibling of the directory. If `FTW_SKIP_SIBLINGS' is |
| returned by the callback, all siblings of the current entry |
| are skipped and walking continues in its parent. No other |
| return values should be returned from the callbacks if this |
| option is set. This option is a GNU extension. |
| |
| The return value is computed in the same way as for `ftw'. `nftw' |
| returns 0 if no failures occurred and all callback functions |
| returned 0. In case of internal errors, such as memory problems, |
| the return value is -1 and `errno' is set accordingly. If the |
| return value of a callback invocation was non-zero then that value |
| is returned. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' on a |
| 32-bit system this function is in fact `nftw64', i.e., the LFS |
| interface transparently replaces the old interface. |
| |
| -- Function: int nftw64 (const char *FILENAME, __nftw64_func_t FUNC, |
| int DESCRIPTORS, int FLAG) |
| Preliminary: | MT-Safe cwd | AS-Unsafe heap | AC-Unsafe mem fd cwd |
| | *Note POSIX Safety Concepts::. |
| |
| This function is similar to `nftw' but it can work on filesystems |
| with large files. File information is reported using a variable |
| of type `struct stat64' which is passed by reference to the |
| callback function. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' on a |
| 32-bit system this function is available under the name `nftw' and |
| transparently replaces the old implementation. |
| |
| |
| File: libc.info, Node: Hard Links, Next: Symbolic Links, Prev: Working with Directory Trees, Up: File System Interface |
| |
| 14.4 Hard Links |
| =============== |
| |
| In POSIX systems, one file can have many names at the same time. All of |
| the names are equally real, and no one of them is preferred to the |
| others. |
| |
| To add a name to a file, use the `link' function. (The new name is |
| also called a "hard link" to the file.) Creating a new link to a file |
| does not copy the contents of the file; it simply makes a new name by |
| which the file can be known, in addition to the file's existing name or |
| names. |
| |
| One file can have names in several directories, so the organization |
| of the file system is not a strict hierarchy or tree. |
| |
| In most implementations, it is not possible to have hard links to the |
| same file in multiple file systems. `link' reports an error if you try |
| to make a hard link to the file from another file system when this |
| cannot be done. |
| |
| The prototype for the `link' function is declared in the header file |
| `unistd.h'. |
| |
| -- Function: int link (const char *OLDNAME, const char *NEWNAME) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `link' function makes a new link to the existing file named by |
| OLDNAME, under the new name NEWNAME. |
| |
| This function returns a value of `0' if it is successful and `-1' |
| on failure. In addition to the usual file name errors (*note File |
| Name Errors::) for both OLDNAME and NEWNAME, the following `errno' |
| error conditions are defined for this function: |
| |
| `EACCES' |
| You are not allowed to write to the directory in which the |
| new link is to be written. |
| |
| `EEXIST' |
| There is already a file named NEWNAME. If you want to replace |
| this link with a new link, you must remove the old link |
| explicitly first. |
| |
| `EMLINK' |
| There are already too many links to the file named by OLDNAME. |
| (The maximum number of links to a file is `LINK_MAX'; see |
| *note Limits for Files::.) |
| |
| `ENOENT' |
| The file named by OLDNAME doesn't exist. You can't make a |
| link to a file that doesn't exist. |
| |
| `ENOSPC' |
| The directory or file system that would contain the new link |
| is full and cannot be extended. |
| |
| `EPERM' |
| On GNU/Linux and GNU/Hurd systems and some others, you cannot |
| make links to directories. Many systems allow only |
| privileged users to do so. This error is used to report the |
| problem. |
| |
| `EROFS' |
| The directory containing the new link can't be modified |
| because it's on a read-only file system. |
| |
| `EXDEV' |
| The directory specified in NEWNAME is on a different file |
| system than the existing file. |
| |
| `EIO' |
| A hardware error occurred while trying to read or write the |
| to filesystem. |
| |
| -- Function: int linkat (int oldfd, const char *OLDNAME, int newfd, |
| const char *NEWNAME, int flags) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `linkat' function is analogous to the `link' function, except |
| that it identifies its source and target using a combination of a |
| file descriptor (referring to a directory) and a pathname. If a |
| pathnames is not absolute, it is resolved relative to the |
| corresponding file descriptor. The special file descriptor |
| `AT_FDCWD' denotes the current directory. |
| |
| The FLAGS argument is a combination of the following flags: |
| |
| `AT_SYMLINK_FOLLOW' |
| If the source path identified by OLDFD and OLDNAME is a |
| symbolic link, `linkat' follows the symbolic link and creates |
| a link to its target. If the flag is not set, a link for the |
| symbolic link itself is created; this is not supported by all |
| file systems and `linkat' can fail in this case. |
| |
| `AT_EMPTY_PATH' |
| If this flag is specified, OLDNAME can be an empty string. In |
| this case, a new link to the file denoted by the descriptor |
| OLDFD is created, which may have been opened with `O_PATH' or |
| `O_TMPFILE'. This flag is a GNU extension. |
| |
| |
| File: libc.info, Node: Symbolic Links, Next: Deleting Files, Prev: Hard Links, Up: File System Interface |
| |
| 14.5 Symbolic Links |
| =================== |
| |
| GNU systems support "soft links" or "symbolic links". This is a kind |
| of "file" that is essentially a pointer to another file name. Unlike |
| hard links, symbolic links can be made to directories or across file |
| systems with no restrictions. You can also make a symbolic link to a |
| name which is not the name of any file. (Opening this link will fail |
| until a file by that name is created.) Likewise, if the symbolic link |
| points to an existing file which is later deleted, the symbolic link |
| continues to point to the same file name even though the name no longer |
| names any file. |
| |
| The reason symbolic links work the way they do is that special things |
| happen when you try to open the link. The `open' function realizes you |
| have specified the name of a link, reads the file name contained in the |
| link, and opens that file name instead. The `stat' function likewise |
| operates on the file that the symbolic link points to, instead of on |
| the link itself. |
| |
| By contrast, other operations such as deleting or renaming the file |
| operate on the link itself. The functions `readlink' and `lstat' also |
| refrain from following symbolic links, because their purpose is to |
| obtain information about the link. `link', the function that makes a |
| hard link, does too. It makes a hard link to the symbolic link, which |
| one rarely wants. |
| |
| Some systems have, for some functions operating on files, a limit on |
| how many symbolic links are followed when resolving a path name. The |
| limit if it exists is published in the `sys/param.h' header file. |
| |
| -- Macro: int MAXSYMLINKS |
| The macro `MAXSYMLINKS' specifies how many symlinks some function |
| will follow before returning `ELOOP'. Not all functions behave the |
| same and this value is not the same as that returned for |
| `_SC_SYMLOOP' by `sysconf'. In fact, the `sysconf' result can |
| indicate that there is no fixed limit although `MAXSYMLINKS' |
| exists and has a finite value. |
| |
| Prototypes for most of the functions listed in this section are in |
| `unistd.h'. |
| |
| -- Function: int symlink (const char *OLDNAME, const char *NEWNAME) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `symlink' function makes a symbolic link to OLDNAME named |
| NEWNAME. |
| |
| The normal return value from `symlink' is `0'. A return value of |
| `-1' indicates an error. In addition to the usual file name |
| syntax errors (*note File Name Errors::), the following `errno' |
| error conditions are defined for this function: |
| |
| `EEXIST' |
| There is already an existing file named NEWNAME. |
| |
| `EROFS' |
| The file NEWNAME would exist on a read-only file system. |
| |
| `ENOSPC' |
| The directory or file system cannot be extended to make the |
| new link. |
| |
| `EIO' |
| A hardware error occurred while reading or writing data on |
| the disk. |
| |
| |
| -- Function: ssize_t readlink (const char *FILENAME, char *BUFFER, |
| size_t SIZE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `readlink' function gets the value of the symbolic link |
| FILENAME. The file name that the link points to is copied into |
| BUFFER. This file name string is _not_ null-terminated; |
| `readlink' normally returns the number of characters copied. The |
| SIZE argument specifies the maximum number of characters to copy, |
| usually the allocation size of BUFFER. |
| |
| If the return value equals SIZE, you cannot tell whether or not |
| there was room to return the entire name. So make a bigger buffer |
| and call `readlink' again. Here is an example: |
| |
| char * |
| readlink_malloc (const char *filename) |
| { |
| int size = 100; |
| char *buffer = NULL; |
| |
| while (1) |
| { |
| buffer = (char *) xrealloc (buffer, size); |
| int nchars = readlink (filename, buffer, size); |
| if (nchars < 0) |
| { |
| free (buffer); |
| return NULL; |
| } |
| if (nchars < size) |
| return buffer; |
| size *= 2; |
| } |
| } |
| |
| A value of `-1' is returned in case of error. In addition to the |
| usual file name errors (*note File Name Errors::), the following |
| `errno' error conditions are defined for this function: |
| |
| `EINVAL' |
| The named file is not a symbolic link. |
| |
| `EIO' |
| A hardware error occurred while reading or writing data on |
| the disk. |
| |
| In some situations it is desirable to resolve all the symbolic links |
| to get the real name of a file where no prefix names a symbolic link |
| which is followed and no filename in the path is `.' or `..'. This is |
| for instance desirable if files have to be compared in which case |
| different names can refer to the same inode. |
| |
| -- Function: char * canonicalize_file_name (const char *NAME) |
| Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | *Note |
| POSIX Safety Concepts::. |
| |
| The `canonicalize_file_name' function returns the absolute name of |
| the file named by NAME which contains no `.', `..' components nor |
| any repeated path separators (`/') or symlinks. The result is |
| passed back as the return value of the function in a block of |
| memory allocated with `malloc'. If the result is not used anymore |
| the memory should be freed with a call to `free'. |
| |
| If any of the path components are missing the function returns a |
| NULL pointer. This is also what is returned if the length of the |
| path reaches or exceeds `PATH_MAX' characters. In any case |
| `errno' is set accordingly. |
| |
| `ENAMETOOLONG' |
| The resulting path is too long. This error only occurs on |
| systems which have a limit on the file name length. |
| |
| `EACCES' |
| At least one of the path components is not readable. |
| |
| `ENOENT' |
| The input file name is empty. |
| |
| `ENOENT' |
| At least one of the path components does not exist. |
| |
| `ELOOP' |
| More than `MAXSYMLINKS' many symlinks have been followed. |
| |
| This function is a GNU extension and is declared in `stdlib.h'. |
| |
| The Unix standard includes a similar function which differs from |
| `canonicalize_file_name' in that the user has to provide the buffer |
| where the result is placed in. |
| |
| -- Function: char * realpath (const char *restrict NAME, char |
| *restrict RESOLVED) |
| Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | *Note |
| POSIX Safety Concepts::. |
| |
| A call to `realpath' where the RESOLVED parameter is `NULL' |
| behaves exactly like `canonicalize_file_name'. The function |
| allocates a buffer for the file name and returns a pointer to it. |
| If RESOLVED is not `NULL' it points to a buffer into which the |
| result is copied. It is the callers responsibility to allocate a |
| buffer which is large enough. On systems which define `PATH_MAX' |
| this means the buffer must be large enough for a pathname of this |
| size. For systems without limitations on the pathname length the |
| requirement cannot be met and programs should not call `realpath' |
| with anything but `NULL' for the second parameter. |
| |
| One other difference is that the buffer RESOLVED (if nonzero) will |
| contain the part of the path component which does not exist or is |
| not readable if the function returns `NULL' and `errno' is set to |
| `EACCES' or `ENOENT'. |
| |
| This function is declared in `stdlib.h'. |
| |
| The advantage of using this function is that it is more widely |
| available. The drawback is that it reports failures for long paths on |
| systems which have no limits on the file name length. |
| |
| |
| File: libc.info, Node: Deleting Files, Next: Renaming Files, Prev: Symbolic Links, Up: File System Interface |
| |
| 14.6 Deleting Files |
| =================== |
| |
| You can delete a file with `unlink' or `remove'. |
| |
| Deletion actually deletes a file name. If this is the file's only |
| name, then the file is deleted as well. If the file has other |
| remaining names (*note Hard Links::), it remains accessible under those |
| names. |
| |
| -- Function: int unlink (const char *FILENAME) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `unlink' function deletes the file name FILENAME. If this is |
| a file's sole name, the file itself is also deleted. (Actually, |
| if any process has the file open when this happens, deletion is |
| postponed until all processes have closed the file.) |
| |
| The function `unlink' is declared in the header file `unistd.h'. |
| |
| This function returns `0' on successful completion, and `-1' on |
| error. In addition to the usual file name errors (*note File Name |
| Errors::), the following `errno' error conditions are defined for |
| this function: |
| |
| `EACCES' |
| Write permission is denied for the directory from which the |
| file is to be removed, or the directory has the sticky bit |
| set and you do not own the file. |
| |
| `EBUSY' |
| This error indicates that the file is being used by the |
| system in such a way that it can't be unlinked. For example, |
| you might see this error if the file name specifies the root |
| directory or a mount point for a file system. |
| |
| `ENOENT' |
| The file name to be deleted doesn't exist. |
| |
| `EPERM' |
| On some systems `unlink' cannot be used to delete the name of |
| a directory, or at least can only be used this way by a |
| privileged user. To avoid such problems, use `rmdir' to |
| delete directories. (On GNU/Linux and GNU/Hurd systems |
| `unlink' can never delete the name of a directory.) |
| |
| `EROFS' |
| The directory containing the file name to be deleted is on a |
| read-only file system and can't be modified. |
| |
| -- Function: int rmdir (const char *FILENAME) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `rmdir' function deletes a directory. The directory must be |
| empty before it can be removed; in other words, it can only contain |
| entries for `.' and `..'. |
| |
| In most other respects, `rmdir' behaves like `unlink'. There are |
| two additional `errno' error conditions defined for `rmdir': |
| |
| `ENOTEMPTY' |
| `EEXIST' |
| The directory to be deleted is not empty. |
| |
| These two error codes are synonymous; some systems use one, and |
| some use the other. GNU/Linux and GNU/Hurd systems always use |
| `ENOTEMPTY'. |
| |
| The prototype for this function is declared in the header file |
| `unistd.h'. |
| |
| -- Function: int remove (const char *FILENAME) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This is the ISO C function to remove a file. It works like |
| `unlink' for files and like `rmdir' for directories. `remove' is |
| declared in `stdio.h'. |
| |
| |
| File: libc.info, Node: Renaming Files, Next: Creating Directories, Prev: Deleting Files, Up: File System Interface |
| |
| 14.7 Renaming Files |
| =================== |
| |
| The `rename' function is used to change a file's name. |
| |
| -- Function: int rename (const char *OLDNAME, const char *NEWNAME) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `rename' function renames the file OLDNAME to NEWNAME. The |
| file formerly accessible under the name OLDNAME is afterwards |
| accessible as NEWNAME instead. (If the file had any other names |
| aside from OLDNAME, it continues to have those names.) |
| |
| The directory containing the name NEWNAME must be on the same file |
| system as the directory containing the name OLDNAME. |
| |
| One special case for `rename' is when OLDNAME and NEWNAME are two |
| names for the same file. The consistent way to handle this case |
| is to delete OLDNAME. However, in this case POSIX requires that |
| `rename' do nothing and report success--which is inconsistent. We |
| don't know what your operating system will do. |
| |
| If OLDNAME is not a directory, then any existing file named |
| NEWNAME is removed during the renaming operation. However, if |
| NEWNAME is the name of a directory, `rename' fails in this case. |
| |
| If OLDNAME is a directory, then either NEWNAME must not exist or |
| it must name a directory that is empty. In the latter case, the |
| existing directory named NEWNAME is deleted first. The name |
| NEWNAME must not specify a subdirectory of the directory `oldname' |
| which is being renamed. |
| |
| One useful feature of `rename' is that the meaning of NEWNAME |
| changes "atomically" from any previously existing file by that |
| name to its new meaning (i.e., the file that was called OLDNAME). |
| There is no instant at which NEWNAME is non-existent "in between" |
| the old meaning and the new meaning. If there is a system crash |
| during the operation, it is possible for both names to still |
| exist; but NEWNAME will always be intact if it exists at all. |
| |
| If `rename' fails, it returns `-1'. In addition to the usual file |
| name errors (*note File Name Errors::), the following `errno' |
| error conditions are defined for this function: |
| |
| `EACCES' |
| One of the directories containing NEWNAME or OLDNAME refuses |
| write permission; or NEWNAME and OLDNAME are directories and |
| write permission is refused for one of them. |
| |
| `EBUSY' |
| A directory named by OLDNAME or NEWNAME is being used by the |
| system in a way that prevents the renaming from working. |
| This includes directories that are mount points for |
| filesystems, and directories that are the current working |
| directories of processes. |
| |
| `ENOTEMPTY' |
| `EEXIST' |
| The directory NEWNAME isn't empty. GNU/Linux and GNU/Hurd |
| systems always return `ENOTEMPTY' for this, but some other |
| systems return `EEXIST'. |
| |
| `EINVAL' |
| OLDNAME is a directory that contains NEWNAME. |
| |
| `EISDIR' |
| NEWNAME is a directory but the OLDNAME isn't. |
| |
| `EMLINK' |
| The parent directory of NEWNAME would have too many links |
| (entries). |
| |
| `ENOENT' |
| The file OLDNAME doesn't exist. |
| |
| `ENOSPC' |
| The directory that would contain NEWNAME has no room for |
| another entry, and there is no space left in the file system |
| to expand it. |
| |
| `EROFS' |
| The operation would involve writing to a directory on a |
| read-only file system. |
| |
| `EXDEV' |
| The two file names NEWNAME and OLDNAME are on different file |
| systems. |
| |
| |
| File: libc.info, Node: Creating Directories, Next: File Attributes, Prev: Renaming Files, Up: File System Interface |
| |
| 14.8 Creating Directories |
| ========================= |
| |
| Directories are created with the `mkdir' function. (There is also a |
| shell command `mkdir' which does the same thing.) |
| |
| -- Function: int mkdir (const char *FILENAME, mode_t MODE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `mkdir' function creates a new, empty directory with name |
| FILENAME. |
| |
| The argument MODE specifies the file permissions for the new |
| directory file. *Note Permission Bits::, for more information |
| about this. |
| |
| A return value of `0' indicates successful completion, and `-1' |
| indicates failure. In addition to the usual file name syntax |
| errors (*note File Name Errors::), the following `errno' error |
| conditions are defined for this function: |
| |
| `EACCES' |
| Write permission is denied for the parent directory in which |
| the new directory is to be added. |
| |
| `EEXIST' |
| A file named FILENAME already exists. |
| |
| `EMLINK' |
| The parent directory has too many links (entries). |
| |
| Well-designed file systems never report this error, because |
| they permit more links than your disk could possibly hold. |
| However, you must still take account of the possibility of |
| this error, as it could result from network access to a file |
| system on another machine. |
| |
| `ENOSPC' |
| The file system doesn't have enough room to create the new |
| directory. |
| |
| `EROFS' |
| The parent directory of the directory being created is on a |
| read-only file system and cannot be modified. |
| |
| To use this function, your program should include the header file |
| `sys/stat.h'. |
| |
| |
| File: libc.info, Node: File Attributes, Next: Making Special Files, Prev: Creating Directories, Up: File System Interface |
| |
| 14.9 File Attributes |
| ==================== |
| |
| When you issue an `ls -l' shell command on a file, it gives you |
| information about the size of the file, who owns it, when it was last |
| modified, etc. These are called the "file attributes", and are |
| associated with the file itself and not a particular one of its names. |
| |
| This section contains information about how you can inquire about and |
| modify the attributes of a file. |
| |
| * Menu: |
| |
| * 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. |
| * Storage Allocation:: Allocate backing storage for files. |
| |
| |
| File: libc.info, Node: Attribute Meanings, Next: Reading Attributes, Up: File Attributes |
| |
| 14.9.1 The meaning of the File Attributes |
| ----------------------------------------- |
| |
| When you read the attributes of a file, they come back in a structure |
| called `struct stat'. This section describes the names of the |
| attributes, their data types, and what they mean. For the functions to |
| read the attributes of a file, see *note Reading Attributes::. |
| |
| The header file `sys/stat.h' declares all the symbols defined in |
| this section. |
| |
| -- Data Type: struct stat |
| The `stat' structure type is used to return information about the |
| attributes of a file. It contains at least the following members: |
| |
| `mode_t st_mode' |
| Specifies the mode of the file. This includes file type |
| information (*note Testing File Type::) and the file |
| permission bits (*note Permission Bits::). |
| |
| `ino_t st_ino' |
| The file serial number, which distinguishes this file from |
| all other files on the same device. |
| |
| `dev_t st_dev' |
| Identifies the device containing the file. The `st_ino' and |
| `st_dev', taken together, uniquely identify the file. The |
| `st_dev' value is not necessarily consistent across reboots or |
| system crashes, however. |
| |
| `nlink_t st_nlink' |
| The number of hard links to the file. This count keeps track |
| of how many directories have entries for this file. If the |
| count is ever decremented to zero, then the file itself is |
| discarded as soon as no process still holds it open. |
| Symbolic links are not counted in the total. |
| |
| `uid_t st_uid' |
| The user ID of the file's owner. *Note File Owner::. |
| |
| `gid_t st_gid' |
| The group ID of the file. *Note File Owner::. |
| |
| `off_t st_size' |
| This specifies the size of a regular file in bytes. For |
| files that are really devices this field isn't usually |
| meaningful. For symbolic links this specifies the length of |
| the file name the link refers to. |
| |
| `time_t st_atime' |
| This is the last access time for the file. *Note File |
| Times::. |
| |
| `unsigned long int st_atime_usec' |
| This is the fractional part of the last access time for the |
| file. *Note File Times::. |
| |
| `time_t st_mtime' |
| This is the time of the last modification to the contents of |
| the file. *Note File Times::. |
| |
| `unsigned long int st_mtime_usec' |
| This is the fractional part of the time of the last |
| modification to the contents of the file. *Note File Times::. |
| |
| `time_t st_ctime' |
| This is the time of the last modification to the attributes |
| of the file. *Note File Times::. |
| |
| `unsigned long int st_ctime_usec' |
| This is the fractional part of the time of the last |
| modification to the attributes of the file. *Note File |
| Times::. |
| |
| `blkcnt_t st_blocks' |
| This is the amount of disk space that the file occupies, |
| measured in units of 512-byte blocks. |
| |
| The number of disk blocks is not strictly proportional to the |
| size of the file, for two reasons: the file system may use |
| some blocks for internal record keeping; and the file may be |
| sparse--it may have "holes" which contain zeros but do not |
| actually take up space on the disk. |
| |
| You can tell (approximately) whether a file is sparse by |
| comparing this value with `st_size', like this: |
| |
| (st.st_blocks * 512 < st.st_size) |
| |
| This test is not perfect because a file that is just slightly |
| sparse might not be detected as sparse at all. For practical |
| applications, this is not a problem. |
| |
| `unsigned int st_blksize' |
| The optimal block size for reading or writing this file, in |
| bytes. You might use this size for allocating the buffer |
| space for reading or writing the file. (This is unrelated to |
| `st_blocks'.) |
| |
| The extensions for the Large File Support (LFS) require, even on |
| 32-bit machines, types which can handle file sizes up to 2^63. |
| Therefore a new definition of `struct stat' is necessary. |
| |
| -- Data Type: struct stat64 |
| The members of this type are the same and have the same names as |
| those in `struct stat'. The only difference is that the members |
| `st_ino', `st_size', and `st_blocks' have a different type to |
| support larger values. |
| |
| `mode_t st_mode' |
| Specifies the mode of the file. This includes file type |
| information (*note Testing File Type::) and the file |
| permission bits (*note Permission Bits::). |
| |
| `ino64_t st_ino' |
| The file serial number, which distinguishes this file from |
| all other files on the same device. |
| |
| `dev_t st_dev' |
| Identifies the device containing the file. The `st_ino' and |
| `st_dev', taken together, uniquely identify the file. The |
| `st_dev' value is not necessarily consistent across reboots or |
| system crashes, however. |
| |
| `nlink_t st_nlink' |
| The number of hard links to the file. This count keeps track |
| of how many directories have entries for this file. If the |
| count is ever decremented to zero, then the file itself is |
| discarded as soon as no process still holds it open. |
| Symbolic links are not counted in the total. |
| |
| `uid_t st_uid' |
| The user ID of the file's owner. *Note File Owner::. |
| |
| `gid_t st_gid' |
| The group ID of the file. *Note File Owner::. |
| |
| `off64_t st_size' |
| This specifies the size of a regular file in bytes. For |
| files that are really devices this field isn't usually |
| meaningful. For symbolic links this specifies the length of |
| the file name the link refers to. |
| |
| `time_t st_atime' |
| This is the last access time for the file. *Note File |
| Times::. |
| |
| `unsigned long int st_atime_usec' |
| This is the fractional part of the last access time for the |
| file. *Note File Times::. |
| |
| `time_t st_mtime' |
| This is the time of the last modification to the contents of |
| the file. *Note File Times::. |
| |
| `unsigned long int st_mtime_usec' |
| This is the fractional part of the time of the last |
| modification to the contents of the file. *Note File Times::. |
| |
| `time_t st_ctime' |
| This is the time of the last modification to the attributes |
| of the file. *Note File Times::. |
| |
| `unsigned long int st_ctime_usec' |
| This is the fractional part of the time of the last |
| modification to the attributes of the file. *Note File |
| Times::. |
| |
| `blkcnt64_t st_blocks' |
| This is the amount of disk space that the file occupies, |
| measured in units of 512-byte blocks. |
| |
| `unsigned int st_blksize' |
| The optimal block size for reading of writing this file, in |
| bytes. You might use this size for allocating the buffer |
| space for reading of writing the file. (This is unrelated to |
| `st_blocks'.) |
| |
| Some of the file attributes have special data type names which exist |
| specifically for those attributes. (They are all aliases for well-known |
| integer types that you know and love.) These typedef names are defined |
| in the header file `sys/types.h' as well as in `sys/stat.h'. Here is a |
| list of them. |
| |
| -- Data Type: mode_t |
| This is an integer data type used to represent file modes. In the |
| GNU C Library, this is an unsigned type no narrower than `unsigned |
| int'. |
| |
| -- Data Type: ino_t |
| This is an unsigned integer type used to represent file serial |
| numbers. (In Unix jargon, these are sometimes called "inode |
| numbers".) In the GNU C Library, this type is no narrower than |
| `unsigned int'. |
| |
| If the source is compiled with `_FILE_OFFSET_BITS == 64' this type |
| is transparently replaced by `ino64_t'. |
| |
| -- Data Type: ino64_t |
| This is an unsigned integer type used to represent file serial |
| numbers for the use in LFS. In the GNU C Library, this type is no |
| narrower than `unsigned int'. |
| |
| When compiling with `_FILE_OFFSET_BITS == 64' this type is |
| available under the name `ino_t'. |
| |
| -- Data Type: dev_t |
| This is an arithmetic data type used to represent file device |
| numbers. In the GNU C Library, this is an integer type no |
| narrower than `int'. |
| |
| -- Data Type: nlink_t |
| This is an integer type used to represent file link counts. |
| |
| -- Data Type: blkcnt_t |
| This is a signed integer type used to represent block counts. In |
| the GNU C Library, this type is no narrower than `int'. |
| |
| If the source is compiled with `_FILE_OFFSET_BITS == 64' this type |
| is transparently replaced by `blkcnt64_t'. |
| |
| -- Data Type: blkcnt64_t |
| This is a signed integer type used to represent block counts for |
| the use in LFS. In the GNU C Library, this type is no narrower |
| than `int'. |
| |
| When compiling with `_FILE_OFFSET_BITS == 64' this type is |
| available under the name `blkcnt_t'. |
| |
| |
| File: libc.info, Node: Reading Attributes, Next: Testing File Type, Prev: Attribute Meanings, Up: File Attributes |
| |
| 14.9.2 Reading the Attributes of a File |
| --------------------------------------- |
| |
| To examine the attributes of files, use the functions `stat', `fstat' |
| and `lstat'. They return the attribute information in a `struct stat' |
| object. All three functions are declared in the header file |
| `sys/stat.h'. |
| |
| -- Function: int stat (const char *FILENAME, struct stat *BUF) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `stat' function returns information about the attributes of the |
| file named by FILENAME in the structure pointed to by BUF. |
| |
| If FILENAME is the name of a symbolic link, the attributes you get |
| describe the file that the link points to. If the link points to a |
| nonexistent file name, then `stat' fails reporting a nonexistent |
| file. |
| |
| The return value is `0' if the operation is successful, or `-1' on |
| failure. In addition to the usual file name errors (*note File |
| Name Errors::, the following `errno' error conditions are defined |
| for this function: |
| |
| `ENOENT' |
| The file named by FILENAME doesn't exist. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' this |
| function is in fact `stat64' since the LFS interface transparently |
| replaces the normal implementation. |
| |
| -- Function: int stat64 (const char *FILENAME, struct stat64 *BUF) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to `stat' but it is also able to work on |
| files larger than 2^31 bytes on 32-bit systems. To be able to do |
| this the result is stored in a variable of type `struct stat64' to |
| which BUF must point. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' this |
| function is available under the name `stat' and so transparently |
| replaces the interface for small files on 32-bit machines. |
| |
| -- Function: int fstat (int FILEDES, struct stat *BUF) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `fstat' function is like `stat', except that it takes an open |
| file descriptor as an argument instead of a file name. *Note |
| Low-Level I/O::. |
| |
| Like `stat', `fstat' returns `0' on success and `-1' on failure. |
| The following `errno' error conditions are defined for `fstat': |
| |
| `EBADF' |
| The FILEDES argument is not a valid file descriptor. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' this |
| function is in fact `fstat64' since the LFS interface transparently |
| replaces the normal implementation. |
| |
| -- Function: int fstat64 (int FILEDES, struct stat64 *BUF) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to `fstat' but is able to work on large |
| files on 32-bit platforms. For large files the file descriptor |
| FILEDES should be obtained by `open64' or `creat64'. The BUF |
| pointer points to a variable of type `struct stat64' which is able |
| to represent the larger values. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' this |
| function is available under the name `fstat' and so transparently |
| replaces the interface for small files on 32-bit machines. |
| |
| -- Function: int lstat (const char *FILENAME, struct stat *BUF) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `lstat' function is like `stat', except that it does not |
| follow symbolic links. If FILENAME is the name of a symbolic |
| link, `lstat' returns information about the link itself; otherwise |
| `lstat' works like `stat'. *Note Symbolic Links::. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' this |
| function is in fact `lstat64' since the LFS interface transparently |
| replaces the normal implementation. |
| |
| -- Function: int lstat64 (const char *FILENAME, struct stat64 *BUF) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to `lstat' but it is also able to work on |
| files larger than 2^31 bytes on 32-bit systems. To be able to do |
| this the result is stored in a variable of type `struct stat64' to |
| which BUF must point. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' this |
| function is available under the name `lstat' and so transparently |
| replaces the interface for small files on 32-bit machines. |
| |
| |
| File: libc.info, Node: Testing File Type, Next: File Owner, Prev: Reading Attributes, Up: File Attributes |
| |
| 14.9.3 Testing the Type of a File |
| --------------------------------- |
| |
| The "file mode", stored in the `st_mode' field of the file attributes, |
| contains two kinds of information: the file type code, and the access |
| permission bits. This section discusses only the type code, which you |
| can use to tell whether the file is a directory, socket, symbolic link, |
| and so on. For details about access permissions see *note Permission |
| Bits::. |
| |
| There are two ways you can access the file type information in a file |
| mode. Firstly, for each file type there is a "predicate macro" which |
| examines a given file mode and returns whether it is of that type or |
| not. Secondly, you can mask out the rest of the file mode to leave |
| just the file type code, and compare this against constants for each of |
| the supported file types. |
| |
| All of the symbols listed in this section are defined in the header |
| file `sys/stat.h'. |
| |
| The following predicate macros test the type of a file, given the |
| value M which is the `st_mode' field returned by `stat' on that file: |
| |
| -- Macro: int S_ISDIR (mode_t M) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro returns non-zero if the file is a directory. |
| |
| -- Macro: int S_ISCHR (mode_t M) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro returns non-zero if the file is a character special |
| file (a device like a terminal). |
| |
| -- Macro: int S_ISBLK (mode_t M) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro returns non-zero if the file is a block special file (a |
| device like a disk). |
| |
| -- Macro: int S_ISREG (mode_t M) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro returns non-zero if the file is a regular file. |
| |
| -- Macro: int S_ISFIFO (mode_t M) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro returns non-zero if the file is a FIFO special file, or |
| a pipe. *Note Pipes and FIFOs::. |
| |
| -- Macro: int S_ISLNK (mode_t M) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro returns non-zero if the file is a symbolic link. *Note |
| Symbolic Links::. |
| |
| -- Macro: int S_ISSOCK (mode_t M) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro returns non-zero if the file is a socket. *Note |
| Sockets::. |
| |
| An alternate non-POSIX method of testing the file type is supported |
| for compatibility with BSD. The mode can be bitwise AND-ed with |
| `S_IFMT' to extract the file type code, and compared to the appropriate |
| constant. For example, |
| |
| S_ISCHR (MODE) |
| |
| is equivalent to: |
| |
| ((MODE & S_IFMT) == S_IFCHR) |
| |
| -- Macro: int S_IFMT |
| This is a bit mask used to extract the file type code from a mode |
| value. |
| |
| These are the symbolic names for the different file type codes: |
| |
| `S_IFDIR' |
| This is the file type constant of a directory file. |
| |
| `S_IFCHR' |
| This is the file type constant of a character-oriented device file. |
| |
| `S_IFBLK' |
| This is the file type constant of a block-oriented device file. |
| |
| `S_IFREG' |
| This is the file type constant of a regular file. |
| |
| `S_IFLNK' |
| This is the file type constant of a symbolic link. |
| |
| `S_IFSOCK' |
| This is the file type constant of a socket. |
| |
| `S_IFIFO' |
| This is the file type constant of a FIFO or pipe. |
| |
| The POSIX.1b standard introduced a few more objects which possibly |
| can be implemented as objects in the filesystem. These are message |
| queues, semaphores, and shared memory objects. To allow |
| differentiating these objects from other files the POSIX standard |
| introduced three new test macros. But unlike the other macros they do |
| not take the value of the `st_mode' field as the parameter. Instead |
| they expect a pointer to the whole `struct stat' structure. |
| |
| -- Macro: int S_TYPEISMQ (struct stat *S) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| If the system implements POSIX message queues as distinct objects |
| and the file is a message queue object, this macro returns a |
| non-zero value. In all other cases the result is zero. |
| |
| -- Macro: int S_TYPEISSEM (struct stat *S) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| If the system implements POSIX semaphores as distinct objects and |
| the file is a semaphore object, this macro returns a non-zero |
| value. In all other cases the result is zero. |
| |
| -- Macro: int S_TYPEISSHM (struct stat *S) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| If the system implements POSIX shared memory objects as distinct |
| objects and the file is a shared memory object, this macro returns |
| a non-zero value. In all other cases the result is zero. |
| |
| |
| File: libc.info, Node: File Owner, Next: Permission Bits, Prev: Testing File Type, Up: File Attributes |
| |
| 14.9.4 File Owner |
| ----------------- |
| |
| Every file has an "owner" which is one of the registered user names |
| defined on the system. Each file also has a "group" which is one of |
| the defined groups. The file owner can often be useful for showing you |
| who edited the file (especially when you edit with GNU Emacs), but its |
| main purpose is for access control. |
| |
| The file owner and group play a role in determining access because |
| the file has one set of access permission bits for the owner, another |
| set that applies to users who belong to the file's group, and a third |
| set of bits that applies to everyone else. *Note Access Permission::, |
| for the details of how access is decided based on this data. |
| |
| When a file is created, its owner is set to the effective user ID of |
| the process that creates it (*note Process Persona::). The file's |
| group ID may be set to either the effective group ID of the process, or |
| the group ID of the directory that contains the file, depending on the |
| system where the file is stored. When you access a remote file system, |
| it behaves according to its own rules, not according to the system your |
| program is running on. Thus, your program must be prepared to encounter |
| either kind of behavior no matter what kind of system you run it on. |
| |
| You can change the owner and/or group owner of an existing file using |
| the `chown' function. This is the primitive for the `chown' and |
| `chgrp' shell commands. |
| |
| The prototype for this function is declared in `unistd.h'. |
| |
| -- Function: int chown (const char *FILENAME, uid_t OWNER, gid_t GROUP) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `chown' function changes the owner of the file FILENAME to |
| OWNER, and its group owner to GROUP. |
| |
| Changing the owner of the file on certain systems clears the |
| set-user-ID and set-group-ID permission bits. (This is because |
| those bits may not be appropriate for the new owner.) Other file |
| permission bits are not changed. |
| |
| The return value is `0' on success and `-1' on failure. In |
| addition to the usual file name errors (*note File Name Errors::), |
| the following `errno' error conditions are defined for this |
| function: |
| |
| `EPERM' |
| This process lacks permission to make the requested change. |
| |
| Only privileged users or the file's owner can change the |
| file's group. On most file systems, only privileged users |
| can change the file owner; some file systems allow you to |
| change the owner if you are currently the owner. When you |
| access a remote file system, the behavior you encounter is |
| determined by the system that actually holds the file, not by |
| the system your program is running on. |
| |
| *Note Options for Files::, for information about the |
| `_POSIX_CHOWN_RESTRICTED' macro. |
| |
| `EROFS' |
| The file is on a read-only file system. |
| |
| -- Function: int fchown (int FILEDES, uid_t OWNER, gid_t GROUP) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This is like `chown', except that it changes the owner of the open |
| file with descriptor FILEDES. |
| |
| The return value from `fchown' is `0' on success and `-1' on |
| failure. The following `errno' error codes are defined for this |
| function: |
| |
| `EBADF' |
| The FILEDES argument is not a valid file descriptor. |
| |
| `EINVAL' |
| The FILEDES argument corresponds to a pipe or socket, not an |
| ordinary file. |
| |
| `EPERM' |
| This process lacks permission to make the requested change. |
| For details see `chmod' above. |
| |
| `EROFS' |
| The file resides on a read-only file system. |
| |
| |
| File: libc.info, Node: Permission Bits, Next: Access Permission, Prev: File Owner, Up: File Attributes |
| |
| 14.9.5 The Mode Bits for Access Permission |
| ------------------------------------------ |
| |
| The "file mode", stored in the `st_mode' field of the file attributes, |
| contains two kinds of information: the file type code, and the access |
| permission bits. This section discusses only the access permission |
| bits, which control who can read or write the file. *Note Testing File |
| Type::, for information about the file type code. |
| |
| All of the symbols listed in this section are defined in the header |
| file `sys/stat.h'. |
| |
| These symbolic constants are defined for the file mode bits that |
| control access permission for the file: |
| |
| `S_IRUSR' |
| `S_IREAD' |
| Read permission bit for the owner of the file. On many systems |
| this bit is 0400. `S_IREAD' is an obsolete synonym provided for |
| BSD compatibility. |
| |
| `S_IWUSR' |
| `S_IWRITE' |
| Write permission bit for the owner of the file. Usually 0200. |
| `S_IWRITE' is an obsolete synonym provided for BSD compatibility. |
| |
| `S_IXUSR' |
| `S_IEXEC' |
| Execute (for ordinary files) or search (for directories) |
| permission bit for the owner of the file. Usually 0100. |
| `S_IEXEC' is an obsolete synonym provided for BSD compatibility. |
| |
| `S_IRWXU' |
| This is equivalent to `(S_IRUSR | S_IWUSR | S_IXUSR)'. |
| |
| `S_IRGRP' |
| Read permission bit for the group owner of the file. Usually 040. |
| |
| `S_IWGRP' |
| Write permission bit for the group owner of the file. Usually 020. |
| |
| `S_IXGRP' |
| Execute or search permission bit for the group owner of the file. |
| Usually 010. |
| |
| `S_IRWXG' |
| This is equivalent to `(S_IRGRP | S_IWGRP | S_IXGRP)'. |
| |
| `S_IROTH' |
| Read permission bit for other users. Usually 04. |
| |
| `S_IWOTH' |
| Write permission bit for other users. Usually 02. |
| |
| `S_IXOTH' |
| Execute or search permission bit for other users. Usually 01. |
| |
| `S_IRWXO' |
| This is equivalent to `(S_IROTH | S_IWOTH | S_IXOTH)'. |
| |
| `S_ISUID' |
| This is the set-user-ID on execute bit, usually 04000. *Note How |
| Change Persona::. |
| |
| `S_ISGID' |
| This is the set-group-ID on execute bit, usually 02000. *Note How |
| Change Persona::. |
| |
| `S_ISVTX' |
| This is the "sticky" bit, usually 01000. |
| |
| For a directory it gives permission to delete a file in that |
| directory only if you own that file. Ordinarily, a user can |
| either delete all the files in a directory or cannot delete any of |
| them (based on whether the user has write permission for the |
| directory). The same restriction applies--you must have both |
| write permission for the directory and own the file you want to |
| delete. The one exception is that the owner of the directory can |
| delete any file in the directory, no matter who owns it (provided |
| the owner has given himself write permission for the directory). |
| This is commonly used for the `/tmp' directory, where anyone may |
| create files but not delete files created by other users. |
| |
| Originally the sticky bit on an executable file modified the |
| swapping policies of the system. Normally, when a program |
| terminated, its pages in core were immediately freed and reused. |
| If the sticky bit was set on the executable file, the system kept |
| the pages in core for a while as if the program were still |
| running. This was advantageous for a program likely to be run |
| many times in succession. This usage is obsolete in modern |
| systems. When a program terminates, its pages always remain in |
| core as long as there is no shortage of memory in the system. |
| When the program is next run, its pages will still be in core if |
| no shortage arose since the last run. |
| |
| On some modern systems where the sticky bit has no useful meaning |
| for an executable file, you cannot set the bit at all for a |
| non-directory. If you try, `chmod' fails with `EFTYPE'; *note |
| Setting Permissions::. |
| |
| Some systems (particularly SunOS) have yet another use for the |
| sticky bit. If the sticky bit is set on a file that is _not_ |
| executable, it means the opposite: never cache the pages of this |
| file at all. The main use of this is for the files on an NFS |
| server machine which are used as the swap area of diskless client |
| machines. The idea is that the pages of the file will be cached |
| in the client's memory, so it is a waste of the server's memory to |
| cache them a second time. With this usage the sticky bit also |
| implies that the filesystem may fail to record the file's |
| modification time onto disk reliably (the idea being that no-one |
| cares for a swap file). |
| |
| This bit is only available on BSD systems (and those derived from |
| them). Therefore one has to use the `_GNU_SOURCE' feature select |
| macro, or not define any feature test macros, to get the definition |
| (*note Feature Test Macros::). |
| |
| The actual bit values of the symbols are listed in the table above |
| so you can decode file mode values when debugging your programs. These |
| bit values are correct for most systems, but they are not guaranteed. |
| |
| *Warning:* Writing explicit numbers for file permissions is bad |
| practice. Not only is it not portable, it also requires everyone who |
| reads your program to remember what the bits mean. To make your program |
| clean use the symbolic names. |
| |
| |
| File: libc.info, Node: Access Permission, Next: Setting Permissions, Prev: Permission Bits, Up: File Attributes |
| |
| 14.9.6 How Your Access to a File is Decided |
| ------------------------------------------- |
| |
| Recall that the operating system normally decides access permission for |
| a file based on the effective user and group IDs of the process and its |
| supplementary group IDs, together with the file's owner, group and |
| permission bits. These concepts are discussed in detail in *note |
| Process Persona::. |
| |
| If the effective user ID of the process matches the owner user ID of |
| the file, then permissions for read, write, and execute/search are |
| controlled by the corresponding "user" (or "owner") bits. Likewise, if |
| any of the effective group ID or supplementary group IDs of the process |
| matches the group owner ID of the file, then permissions are controlled |
| by the "group" bits. Otherwise, permissions are controlled by the |
| "other" bits. |
| |
| Privileged users, like `root', can access any file regardless of its |
| permission bits. As a special case, for a file to be executable even |
| by a privileged user, at least one of its execute bits must be set. |
| |
| |
| File: libc.info, Node: Setting Permissions, Next: Testing File Access, Prev: Access Permission, Up: File Attributes |
| |
| 14.9.7 Assigning File Permissions |
| --------------------------------- |
| |
| The primitive functions for creating files (for example, `open' or |
| `mkdir') take a MODE argument, which specifies the file permissions to |
| give the newly created file. This mode is modified by the process's |
| "file creation mask", or "umask", before it is used. |
| |
| The bits that are set in the file creation mask identify permissions |
| that are always to be disabled for newly created files. For example, if |
| you set all the "other" access bits in the mask, then newly created |
| files are not accessible at all to processes in the "other" category, |
| even if the MODE argument passed to the create function would permit |
| such access. In other words, the file creation mask is the complement |
| of the ordinary access permissions you want to grant. |
| |
| Programs that create files typically specify a MODE argument that |
| includes all the permissions that make sense for the particular file. |
| For an ordinary file, this is typically read and write permission for |
| all classes of users. These permissions are then restricted as |
| specified by the individual user's own file creation mask. |
| |
| To change the permission of an existing file given its name, call |
| `chmod'. This function uses the specified permission bits and ignores |
| the file creation mask. |
| |
| In normal use, the file creation mask is initialized by the user's |
| login shell (using the `umask' shell command), and inherited by all |
| subprocesses. Application programs normally don't need to worry about |
| the file creation mask. It will automatically do what it is supposed to |
| do. |
| |
| When your program needs to create a file and bypass the umask for its |
| access permissions, the easiest way to do this is to use `fchmod' after |
| opening the file, rather than changing the umask. In fact, changing |
| the umask is usually done only by shells. They use the `umask' |
| function. |
| |
| The functions in this section are declared in `sys/stat.h'. |
| |
| -- Function: mode_t umask (mode_t MASK) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `umask' function sets the file creation mask of the current |
| process to MASK, and returns the previous value of the file |
| creation mask. |
| |
| Here is an example showing how to read the mask with `umask' |
| without changing it permanently: |
| |
| mode_t |
| read_umask (void) |
| { |
| mode_t mask = umask (0); |
| umask (mask); |
| return mask; |
| } |
| |
| However, on GNU/Hurd systems it is better to use `getumask' if you |
| just want to read the mask value, because it is reentrant. |
| |
| -- Function: mode_t getumask (void) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Return the current value of the file creation mask for the current |
| process. This function is a GNU extension and is only available on |
| GNU/Hurd systems. |
| |
| -- Function: int chmod (const char *FILENAME, mode_t MODE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `chmod' function sets the access permission bits for the file |
| named by FILENAME to MODE. |
| |
| If FILENAME is a symbolic link, `chmod' changes the permissions of |
| the file pointed to by the link, not those of the link itself. |
| |
| This function returns `0' if successful and `-1' if not. In |
| addition to the usual file name errors (*note File Name Errors::), |
| the following `errno' error conditions are defined for this |
| function: |
| |
| `ENOENT' |
| The named file doesn't exist. |
| |
| `EPERM' |
| This process does not have permission to change the access |
| permissions of this file. Only the file's owner (as judged |
| by the effective user ID of the process) or a privileged user |
| can change them. |
| |
| `EROFS' |
| The file resides on a read-only file system. |
| |
| `EFTYPE' |
| MODE has the `S_ISVTX' bit (the "sticky bit") set, and the |
| named file is not a directory. Some systems do not allow |
| setting the sticky bit on non-directory files, and some do |
| (and only some of those assign a useful meaning to the bit |
| for non-directory files). |
| |
| You only get `EFTYPE' on systems where the sticky bit has no |
| useful meaning for non-directory files, so it is always safe |
| to just clear the bit in MODE and call `chmod' again. *Note |
| Permission Bits::, for full details on the sticky bit. |
| |
| -- Function: int fchmod (int FILEDES, mode_t MODE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This is like `chmod', except that it changes the permissions of the |
| currently open file given by FILEDES. |
| |
| The return value from `fchmod' is `0' on success and `-1' on |
| failure. The following `errno' error codes are defined for this |
| function: |
| |
| `EBADF' |
| The FILEDES argument is not a valid file descriptor. |
| |
| `EINVAL' |
| The FILEDES argument corresponds to a pipe or socket, or |
| something else that doesn't really have access permissions. |
| |
| `EPERM' |
| This process does not have permission to change the access |
| permissions of this file. Only the file's owner (as judged |
| by the effective user ID of the process) or a privileged user |
| can change them. |
| |
| `EROFS' |
| The file resides on a read-only file system. |
| |
| |
| File: libc.info, Node: Testing File Access, Next: File Times, Prev: Setting Permissions, Up: File Attributes |
| |
| 14.9.8 Testing Permission to Access a File |
| ------------------------------------------ |
| |
| In some situations it is desirable to allow programs to access files or |
| devices even if this is not possible with the permissions granted to the |
| user. One possible solution is to set the setuid-bit of the program |
| file. If such a program is started the _effective_ user ID of the |
| process is changed to that of the owner of the program file. So to |
| allow write access to files like `/etc/passwd', which normally can be |
| written only by the super-user, the modifying program will have to be |
| owned by `root' and the setuid-bit must be set. |
| |
| But besides the files the program is intended to change the user |
| should not be allowed to access any file to which s/he would not have |
| access anyway. The program therefore must explicitly check whether _the |
| user_ would have the necessary access to a file, before it reads or |
| writes the file. |
| |
| To do this, use the function `access', which checks for access |
| permission based on the process's _real_ user ID rather than the |
| effective user ID. (The setuid feature does not alter the real user ID, |
| so it reflects the user who actually ran the program.) |
| |
| There is another way you could check this access, which is easy to |
| describe, but very hard to use. This is to examine the file mode bits |
| and mimic the system's own access computation. This method is |
| undesirable because many systems have additional access control |
| features; your program cannot portably mimic them, and you would not |
| want to try to keep track of the diverse features that different systems |
| have. Using `access' is simple and automatically does whatever is |
| appropriate for the system you are using. |
| |
| `access' is _only_ appropriate to use in setuid programs. A |
| non-setuid program will always use the effective ID rather than the |
| real ID. |
| |
| The symbols in this section are declared in `unistd.h'. |
| |
| -- Function: int access (const char *FILENAME, int HOW) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `access' function checks to see whether the file named by |
| FILENAME can be accessed in the way specified by the HOW argument. |
| The HOW argument either can be the bitwise OR of the flags `R_OK', |
| `W_OK', `X_OK', or the existence test `F_OK'. |
| |
| This function uses the _real_ user and group IDs of the calling |
| process, rather than the _effective_ IDs, to check for access |
| permission. As a result, if you use the function from a `setuid' |
| or `setgid' program (*note How Change Persona::), it gives |
| information relative to the user who actually ran the program. |
| |
| The return value is `0' if the access is permitted, and `-1' |
| otherwise. (In other words, treated as a predicate function, |
| `access' returns true if the requested access is _denied_.) |
| |
| In addition to the usual file name errors (*note File Name |
| Errors::), the following `errno' error conditions are defined for |
| this function: |
| |
| `EACCES' |
| The access specified by HOW is denied. |
| |
| `ENOENT' |
| The file doesn't exist. |
| |
| `EROFS' |
| Write permission was requested for a file on a read-only file |
| system. |
| |
| These macros are defined in the header file `unistd.h' for use as |
| the HOW argument to the `access' function. The values are integer |
| constants. |
| |
| -- Macro: int R_OK |
| Flag meaning test for read permission. |
| |
| -- Macro: int W_OK |
| Flag meaning test for write permission. |
| |
| -- Macro: int X_OK |
| Flag meaning test for execute/search permission. |
| |
| -- Macro: int F_OK |
| Flag meaning test for existence of the file. |
| |
| |
| File: libc.info, Node: File Times, Next: File Size, Prev: Testing File Access, Up: File Attributes |
| |
| 14.9.9 File Times |
| ----------------- |
| |
| Each file has three time stamps associated with it: its access time, |
| its modification time, and its attribute modification time. These |
| correspond to the `st_atime', `st_mtime', and `st_ctime' members of the |
| `stat' structure; see *note File Attributes::. |
| |
| All of these times are represented in calendar time format, as |
| `time_t' objects. This data type is defined in `time.h'. For more |
| information about representation and manipulation of time values, see |
| *note Calendar Time::. |
| |
| Reading from a file updates its access time attribute, and writing |
| updates its modification time. When a file is created, all three time |
| stamps for that file are set to the current time. In addition, the |
| attribute change time and modification time fields of the directory that |
| contains the new entry are updated. |
| |
| Adding a new name for a file with the `link' function updates the |
| attribute change time field of the file being linked, and both the |
| attribute change time and modification time fields of the directory |
| containing the new name. These same fields are affected if a file name |
| is deleted with `unlink', `remove' or `rmdir'. Renaming a file with |
| `rename' affects only the attribute change time and modification time |
| fields of the two parent directories involved, and not the times for |
| the file being renamed. |
| |
| Changing the attributes of a file (for example, with `chmod') |
| updates its attribute change time field. |
| |
| You can also change some of the time stamps of a file explicitly |
| using the `utime' function--all except the attribute change time. You |
| need to include the header file `utime.h' to use this facility. |
| |
| -- Data Type: struct utimbuf |
| The `utimbuf' structure is used with the `utime' function to |
| specify new access and modification times for a file. It contains |
| the following members: |
| |
| `time_t actime' |
| This is the access time for the file. |
| |
| `time_t modtime' |
| This is the modification time for the file. |
| |
| -- Function: int utime (const char *FILENAME, const struct utimbuf |
| *TIMES) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is used to modify the file times associated with the |
| file named FILENAME. |
| |
| If TIMES is a null pointer, then the access and modification times |
| of the file are set to the current time. Otherwise, they are set |
| to the values from the `actime' and `modtime' members |
| (respectively) of the `utimbuf' structure pointed to by TIMES. |
| |
| The attribute modification time for the file is set to the current |
| time in either case (since changing the time stamps is itself a |
| modification of the file attributes). |
| |
| The `utime' function returns `0' if successful and `-1' on |
| failure. In addition to the usual file name errors (*note File |
| Name Errors::), the following `errno' error conditions are defined |
| for this function: |
| |
| `EACCES' |
| There is a permission problem in the case where a null |
| pointer was passed as the TIMES argument. In order to update |
| the time stamp on the file, you must either be the owner of |
| the file, have write permission for the file, or be a |
| privileged user. |
| |
| `ENOENT' |
| The file doesn't exist. |
| |
| `EPERM' |
| If the TIMES argument is not a null pointer, you must either |
| be the owner of the file or be a privileged user. |
| |
| `EROFS' |
| The file lives on a read-only file system. |
| |
| Each of the three time stamps has a corresponding microsecond part, |
| which extends its resolution. These fields are called `st_atime_usec', |
| `st_mtime_usec', and `st_ctime_usec'; each has a value between 0 and |
| 999,999, which indicates the time in microseconds. They correspond to |
| the `tv_usec' field of a `timeval' structure; see *note High-Resolution |
| Calendar::. |
| |
| The `utimes' function is like `utime', but also lets you specify the |
| fractional part of the file times. The prototype for this function is |
| in the header file `sys/time.h'. |
| |
| -- Function: int utimes (const char *FILENAME, const struct timeval |
| TVP[2]) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function sets the file access and modification times of the |
| file FILENAME. The new file access time is specified by `TVP[0]', |
| and the new modification time by `TVP[1]'. Similar to `utime', if |
| TVP is a null pointer then the access and modification times of |
| the file are set to the current time. This function comes from |
| BSD. |
| |
| The return values and error conditions are the same as for the |
| `utime' function. |
| |
| -- Function: int lutimes (const char *FILENAME, const struct timeval |
| TVP[2]) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is like `utimes', except that it does not follow |
| symbolic links. If FILENAME is the name of a symbolic link, |
| `lutimes' sets the file access and modification times of the |
| symbolic link special file itself (as seen by `lstat'; *note |
| Symbolic Links::) while `utimes' sets the file access and |
| modification times of the file the symbolic link refers to. This |
| function comes from FreeBSD, and is not available on all platforms |
| (if not available, it will fail with `ENOSYS'). |
| |
| The return values and error conditions are the same as for the |
| `utime' function. |
| |
| -- Function: int futimes (int FD, const struct timeval TVP[2]) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is like `utimes', except that it takes an open file |
| descriptor as an argument instead of a file name. *Note Low-Level |
| I/O::. This function comes from FreeBSD, and is not available on |
| all platforms (if not available, it will fail with `ENOSYS'). |
| |
| Like `utimes', `futimes' returns `0' on success and `-1' on |
| failure. The following `errno' error conditions are defined for |
| `futimes': |
| |
| `EACCES' |
| There is a permission problem in the case where a null |
| pointer was passed as the TIMES argument. In order to update |
| the time stamp on the file, you must either be the owner of |
| the file, have write permission for the file, or be a |
| privileged user. |
| |
| `EBADF' |
| The FILEDES argument is not a valid file descriptor. |
| |
| `EPERM' |
| If the TIMES argument is not a null pointer, you must either |
| be the owner of the file or be a privileged user. |
| |
| `EROFS' |
| The file lives on a read-only file system. |
| |
| |
| File: libc.info, Node: File Size, Next: Storage Allocation, Prev: File Times, Up: File Attributes |
| |
| 14.9.10 File Size |
| ----------------- |
| |
| Normally file sizes are maintained automatically. A file begins with a |
| size of 0 and is automatically extended when data is written past its |
| end. It is also possible to empty a file completely by an `open' or |
| `fopen' call. |
| |
| However, sometimes it is necessary to _reduce_ the size of a file. |
| This can be done with the `truncate' and `ftruncate' functions. They |
| were introduced in BSD Unix. `ftruncate' was later added to POSIX.1. |
| |
| Some systems allow you to extend a file (creating holes) with these |
| functions. This is useful when using memory-mapped I/O (*note |
| Memory-mapped I/O::), where files are not automatically extended. |
| However, it is not portable but must be implemented if `mmap' allows |
| mapping of files (i.e., `_POSIX_MAPPED_FILES' is defined). |
| |
| Using these functions on anything other than a regular file gives |
| _undefined_ results. On many systems, such a call will appear to |
| succeed, without actually accomplishing anything. |
| |
| -- Function: int truncate (const char *FILENAME, off_t LENGTH) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `truncate' function changes the size of FILENAME to LENGTH. |
| If LENGTH is shorter than the previous length, data at the end |
| will be lost. The file must be writable by the user to perform |
| this operation. |
| |
| If LENGTH is longer, holes will be added to the end. However, some |
| systems do not support this feature and will leave the file |
| unchanged. |
| |
| When the source file is compiled with `_FILE_OFFSET_BITS == 64' the |
| `truncate' function is in fact `truncate64' and the type `off_t' |
| has 64 bits which makes it possible to handle files up to 2^63 |
| bytes in length. |
| |
| The return value is 0 for success, or -1 for an error. In |
| addition to the usual file name errors, the following errors may |
| occur: |
| |
| `EACCES' |
| The file is a directory or not writable. |
| |
| `EINVAL' |
| LENGTH is negative. |
| |
| `EFBIG' |
| The operation would extend the file beyond the limits of the |
| operating system. |
| |
| `EIO' |
| A hardware I/O error occurred. |
| |
| `EPERM' |
| The file is "append-only" or "immutable". |
| |
| `EINTR' |
| The operation was interrupted by a signal. |
| |
| |
| |
| -- Function: int truncate64 (const char *NAME, off64_t LENGTH) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to the `truncate' function. The |
| difference is that the LENGTH argument is 64 bits wide even on 32 |
| bits machines, which allows the handling of files with sizes up to |
| 2^63 bytes. |
| |
| When the source file is compiled with `_FILE_OFFSET_BITS == 64' on |
| a 32 bits machine this function is actually available under the |
| name `truncate' and so transparently replaces the 32 bits |
| interface. |
| |
| -- Function: int ftruncate (int FD, off_t LENGTH) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This is like `truncate', but it works on a file descriptor FD for |
| an opened file instead of a file name to identify the object. The |
| file must be opened for writing to successfully carry out the |
| operation. |
| |
| The POSIX standard leaves it implementation defined what happens |
| if the specified new LENGTH of the file is bigger than the |
| original size. The `ftruncate' function might simply leave the |
| file alone and do nothing or it can increase the size to the |
| desired size. In this later case the extended area should be |
| zero-filled. So using `ftruncate' is no reliable way to increase |
| the file size but if it is possible it is probably the fastest |
| way. The function also operates on POSIX shared memory segments |
| if these are implemented by the system. |
| |
| `ftruncate' is especially useful in combination with `mmap'. |
| Since the mapped region must have a fixed size one cannot enlarge |
| the file by writing something beyond the last mapped page. |
| Instead one has to enlarge the file itself and then remap the file |
| with the new size. The example below shows how this works. |
| |
| When the source file is compiled with `_FILE_OFFSET_BITS == 64' the |
| `ftruncate' function is in fact `ftruncate64' and the type `off_t' |
| has 64 bits which makes it possible to handle files up to 2^63 |
| bytes in length. |
| |
| The return value is 0 for success, or -1 for an error. The |
| following errors may occur: |
| |
| `EBADF' |
| FD does not correspond to an open file. |
| |
| `EACCES' |
| FD is a directory or not open for writing. |
| |
| `EINVAL' |
| LENGTH is negative. |
| |
| `EFBIG' |
| The operation would extend the file beyond the limits of the |
| operating system. |
| |
| `EIO' |
| A hardware I/O error occurred. |
| |
| `EPERM' |
| The file is "append-only" or "immutable". |
| |
| `EINTR' |
| The operation was interrupted by a signal. |
| |
| |
| |
| -- Function: int ftruncate64 (int ID, off64_t LENGTH) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to the `ftruncate' function. The |
| difference is that the LENGTH argument is 64 bits wide even on 32 |
| bits machines which allows the handling of files with sizes up to |
| 2^63 bytes. |
| |
| When the source file is compiled with `_FILE_OFFSET_BITS == 64' on |
| a 32 bits machine this function is actually available under the |
| name `ftruncate' and so transparently replaces the 32 bits |
| interface. |
| |
| As announced here is a little example of how to use `ftruncate' in |
| combination with `mmap': |
| |
| int fd; |
| void *start; |
| size_t len; |
| |
| int |
| add (off_t at, void *block, size_t size) |
| { |
| if (at + size > len) |
| { |
| /* Resize the file and remap. */ |
| size_t ps = sysconf (_SC_PAGESIZE); |
| size_t ns = (at + size + ps - 1) & ~(ps - 1); |
| void *np; |
| if (ftruncate (fd, ns) < 0) |
| return -1; |
| np = mmap (NULL, ns, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0); |
| if (np == MAP_FAILED) |
| return -1; |
| start = np; |
| len = ns; |
| } |
| memcpy ((char *) start + at, block, size); |
| return 0; |
| } |
| |
| The function `add' writes a block of memory at an arbitrary position |
| in the file. If the current size of the file is too small it is |
| extended. Note that it is extended by a whole number of pages. This |
| is a requirement of `mmap'. The program has to keep track of the real |
| size, and when it has finished a final `ftruncate' call should set the |
| real size of the file. |
| |
| |
| File: libc.info, Node: Storage Allocation, Prev: File Size, Up: File Attributes |
| |
| 14.9.11 Storage Allocation |
| -------------------------- |
| |
| Most file systems support allocating large files in a non-contiguous |
| fashion: the file is split into _fragments_ which are allocated |
| sequentially, but the fragments themselves can be scattered across the |
| disk. File systems generally try to avoid such fragmentation because it |
| decreases performance, but if a file gradually increases in size, there |
| might be no other option than to fragment it. In addition, many file |
| systems support _sparse files_ with _holes_: regions of null bytes for |
| which no backing storage has been allocated by the file system. When |
| the holes are finally overwritten with data, fragmentation can occur as |
| well. |
| |
| Explicit allocation of storage for yet-unwritten parts of the file |
| can help the system to avoid fragmentation. Additionally, if storage |
| pre-allocation fails, it is possible to report the out-of-disk error |
| early, often without filling up the entire disk. However, due to |
| deduplication, copy-on-write semantics, and file compression, such |
| pre-allocation may not reliably prevent the out-of-disk-space error from |
| occurring later. Checking for write errors is still required, and |
| writes to memory-mapped regions created with `mmap' can still result in |
| `SIGBUS'. |
| |
| -- Function: int posix_fallocate (int FD, off_t OFFSET, off_t LENGTH) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Allocate backing store for the region of LENGTH bytes starting at |
| byte OFFSET in the file for the descriptor FD. The file length is |
| increased to `LENGTH + OFFSET' if necessary. |
| |
| FD must be a regular file opened for writing, or `EBADF' is |
| returned. If there is insufficient disk space to fulfill the |
| allocation request, `ENOSPC' is returned. |
| |
| *Note_* If `fallocate' is not available (because the file system |
| does not support it), `posix_fallocate' is emulated, which has the |
| following drawbacks: |
| |
| * It is very inefficient because all file system blocks in the |
| requested range need to be examined (even if they have been |
| allocated before) and potentially rewritten. In contrast, |
| with proper `fallocate' support (see below), the file system |
| can examine the internal file allocation data structures and |
| eliminate holes directly, maybe even using unwritten extents |
| (which are pre-allocated but uninitialized on disk). |
| |
| * There is a race condition if another thread or process |
| modifies the underlying file in the to-be-allocated area. |
| Non-null bytes could be overwritten with null bytes. |
| |
| * If FD has been opened with the `O_WRONLY' flag, the function |
| will fail with an `errno' value of `EBADF'. |
| |
| * If FD has been opened with the `O_APPEND' flag, the function |
| will fail with an `errno' value of `EBADF'. |
| |
| * If LENGTH is zero, `ftruncate' is used to increase the file |
| size as requested, without allocating file system blocks. |
| There is a race condition which means that `ftruncate' can |
| accidentally truncate the file if it has been extended |
| concurrently. |
| |
| On Linux, if an application does not benefit from emulation or if |
| the emulation is harmful due to its inherent race conditions, the |
| application can use the Linux-specific `fallocate' function, with a |
| zero flag argument. For the `fallocate' function, the GNU C |
| Library does not perform allocation emulation if the file system |
| does not support allocation. Instead, an `EOPNOTSUPP' is returned |
| to the caller. |
| |
| |
| -- Function: int posix_fallocate64 (int FD, off64_t OFFSET, off64_t |
| LENGTH) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is a variant of `posix_fallocate64' which accepts |
| 64-bit file offsets on all platforms. |
| |
| |
| |
| File: libc.info, Node: Making Special Files, Next: Temporary Files, Prev: File Attributes, Up: File System Interface |
| |
| 14.10 Making Special Files |
| ========================== |
| |
| The `mknod' function is the primitive for making special files, such as |
| files that correspond to devices. The GNU C Library includes this |
| function for compatibility with BSD. |
| |
| The prototype for `mknod' is declared in `sys/stat.h'. |
| |
| -- Function: int mknod (const char *FILENAME, mode_t MODE, dev_t DEV) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `mknod' function makes a special file with name FILENAME. The |
| MODE specifies the mode of the file, and may include the various |
| special file bits, such as `S_IFCHR' (for a character special file) |
| or `S_IFBLK' (for a block special file). *Note Testing File |
| Type::. |
| |
| The DEV argument specifies which device the special file refers to. |
| Its exact interpretation depends on the kind of special file being |
| created. |
| |
| The return value is `0' on success and `-1' on error. In addition |
| to the usual file name errors (*note File Name Errors::), the |
| following `errno' error conditions are defined for this function: |
| |
| `EPERM' |
| The calling process is not privileged. Only the superuser |
| can create special files. |
| |
| `ENOSPC' |
| The directory or file system that would contain the new file |
| is full and cannot be extended. |
| |
| `EROFS' |
| The directory containing the new file can't be modified |
| because it's on a read-only file system. |
| |
| `EEXIST' |
| There is already a file named FILENAME. If you want to |
| replace this file, you must remove the old file explicitly |
| first. |
| |
| |
| File: libc.info, Node: Temporary Files, Prev: Making Special Files, Up: File System Interface |
| |
| 14.11 Temporary Files |
| ===================== |
| |
| If you need to use a temporary file in your program, you can use the |
| `tmpfile' function to open it. Or you can use the `tmpnam' (better: |
| `tmpnam_r') function to provide a name for a temporary file and then |
| you can open it in the usual way with `fopen'. |
| |
| The `tempnam' function is like `tmpnam' but lets you choose what |
| directory temporary files will go in, and something about what their |
| file names will look like. Important for multi-threaded programs is |
| that `tempnam' is reentrant, while `tmpnam' is not since it returns a |
| pointer to a static buffer. |
| |
| These facilities are declared in the header file `stdio.h'. |
| |
| -- Function: FILE * tmpfile (void) |
| Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem fd |
| lock | *Note POSIX Safety Concepts::. |
| |
| This function creates a temporary binary file for update mode, as |
| if by calling `fopen' with mode `"wb+"'. The file is deleted |
| automatically when it is closed or when the program terminates. |
| (On some other ISO C systems the file may fail to be deleted if |
| the program terminates abnormally). |
| |
| This function is reentrant. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' on a |
| 32-bit system this function is in fact `tmpfile64', i.e., the LFS |
| interface transparently replaces the old interface. |
| |
| -- Function: FILE * tmpfile64 (void) |
| Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem fd |
| lock | *Note POSIX Safety Concepts::. |
| |
| This function is similar to `tmpfile', but the stream it returns a |
| pointer to was opened using `tmpfile64'. Therefore this stream can |
| be used for files larger than 2^31 bytes on 32-bit machines. |
| |
| Please note that the return type is still `FILE *'. There is no |
| special `FILE' type for the LFS interface. |
| |
| If the sources are compiled with `_FILE_OFFSET_BITS == 64' on a 32 |
| bits machine this function is available under the name `tmpfile' |
| and so transparently replaces the old interface. |
| |
| -- Function: char * tmpnam (char *RESULT) |
| Preliminary: | MT-Unsafe race:tmpnam/!result | AS-Unsafe | AC-Safe |
| | *Note POSIX Safety Concepts::. |
| |
| This function constructs and returns a valid file name that does |
| not refer to any existing file. If the RESULT argument is a null |
| pointer, the return value is a pointer to an internal static |
| string, which might be modified by subsequent calls and therefore |
| makes this function non-reentrant. Otherwise, the RESULT argument |
| should be a pointer to an array of at least `L_tmpnam' characters, |
| and the result is written into that array. |
| |
| It is possible for `tmpnam' to fail if you call it too many times |
| without removing previously-created files. This is because the |
| limited length of the temporary file names gives room for only a |
| finite number of different names. If `tmpnam' fails it returns a |
| null pointer. |
| |
| *Warning:* Between the time the pathname is constructed and the |
| file is created another process might have created a file with the |
| same name using `tmpnam', leading to a possible security hole. The |
| implementation generates names which can hardly be predicted, but |
| when opening the file you should use the `O_EXCL' flag. Using |
| `tmpfile' or `mkstemp' is a safe way to avoid this problem. |
| |
| -- Function: char * tmpnam_r (char *RESULT) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is nearly identical to the `tmpnam' function, except |
| that if RESULT is a null pointer it returns a null pointer. |
| |
| This guarantees reentrancy because the non-reentrant situation of |
| `tmpnam' cannot happen here. |
| |
| *Warning*: This function has the same security problems as |
| `tmpnam'. |
| |
| -- Macro: int L_tmpnam |
| The value of this macro is an integer constant expression that |
| represents the minimum size of a string large enough to hold a |
| file name generated by the `tmpnam' function. |
| |
| -- Macro: int TMP_MAX |
| The macro `TMP_MAX' is a lower bound for how many temporary names |
| you can create with `tmpnam'. You can rely on being able to call |
| `tmpnam' at least this many times before it might fail saying you |
| have made too many temporary file names. |
| |
| With the GNU C Library, you can create a very large number of |
| temporary file names. If you actually created the files, you |
| would probably run out of disk space before you ran out of names. |
| Some other systems have a fixed, small limit on the number of |
| temporary files. The limit is never less than `25'. |
| |
| -- Function: char * tempnam (const char *DIR, const char *PREFIX) |
| Preliminary: | MT-Safe env | AS-Unsafe heap | AC-Unsafe mem | |
| *Note POSIX Safety Concepts::. |
| |
| This function generates a unique temporary file name. If PREFIX |
| is not a null pointer, up to five characters of this string are |
| used as a prefix for the file name. The return value is a string |
| newly allocated with `malloc', so you should release its storage |
| with `free' when it is no longer needed. |
| |
| Because the string is dynamically allocated this function is |
| reentrant. |
| |
| The directory prefix for the temporary file name is determined by |
| testing each of the following in sequence. The directory must |
| exist and be writable. |
| |
| * The environment variable `TMPDIR', if it is defined. For |
| security reasons this only happens if the program is not SUID |
| or SGID enabled. |
| |
| * The DIR argument, if it is not a null pointer. |
| |
| * The value of the `P_tmpdir' macro. |
| |
| * The directory `/tmp'. |
| |
| This function is defined for SVID compatibility. |
| |
| *Warning:* Between the time the pathname is constructed and the |
| file is created another process might have created a file with the |
| same name using `tempnam', leading to a possible security hole. |
| The implementation generates names which can hardly be predicted, |
| but when opening the file you should use the `O_EXCL' flag. Using |
| `tmpfile' or `mkstemp' is a safe way to avoid this problem. |
| |
| -- SVID Macro: char * P_tmpdir |
| This macro is the name of the default directory for temporary |
| files. |
| |
| Older Unix systems did not have the functions just described. |
| Instead they used `mktemp' and `mkstemp'. Both of these functions work |
| by modifying a file name template string you pass. The last six |
| characters of this string must be `XXXXXX'. These six `X's are |
| replaced with six characters which make the whole string a unique file |
| name. Usually the template string is something like |
| `/tmp/PREFIXXXXXXX', and each program uses a unique PREFIX. |
| |
| *NB:* Because `mktemp' and `mkstemp' modify the template string, you |
| _must not_ pass string constants to them. String constants are |
| normally in read-only storage, so your program would crash when |
| `mktemp' or `mkstemp' tried to modify the string. These functions are |
| declared in the header file `stdlib.h'. |
| |
| -- Function: char * mktemp (char *TEMPLATE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `mktemp' function generates a unique file name by modifying |
| TEMPLATE as described above. If successful, it returns TEMPLATE |
| as modified. If `mktemp' cannot find a unique file name, it makes |
| TEMPLATE an empty string and returns that. If TEMPLATE does not |
| end with `XXXXXX', `mktemp' returns a null pointer. |
| |
| *Warning:* Between the time the pathname is constructed and the |
| file is created another process might have created a file with the |
| same name using `mktemp', leading to a possible security hole. The |
| implementation generates names which can hardly be predicted, but |
| when opening the file you should use the `O_EXCL' flag. Using |
| `mkstemp' is a safe way to avoid this problem. |
| |
| -- Function: int mkstemp (char *TEMPLATE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety |
| Concepts::. |
| |
| The `mkstemp' function generates a unique file name just as |
| `mktemp' does, but it also opens the file for you with `open' |
| (*note Opening and Closing Files::). If successful, it modifies |
| TEMPLATE in place and returns a file descriptor for that file open |
| for reading and writing. If `mkstemp' cannot create a |
| uniquely-named file, it returns `-1'. If TEMPLATE does not end |
| with `XXXXXX', `mkstemp' returns `-1' and does not modify TEMPLATE. |
| |
| The file is opened using mode `0600'. If the file is meant to be |
| used by other users this mode must be changed explicitly. |
| |
| Unlike `mktemp', `mkstemp' is actually guaranteed to create a unique |
| file that cannot possibly clash with any other program trying to create |
| a temporary file. This is because it works by calling `open' with the |
| `O_EXCL' flag, which says you want to create a new file and get an |
| error if the file already exists. |
| |
| -- Function: char * mkdtemp (char *TEMPLATE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `mkdtemp' function creates a directory with a unique name. If |
| it succeeds, it overwrites TEMPLATE with the name of the |
| directory, and returns TEMPLATE. As with `mktemp' and `mkstemp', |
| TEMPLATE should be a string ending with `XXXXXX'. |
| |
| If `mkdtemp' cannot create an uniquely named directory, it returns |
| `NULL' and sets `errno' appropriately. If TEMPLATE does not end |
| with `XXXXXX', `mkdtemp' returns `NULL' and does not modify |
| TEMPLATE. `errno' will be set to `EINVAL' in this case. |
| |
| The directory is created using mode `0700'. |
| |
| The directory created by `mkdtemp' cannot clash with temporary files |
| or directories created by other users. This is because directory |
| creation always works like `open' with `O_EXCL'. *Note Creating |
| Directories::. |
| |
| The `mkdtemp' function comes from OpenBSD. |
| |
| |
| File: libc.info, Node: Pipes and FIFOs, Next: Sockets, Prev: File System Interface, Up: Top |
| |
| 15 Pipes and FIFOs |
| ****************** |
| |
| A "pipe" is a mechanism for interprocess communication; data written to |
| the pipe by one process can be read by another process. The data is |
| handled in a first-in, first-out (FIFO) order. The pipe has no name; it |
| is created for one use and both ends must be inherited from the single |
| process which created the pipe. |
| |
| A "FIFO special file" is similar to a pipe, but instead of being an |
| anonymous, temporary connection, a FIFO has a name or names like any |
| other file. Processes open the FIFO by name in order to communicate |
| through it. |
| |
| A pipe or FIFO has to be open at both ends simultaneously. If you |
| read from a pipe or FIFO file that doesn't have any processes writing |
| to it (perhaps because they have all closed the file, or exited), the |
| read returns end-of-file. Writing to a pipe or FIFO that doesn't have a |
| reading process is treated as an error condition; it generates a |
| `SIGPIPE' signal, and fails with error code `EPIPE' if the signal is |
| handled or blocked. |
| |
| Neither pipes nor FIFO special files allow file positioning. Both |
| reading and writing operations happen sequentially; reading from the |
| beginning of the file and writing at the end. |
| |
| * Menu: |
| |
| * 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. |
| |
| |
| File: libc.info, Node: Creating a Pipe, Next: Pipe to a Subprocess, Up: Pipes and FIFOs |
| |
| 15.1 Creating a Pipe |
| ==================== |
| |
| The primitive for creating a pipe is the `pipe' function. This creates |
| both the reading and writing ends of the pipe. It is not very useful |
| for a single process to use a pipe to talk to itself. In typical use, |
| a process creates a pipe just before it forks one or more child |
| processes (*note Creating a Process::). The pipe is then used for |
| communication either between the parent or child processes, or between |
| two sibling processes. |
| |
| The `pipe' function is declared in the header file `unistd.h'. |
| |
| -- Function: int pipe (int FILEDES[2]) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety |
| Concepts::. |
| |
| The `pipe' function creates a pipe and puts the file descriptors |
| for the reading and writing ends of the pipe (respectively) into |
| `FILEDES[0]' and `FILEDES[1]'. |
| |
| An easy way to remember that the input end comes first is that file |
| descriptor `0' is standard input, and file descriptor `1' is |
| standard output. |
| |
| If successful, `pipe' returns a value of `0'. On failure, `-1' is |
| returned. The following `errno' error conditions are defined for |
| this function: |
| |
| `EMFILE' |
| The process has too many files open. |
| |
| `ENFILE' |
| There are too many open files in the entire system. *Note |
| Error Codes::, for more information about `ENFILE'. This |
| error never occurs on GNU/Hurd systems. |
| |
| Here is an example of a simple program that creates a pipe. This |
| program uses the `fork' function (*note Creating a Process::) to create |
| a child process. The parent process writes data to the pipe, which is |
| read by the child process. |
| |
| |
| #include <sys/types.h> |
| #include <unistd.h> |
| #include <stdio.h> |
| #include <stdlib.h> |
| |
| /* Read characters from the pipe and echo them to `stdout'. */ |
| |
| void |
| read_from_pipe (int file) |
| { |
| FILE *stream; |
| int c; |
| stream = fdopen (file, "r"); |
| while ((c = fgetc (stream)) != EOF) |
| putchar (c); |
| fclose (stream); |
| } |
| |
| /* Write some random text to the pipe. */ |
| |
| void |
| write_to_pipe (int file) |
| { |
| FILE *stream; |
| stream = fdopen (file, "w"); |
| fprintf (stream, "hello, world!\n"); |
| fprintf (stream, "goodbye, world!\n"); |
| fclose (stream); |
| } |
| |
| int |
| main (void) |
| { |
| pid_t pid; |
| int mypipe[2]; |
| |
| /* Create the pipe. */ |
| if (pipe (mypipe)) |
| { |
| fprintf (stderr, "Pipe failed.\n"); |
| return EXIT_FAILURE; |
| } |
| |
| /* Create the child process. */ |
| pid = fork (); |
| if (pid == (pid_t) 0) |
| { |
| /* This is the child process. |
| Close other end first. */ |
| close (mypipe[1]); |
| read_from_pipe (mypipe[0]); |
| return EXIT_SUCCESS; |
| } |
| else if (pid < (pid_t) 0) |
| { |
| /* The fork failed. */ |
| fprintf (stderr, "Fork failed.\n"); |
| return EXIT_FAILURE; |
| } |
| else |
| { |
| /* This is the parent process. |
| Close other end first. */ |
| close (mypipe[0]); |
| write_to_pipe (mypipe[1]); |
| return EXIT_SUCCESS; |
| } |
| } |
| |
| |
| File: libc.info, Node: Pipe to a Subprocess, Next: FIFO Special Files, Prev: Creating a Pipe, Up: Pipes and FIFOs |
| |
| 15.2 Pipe to a Subprocess |
| ========================= |
| |
| A common use of pipes is to send data to or receive data from a program |
| being run as a subprocess. One way of doing this is by using a |
| combination of `pipe' (to create the pipe), `fork' (to create the |
| subprocess), `dup2' (to force the subprocess to use the pipe as its |
| standard input or output channel), and `exec' (to execute the new |
| program). Or, you can use `popen' and `pclose'. |
| |
| The advantage of using `popen' and `pclose' is that the interface is |
| much simpler and easier to use. But it doesn't offer as much |
| flexibility as using the low-level functions directly. |
| |
| -- Function: FILE * popen (const char *COMMAND, const char *MODE) |
| Preliminary: | MT-Safe | AS-Unsafe heap corrupt | AC-Unsafe |
| corrupt lock fd mem | *Note POSIX Safety Concepts::. |
| |
| The `popen' function is closely related to the `system' function; |
| see *note Running a Command::. It executes the shell command |
| COMMAND as a subprocess. However, instead of waiting for the |
| command to complete, it creates a pipe to the subprocess and |
| returns a stream that corresponds to that pipe. |
| |
| If you specify a MODE argument of `"r"', you can read from the |
| stream to retrieve data from the standard output channel of the |
| subprocess. The subprocess inherits its standard input channel |
| from the parent process. |
| |
| Similarly, if you specify a MODE argument of `"w"', you can write |
| to the stream to send data to the standard input channel of the |
| subprocess. The subprocess inherits its standard output channel |
| from the parent process. |
| |
| In the event of an error `popen' returns a null pointer. This |
| might happen if the pipe or stream cannot be created, if the |
| subprocess cannot be forked, or if the program cannot be executed. |
| |
| -- Function: int pclose (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Unsafe heap plugin corrupt lock | |
| AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::. |
| |
| The `pclose' function is used to close a stream created by `popen'. |
| It waits for the child process to terminate and returns its status |
| value, as for the `system' function. |
| |
| Here is an example showing how to use `popen' and `pclose' to filter |
| output through another program, in this case the paging program `more'. |
| |
| |
| #include <stdio.h> |
| #include <stdlib.h> |
| |
| void |
| write_data (FILE * stream) |
| { |
| int i; |
| for (i = 0; i < 100; i++) |
| fprintf (stream, "%d\n", i); |
| if (ferror (stream)) |
| { |
| fprintf (stderr, "Output to stream failed.\n"); |
| exit (EXIT_FAILURE); |
| } |
| } |
| |
| int |
| main (void) |
| { |
| FILE *output; |
| |
| output = popen ("more", "w"); |
| if (!output) |
| { |
| fprintf (stderr, |
| "incorrect parameters or too many files.\n"); |
| return EXIT_FAILURE; |
| } |
| write_data (output); |
| if (pclose (output) != 0) |
| { |
| fprintf (stderr, |
| "Could not run more or other error.\n"); |
| } |
| return EXIT_SUCCESS; |
| } |
| |
| |
| File: libc.info, Node: FIFO Special Files, Next: Pipe Atomicity, Prev: Pipe to a Subprocess, Up: Pipes and FIFOs |
| |
| 15.3 FIFO Special Files |
| ======================= |
| |
| A FIFO special file is similar to a pipe, except that it is created in a |
| different way. Instead of being an anonymous communications channel, a |
| FIFO special file is entered into the file system by calling `mkfifo'. |
| |
| Once you have created a FIFO special file in this way, any process |
| can open it for reading or writing, in the same way as an ordinary file. |
| However, it has to be open at both ends simultaneously before you can |
| proceed to do any input or output operations on it. Opening a FIFO for |
| reading normally blocks until some other process opens the same FIFO for |
| writing, and vice versa. |
| |
| The `mkfifo' function is declared in the header file `sys/stat.h'. |
| |
| -- Function: int mkfifo (const char *FILENAME, mode_t MODE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `mkfifo' function makes a FIFO special file with name |
| FILENAME. The MODE argument is used to set the file's |
| permissions; see *note Setting Permissions::. |
| |
| The normal, successful return value from `mkfifo' is `0'. In the |
| case of an error, `-1' is returned. In addition to the usual file |
| name errors (*note File Name Errors::), the following `errno' |
| error conditions are defined for this function: |
| |
| `EEXIST' |
| The named file already exists. |
| |
| `ENOSPC' |
| The directory or file system cannot be extended. |
| |
| `EROFS' |
| The directory that would contain the file resides on a |
| read-only file system. |
| |
| |
| File: libc.info, Node: Pipe Atomicity, Prev: FIFO Special Files, Up: Pipes and FIFOs |
| |
| 15.4 Atomicity of Pipe I/O |
| ========================== |
| |
| Reading or writing pipe data is "atomic" if the size of data written is |
| not greater than `PIPE_BUF'. This means that the data transfer seems |
| to be an instantaneous unit, in that nothing else in the system can |
| observe a state in which it is partially complete. Atomic I/O may not |
| begin right away (it may need to wait for buffer space or for data), |
| but once it does begin it finishes immediately. |
| |
| Reading or writing a larger amount of data may not be atomic; for |
| example, output data from other processes sharing the descriptor may be |
| interspersed. Also, once `PIPE_BUF' characters have been written, |
| further writes will block until some characters are read. |
| |
| *Note Limits for Files::, for information about the `PIPE_BUF' |
| parameter. |
| |
| |
| File: libc.info, Node: Sockets, Next: Low-Level Terminal Interface, Prev: Pipes and FIFOs, Up: Top |
| |
| 16 Sockets |
| ********** |
| |
| This chapter describes the GNU facilities for interprocess |
| communication using sockets. |
| |
| A "socket" is a generalized interprocess communication channel. |
| Like a pipe, a socket is represented as a file descriptor. Unlike pipes |
| sockets support communication between unrelated processes, and even |
| between processes running on different machines that communicate over a |
| network. Sockets are the primary means of communicating with other |
| machines; `telnet', `rlogin', `ftp', `talk' and the other familiar |
| network programs use sockets. |
| |
| Not all operating systems support sockets. In the GNU C Library, the |
| header file `sys/socket.h' exists regardless of the operating system, |
| and the socket functions always exist, but if the system does not |
| really support sockets these functions always fail. |
| |
| *Incomplete:* We do not currently document the facilities for |
| broadcast messages or for configuring Internet interfaces. The |
| reentrant functions and some newer functions that are related to IPv6 |
| aren't documented either so far. |
| |
| * Menu: |
| |
| * 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. |
| |
| |
| File: libc.info, Node: Socket Concepts, Next: Communication Styles, Up: Sockets |
| |
| 16.1 Socket Concepts |
| ==================== |
| |
| When you create a socket, you must specify the style of communication |
| you want to use and the type of protocol that should implement it. The |
| "communication style" of a socket defines the user-level semantics of |
| sending and receiving data on the socket. Choosing a communication |
| style specifies the answers to questions such as these: |
| |
| * *What are the units of data transmission?* Some communication |
| styles regard the data as a sequence of bytes with no larger |
| structure; others group the bytes into records (which are known in |
| this context as "packets"). |
| |
| * *Can data be lost during normal operation?* Some communication |
| styles guarantee that all the data sent arrives in the order it was |
| sent (barring system or network crashes); other styles occasionally |
| lose data as a normal part of operation, and may sometimes deliver |
| packets more than once or in the wrong order. |
| |
| Designing a program to use unreliable communication styles usually |
| involves taking precautions to detect lost or misordered packets |
| and to retransmit data as needed. |
| |
| * *Is communication entirely with one partner?* Some communication |
| styles are like a telephone call--you make a "connection" with one |
| remote socket and then exchange data freely. Other styles are |
| like mailing letters--you specify a destination address for each |
| message you send. |
| |
| You must also choose a "namespace" for naming the socket. A socket |
| name ("address") is meaningful only in the context of a particular |
| namespace. In fact, even the data type to use for a socket name may |
| depend on the namespace. Namespaces are also called "domains", but we |
| avoid that word as it can be confused with other usage of the same |
| term. Each namespace has a symbolic name that starts with `PF_'. A |
| corresponding symbolic name starting with `AF_' designates the address |
| format for that namespace. |
| |
| Finally you must choose the "protocol" to carry out the |
| communication. The protocol determines what low-level mechanism is used |
| to transmit and receive data. Each protocol is valid for a particular |
| namespace and communication style; a namespace is sometimes called a |
| "protocol family" because of this, which is why the namespace names |
| start with `PF_'. |
| |
| The rules of a protocol apply to the data passing between two |
| programs, perhaps on different computers; most of these rules are |
| handled by the operating system and you need not know about them. What |
| you do need to know about protocols is this: |
| |
| * In order to have communication between two sockets, they must |
| specify the _same_ protocol. |
| |
| * Each protocol is meaningful with particular style/namespace |
| combinations and cannot be used with inappropriate combinations. |
| For example, the TCP protocol fits only the byte stream style of |
| communication and the Internet namespace. |
| |
| * For each combination of style and namespace there is a "default |
| protocol", which you can request by specifying 0 as the protocol |
| number. And that's what you should normally do--use the default. |
| |
| Throughout the following description at various places |
| variables/parameters to denote sizes are required. And here the trouble |
| starts. In the first implementations the type of these variables was |
| simply `int'. On most machines at that time an `int' was 32 bits wide, |
| which created a _de facto_ standard requiring 32-bit variables. This |
| is important since references to variables of this type are passed to |
| the kernel. |
| |
| Then the POSIX people came and unified the interface with the words |
| "all size values are of type `size_t'". On 64-bit machines `size_t' is |
| 64 bits wide, so pointers to variables were no longer possible. |
| |
| The Unix98 specification provides a solution by introducing a type |
| `socklen_t'. This type is used in all of the cases that POSIX changed |
| to use `size_t'. The only requirement of this type is that it be an |
| unsigned type of at least 32 bits. Therefore, implementations which |
| require that references to 32-bit variables be passed can be as happy |
| as implementations which use 64-bit values. |
| |
| |
| File: libc.info, Node: Communication Styles, Next: Socket Addresses, Prev: Socket Concepts, Up: Sockets |
| |
| 16.2 Communication Styles |
| ========================= |
| |
| The GNU C Library includes support for several different kinds of |
| sockets, each with different characteristics. This section describes |
| the supported socket types. The symbolic constants listed here are |
| defined in `sys/socket.h'. |
| |
| -- Macro: int SOCK_STREAM |
| The `SOCK_STREAM' style is like a pipe (*note Pipes and FIFOs::). |
| It operates over a connection with a particular remote socket and |
| transmits data reliably as a stream of bytes. |
| |
| Use of this style is covered in detail in *note Connections::. |
| |
| -- Macro: int SOCK_DGRAM |
| The `SOCK_DGRAM' style is used for sending individually-addressed |
| packets unreliably. It is the diametrical opposite of |
| `SOCK_STREAM'. |
| |
| Each time you write data to a socket of this kind, that data |
| becomes one packet. Since `SOCK_DGRAM' sockets do not have |
| connections, you must specify the recipient address with each |
| packet. |
| |
| The only guarantee that the system makes about your requests to |
| transmit data is that it will try its best to deliver each packet |
| you send. It may succeed with the sixth packet after failing with |
| the fourth and fifth packets; the seventh packet may arrive before |
| the sixth, and may arrive a second time after the sixth. |
| |
| The typical use for `SOCK_DGRAM' is in situations where it is |
| acceptable to simply re-send a packet if no response is seen in a |
| reasonable amount of time. |
| |
| *Note Datagrams::, for detailed information about how to use |
| datagram sockets. |
| |
| -- Macro: int SOCK_RAW |
| This style provides access to low-level network protocols and |
| interfaces. Ordinary user programs usually have no need to use |
| this style. |
| |
| |
| File: libc.info, Node: Socket Addresses, Next: Interface Naming, Prev: Communication Styles, Up: Sockets |
| |
| 16.3 Socket Addresses |
| ===================== |
| |
| The name of a socket is normally called an "address". The functions |
| and symbols for dealing with socket addresses were named |
| inconsistently, sometimes using the term "name" and sometimes using |
| "address". You can regard these terms as synonymous where sockets are |
| concerned. |
| |
| A socket newly created with the `socket' function has no address. |
| Other processes can find it for communication only if you give it an |
| address. We call this "binding" the address to the socket, and the way |
| to do it is with the `bind' function. |
| |
| You need only be concerned with the address of a socket if other |
| processes are to find it and start communicating with it. You can |
| specify an address for other sockets, but this is usually pointless; |
| the first time you send data from a socket, or use it to initiate a |
| connection, the system assigns an address automatically if you have not |
| specified one. |
| |
| Occasionally a client needs to specify an address because the server |
| discriminates based on address; for example, the rsh and rlogin |
| protocols look at the client's socket address and only bypass passphrase |
| checking if it is less than `IPPORT_RESERVED' (*note Ports::). |
| |
| The details of socket addresses vary depending on what namespace you |
| are using. *Note Local Namespace::, or *note Internet Namespace::, for |
| specific information. |
| |
| Regardless of the namespace, you use the same functions `bind' and |
| `getsockname' to set and examine a socket's address. These functions |
| use a phony data type, `struct sockaddr *', to accept the address. In |
| practice, the address lives in a structure of some other data type |
| appropriate to the address format you are using, but you cast its |
| address to `struct sockaddr *' when you pass it to `bind'. |
| |
| * Menu: |
| |
| * Address Formats:: About `struct sockaddr'. |
| * Setting Address:: Binding an address to a socket. |
| * Reading Address:: Reading the address of a socket. |
| |
| |
| File: libc.info, Node: Address Formats, Next: Setting Address, Up: Socket Addresses |
| |
| 16.3.1 Address Formats |
| ---------------------- |
| |
| The functions `bind' and `getsockname' use the generic data type |
| `struct sockaddr *' to represent a pointer to a socket address. You |
| can't use this data type effectively to interpret an address or |
| construct one; for that, you must use the proper data type for the |
| socket's namespace. |
| |
| Thus, the usual practice is to construct an address of the proper |
| namespace-specific type, then cast a pointer to `struct sockaddr *' |
| when you call `bind' or `getsockname'. |
| |
| The one piece of information that you can get from the `struct |
| sockaddr' data type is the "address format designator". This tells you |
| which data type to use to understand the address fully. |
| |
| The symbols in this section are defined in the header file |
| `sys/socket.h'. |
| |
| -- Data Type: struct sockaddr |
| The `struct sockaddr' type itself has the following members: |
| |
| `short int sa_family' |
| This is the code for the address format of this address. It |
| identifies the format of the data which follows. |
| |
| `char sa_data[14]' |
| This is the actual socket address data, which is |
| format-dependent. Its length also depends on the format, and |
| may well be more than 14. The length 14 of `sa_data' is |
| essentially arbitrary. |
| |
| Each address format has a symbolic name which starts with `AF_'. |
| Each of them corresponds to a `PF_' symbol which designates the |
| corresponding namespace. Here is a list of address format names: |
| |
| `AF_LOCAL' |
| This designates the address format that goes with the local |
| namespace. (`PF_LOCAL' is the name of that namespace.) *Note |
| Local Namespace Details::, for information about this address |
| format. |
| |
| `AF_UNIX' |
| This is a synonym for `AF_LOCAL'. Although `AF_LOCAL' is mandated |
| by POSIX.1g, `AF_UNIX' is portable to more systems. `AF_UNIX' was |
| the traditional name stemming from BSD, so even most POSIX systems |
| support it. It is also the name of choice in the Unix98 |
| specification. (The same is true for `PF_UNIX' vs. `PF_LOCAL'). |
| |
| `AF_FILE' |
| This is another synonym for `AF_LOCAL', for compatibility. |
| (`PF_FILE' is likewise a synonym for `PF_LOCAL'.) |
| |
| `AF_INET' |
| This designates the address format that goes with the Internet |
| namespace. (`PF_INET' is the name of that namespace.) *Note |
| Internet Address Formats::. |
| |
| `AF_INET6' |
| This is similar to `AF_INET', but refers to the IPv6 protocol. |
| (`PF_INET6' is the name of the corresponding namespace.) |
| |
| `AF_UNSPEC' |
| This designates no particular address format. It is used only in |
| rare cases, such as to clear out the default destination address |
| of a "connected" datagram socket. *Note Sending Datagrams::. |
| |
| The corresponding namespace designator symbol `PF_UNSPEC' exists |
| for completeness, but there is no reason to use it in a program. |
| |
| `sys/socket.h' defines symbols starting with `AF_' for many |
| different kinds of networks, most or all of which are not actually |
| implemented. We will document those that really work as we receive |
| information about how to use them. |
| |
| |
| File: libc.info, Node: Setting Address, Next: Reading Address, Prev: Address Formats, Up: Socket Addresses |
| |
| 16.3.2 Setting the Address of a Socket |
| -------------------------------------- |
| |
| Use the `bind' function to assign an address to a socket. The |
| prototype for `bind' is in the header file `sys/socket.h'. For |
| examples of use, see *note Local Socket Example::, or see *note Inet |
| Example::. |
| |
| -- Function: int bind (int SOCKET, struct sockaddr *ADDR, socklen_t |
| LENGTH) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `bind' function assigns an address to the socket SOCKET. The |
| ADDR and LENGTH arguments specify the address; the detailed format |
| of the address depends on the namespace. The first part of the |
| address is always the format designator, which specifies a |
| namespace, and says that the address is in the format of that |
| namespace. |
| |
| The return value is `0' on success and `-1' on failure. The |
| following `errno' error conditions are defined for this function: |
| |
| `EBADF' |
| The SOCKET argument is not a valid file descriptor. |
| |
| `ENOTSOCK' |
| The descriptor SOCKET is not a socket. |
| |
| `EADDRNOTAVAIL' |
| The specified address is not available on this machine. |
| |
| `EADDRINUSE' |
| Some other socket is already using the specified address. |
| |
| `EINVAL' |
| The socket SOCKET already has an address. |
| |
| `EACCES' |
| You do not have permission to access the requested address. |
| (In the Internet domain, only the super-user is allowed to |
| specify a port number in the range 0 through |
| `IPPORT_RESERVED' minus one; see *note Ports::.) |
| |
| Additional conditions may be possible depending on the particular |
| namespace of the socket. |
| |
| |
| File: libc.info, Node: Reading Address, Prev: Setting Address, Up: Socket Addresses |
| |
| 16.3.3 Reading the Address of a Socket |
| -------------------------------------- |
| |
| Use the function `getsockname' to examine the address of an Internet |
| socket. The prototype for this function is in the header file |
| `sys/socket.h'. |
| |
| -- Function: int getsockname (int SOCKET, struct sockaddr *ADDR, |
| socklen_t *LENGTH-PTR) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe mem/hurd | *Note POSIX |
| Safety Concepts::. |
| |
| The `getsockname' function returns information about the address |
| of the socket SOCKET in the locations specified by the ADDR and |
| LENGTH-PTR arguments. Note that the LENGTH-PTR is a pointer; you |
| should initialize it to be the allocation size of ADDR, and on |
| return it contains the actual size of the address data. |
| |
| The format of the address data depends on the socket namespace. |
| The length of the information is usually fixed for a given |
| namespace, so normally you can know exactly how much space is |
| needed and can provide that much. The usual practice is to |
| allocate a place for the value using the proper data type for the |
| socket's namespace, then cast its address to `struct sockaddr *' |
| to pass it to `getsockname'. |
| |
| The return value is `0' on success and `-1' on error. The |
| following `errno' error conditions are defined for this function: |
| |
| `EBADF' |
| The SOCKET argument is not a valid file descriptor. |
| |
| `ENOTSOCK' |
| The descriptor SOCKET is not a socket. |
| |
| `ENOBUFS' |
| There are not enough internal buffers available for the |
| operation. |
| |
| You can't read the address of a socket in the file namespace. This |
| is consistent with the rest of the system; in general, there's no way to |
| find a file's name from a descriptor for that file. |
| |
| |
| File: libc.info, Node: Interface Naming, Next: Local Namespace, Prev: Socket Addresses, Up: Sockets |
| |
| 16.4 Interface Naming |
| ===================== |
| |
| Each network interface has a name. This usually consists of a few |
| letters that relate to the type of interface, which may be followed by a |
| number if there is more than one interface of that type. Examples |
| might be `lo' (the loopback interface) and `eth0' (the first Ethernet |
| interface). |
| |
| Although such names are convenient for humans, it would be clumsy to |
| have to use them whenever a program needs to refer to an interface. In |
| such situations an interface is referred to by its "index", which is an |
| arbitrarily-assigned small positive integer. |
| |
| The following functions, constants and data types are declared in the |
| header file `net/if.h'. |
| |
| -- Constant: size_t IFNAMSIZ |
| This constant defines the maximum buffer size needed to hold an |
| interface name, including its terminating zero byte. |
| |
| -- Function: unsigned int if_nametoindex (const char *IFNAME) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd | |
| *Note POSIX Safety Concepts::. |
| |
| This function yields the interface index corresponding to a |
| particular name. If no interface exists with the name given, it |
| returns 0. |
| |
| -- Function: char * if_indextoname (unsigned int IFINDEX, char *IFNAME) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd | |
| *Note POSIX Safety Concepts::. |
| |
| This function maps an interface index to its corresponding name. |
| The returned name is placed in the buffer pointed to by `ifname', |
| which must be at least `IFNAMSIZ' bytes in length. If the index |
| was invalid, the function's return value is a null pointer, |
| otherwise it is `ifname'. |
| |
| -- Data Type: struct if_nameindex |
| This data type is used to hold the information about a single |
| interface. It has the following members: |
| |
| `unsigned int if_index;' |
| This is the interface index. |
| |
| `char *if_name' |
| This is the null-terminated index name. |
| |
| |
| -- Function: struct if_nameindex * if_nameindex (void) |
| Preliminary: | MT-Safe | AS-Unsafe heap lock/hurd | AC-Unsafe |
| lock/hurd fd mem | *Note POSIX Safety Concepts::. |
| |
| This function returns an array of `if_nameindex' structures, one |
| for every interface that is present. The end of the list is |
| indicated by a structure with an interface of 0 and a null name |
| pointer. If an error occurs, this function returns a null pointer. |
| |
| The returned structure must be freed with `if_freenameindex' after |
| use. |
| |
| -- Function: void if_freenameindex (struct if_nameindex *PTR) |
| Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note |
| POSIX Safety Concepts::. |
| |
| This function frees the structure returned by an earlier call to |
| `if_nameindex'. |
| |
| |
| File: libc.info, Node: Local Namespace, Next: Internet Namespace, Prev: Interface Naming, Up: Sockets |
| |
| 16.5 The Local Namespace |
| ======================== |
| |
| This section describes the details of the local namespace, whose |
| symbolic name (required when you create a socket) is `PF_LOCAL'. The |
| local namespace is also known as "Unix domain sockets". Another name |
| is file namespace since socket addresses are normally implemented as |
| file names. |
| |
| * Menu: |
| |
| * 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. |
| |
| |
| File: libc.info, Node: Local Namespace Concepts, Next: Local Namespace Details, Up: Local Namespace |
| |
| 16.5.1 Local Namespace Concepts |
| ------------------------------- |
| |
| In the local namespace socket addresses are file names. You can specify |
| any file name you want as the address of the socket, but you must have |
| write permission on the directory containing it. It's common to put |
| these files in the `/tmp' directory. |
| |
| One peculiarity of the local namespace is that the name is only used |
| when opening the connection; once open the address is not meaningful and |
| may not exist. |
| |
| Another peculiarity is that you cannot connect to such a socket from |
| another machine-not even if the other machine shares the file system |
| which contains the name of the socket. You can see the socket in a |
| directory listing, but connecting to it never succeeds. Some programs |
| take advantage of this, such as by asking the client to send its own |
| process ID, and using the process IDs to distinguish between clients. |
| However, we recommend you not use this method in protocols you design, |
| as we might someday permit connections from other machines that mount |
| the same file systems. Instead, send each new client an identifying |
| number if you want it to have one. |
| |
| After you close a socket in the local namespace, you should delete |
| the file name from the file system. Use `unlink' or `remove' to do |
| this; see *note Deleting Files::. |
| |
| The local namespace supports just one protocol for any communication |
| style; it is protocol number `0'. |
| |
| |
| File: libc.info, Node: Local Namespace Details, Next: Local Socket Example, Prev: Local Namespace Concepts, Up: Local Namespace |
| |
| 16.5.2 Details of Local Namespace |
| --------------------------------- |
| |
| To create a socket in the local namespace, use the constant `PF_LOCAL' |
| as the NAMESPACE argument to `socket' or `socketpair'. This constant |
| is defined in `sys/socket.h'. |
| |
| -- Macro: int PF_LOCAL |
| This designates the local namespace, in which socket addresses are |
| local names, and its associated family of protocols. `PF_LOCAL' |
| is the macro used by POSIX.1g. |
| |
| -- Macro: int PF_UNIX |
| This is a synonym for `PF_LOCAL', for compatibility's sake. |
| |
| -- Macro: int PF_FILE |
| This is a synonym for `PF_LOCAL', for compatibility's sake. |
| |
| The structure for specifying socket names in the local namespace is |
| defined in the header file `sys/un.h': |
| |
| -- Data Type: struct sockaddr_un |
| This structure is used to specify local namespace socket |
| addresses. It has the following members: |
| |
| `short int sun_family' |
| This identifies the address family or format of the socket |
| address. You should store the value `AF_LOCAL' to designate |
| the local namespace. *Note Socket Addresses::. |
| |
| `char sun_path[108]' |
| This is the file name to use. |
| |
| *Incomplete:* Why is 108 a magic number? RMS suggests making |
| this a zero-length array and tweaking the following example |
| to use `alloca' to allocate an appropriate amount of storage |
| based on the length of the filename. |
| |
| You should compute the LENGTH parameter for a socket address in the |
| local namespace as the sum of the size of the `sun_family' component |
| and the string length (_not_ the allocation size!) of the file name |
| string. This can be done using the macro `SUN_LEN': |
| |
| -- Macro: int SUN_LEN (_struct sockaddr_un *_ PTR) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro computes the length of the socket address in the local |
| namespace. |
| |
| |
| File: libc.info, Node: Local Socket Example, Prev: Local Namespace Details, Up: Local Namespace |
| |
| 16.5.3 Example of Local-Namespace Sockets |
| ----------------------------------------- |
| |
| Here is an example showing how to create and name a socket in the local |
| namespace. |
| |
| |
| #include <stddef.h> |
| #include <stdio.h> |
| #include <errno.h> |
| #include <stdlib.h> |
| #include <string.h> |
| #include <sys/socket.h> |
| #include <sys/un.h> |
| |
| int |
| make_named_socket (const char *filename) |
| { |
| struct sockaddr_un name; |
| int sock; |
| size_t size; |
| |
| /* Create the socket. */ |
| sock = socket (PF_LOCAL, SOCK_DGRAM, 0); |
| if (sock < 0) |
| { |
| perror ("socket"); |
| exit (EXIT_FAILURE); |
| } |
| |
| /* Bind a name to the socket. */ |
| name.sun_family = AF_LOCAL; |
| strncpy (name.sun_path, filename, sizeof (name.sun_path)); |
| name.sun_path[sizeof (name.sun_path) - 1] = '\0'; |
| |
| /* The size of the address is |
| the offset of the start of the filename, |
| plus its length (not including the terminating null byte). |
| Alternatively you can just do: |
| size = SUN_LEN (&name); |
| */ |
| size = (offsetof (struct sockaddr_un, sun_path) |
| + strlen (name.sun_path)); |
| |
| if (bind (sock, (struct sockaddr *) &name, size) < 0) |
| { |
| perror ("bind"); |
| exit (EXIT_FAILURE); |
| } |
| |
| return sock; |
| } |
| |
| |
| File: libc.info, Node: Internet Namespace, Next: Misc Namespaces, Prev: Local Namespace, Up: Sockets |
| |
| 16.6 The Internet Namespace |
| =========================== |
| |
| This section describes the details of the protocols and socket naming |
| conventions used in the Internet namespace. |
| |
| Originally the Internet namespace used only IP version 4 (IPv4). |
| With the growing number of hosts on the Internet, a new protocol with a |
| larger address space was necessary: IP version 6 (IPv6). IPv6 |
| introduces 128-bit addresses (IPv4 has 32-bit addresses) and other |
| features, and will eventually replace IPv4. |
| |
| To create a socket in the IPv4 Internet namespace, use the symbolic |
| name `PF_INET' of this namespace as the NAMESPACE argument to `socket' |
| or `socketpair'. For IPv6 addresses you need the macro `PF_INET6'. |
| These macros are defined in `sys/socket.h'. |
| |
| -- Macro: int PF_INET |
| This designates the IPv4 Internet namespace and associated family |
| of protocols. |
| |
| -- Macro: int PF_INET6 |
| This designates the IPv6 Internet namespace and associated family |
| of protocols. |
| |
| A socket address for the Internet namespace includes the following |
| components: |
| |
| * The address of the machine you want to connect to. Internet |
| addresses can be specified in several ways; these are discussed in |
| *note Internet Address Formats::, *note Host Addresses:: and *note |
| Host Names::. |
| |
| * A port number for that machine. *Note Ports::. |
| |
| You must ensure that the address and port number are represented in a |
| canonical format called "network byte order". *Note Byte Order::, for |
| information about this. |
| |
| * Menu: |
| |
| * 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. |
| |
| |
| File: libc.info, Node: Internet Address Formats, Next: Host Addresses, Up: Internet Namespace |
| |
| 16.6.1 Internet Socket Address Formats |
| -------------------------------------- |
| |
| In the Internet namespace, for both IPv4 (`AF_INET') and IPv6 |
| (`AF_INET6'), a socket address consists of a host address and a port on |
| that host. In addition, the protocol you choose serves effectively as |
| a part of the address because local port numbers are meaningful only |
| within a particular protocol. |
| |
| The data types for representing socket addresses in the Internet |
| namespace are defined in the header file `netinet/in.h'. |
| |
| -- Data Type: struct sockaddr_in |
| This is the data type used to represent socket addresses in the |
| Internet namespace. It has the following members: |
| |
| `sa_family_t sin_family' |
| This identifies the address family or format of the socket |
| address. You should store the value `AF_INET' in this |
| member. The address family is stored in host byte order. |
| *Note Socket Addresses::. |
| |
| `struct in_addr sin_addr' |
| This is the IPv4 address. *Note Host Addresses::, and *note |
| Host Names::, for how to get a value to store here. The IPv4 |
| address is stored in network byte order. |
| |
| `unsigned short int sin_port' |
| This is the port number. *Note Ports::. The port number is |
| stored in network byte order. |
| |
| When you call `bind' or `getsockname', you should specify `sizeof |
| (struct sockaddr_in)' as the LENGTH parameter if you are using an IPv4 |
| Internet namespace socket address. |
| |
| -- Data Type: struct sockaddr_in6 |
| This is the data type used to represent socket addresses in the |
| IPv6 namespace. It has the following members: |
| |
| `sa_family_t sin6_family' |
| This identifies the address family or format of the socket |
| address. You should store the value of `AF_INET6' in this |
| member. *Note Socket Addresses::. The address family is |
| stored in host byte order. |
| |
| `struct in6_addr sin6_addr' |
| This is the IPv6 address of the host machine. *Note Host |
| Addresses::, and *note Host Names::, for how to get a value |
| to store here. The address is stored in network byte order. |
| |
| `uint32_t sin6_flowinfo' |
| This combines the IPv6 traffic class and flow label values, |
| as found in the IPv6 header. This field is stored in network |
| byte order. Only the 28 lower bits (of the number in network |
| byte order) are used; the remainig bits must be zero. The |
| lower 20 bits are the flow label, and bits 20 to 27 are the |
| the traffic class. Typically, this field is zero. |
| |
| `uint32_t sin6_scope_id' |
| For link-local addresses, this identifies the interface on |
| which this address is valid. The scope ID is stored in host |
| byte order. Typically, this field is zero. |
| |
| `uint16_t sin6_port' |
| This is the port number. *Note Ports::. The port number is |
| stored in network byte order. |
| |
| |
| |
| File: libc.info, Node: Host Addresses, Next: Ports, Prev: Internet Address Formats, Up: Internet Namespace |
| |
| 16.6.2 Host Addresses |
| --------------------- |
| |
| Each computer on the Internet has one or more "Internet addresses", |
| numbers which identify that computer among all those on the Internet. |
| Users typically write IPv4 numeric host addresses as sequences of four |
| numbers, separated by periods, as in `128.52.46.32', and IPv6 numeric |
| host addresses as sequences of up to eight numbers separated by colons, |
| as in `5f03:1200:836f:c100::1'. |
| |
| Each computer also has one or more "host names", which are strings |
| of words separated by periods, as in `www.gnu.org'. |
| |
| Programs that let the user specify a host typically accept both |
| numeric addresses and host names. To open a connection a program needs |
| a numeric address, and so must convert a host name to the numeric |
| address it stands for. |
| |
| * Menu: |
| |
| * 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. |
| |
| |
| File: libc.info, Node: Abstract Host Addresses, Next: Host Address Data Type, Up: Host Addresses |
| |
| 16.6.2.1 Internet Host Addresses |
| ................................ |
| |
| Each computer on the Internet has one or more Internet addresses, |
| numbers which identify that computer among all those on the Internet. |
| |
| An IPv4 Internet host address is a number containing four bytes of data. |
| Historically these are divided into two parts, a "network number" and a |
| "local network address number" within that network. In the mid-1990s |
| classless addresses were introduced which changed this behavior. Since |
| some functions implicitly expect the old definitions, we first describe |
| the class-based network and will then describe classless addresses. |
| IPv6 uses only classless addresses and therefore the following |
| paragraphs don't apply. |
| |
| The class-based IPv4 network number consists of the first one, two or |
| three bytes; the rest of the bytes are the local address. |
| |
| IPv4 network numbers are registered with the Network Information |
| Center (NIC), and are divided into three classes--A, B and C. The local |
| network address numbers of individual machines are registered with the |
| administrator of the particular network. |
| |
| Class A networks have single-byte numbers in the range 0 to 127. |
| There are only a small number of Class A networks, but they can each |
| support a very large number of hosts. Medium-sized Class B networks |
| have two-byte network numbers, with the first byte in the range 128 to |
| 191. Class C networks are the smallest; they have three-byte network |
| numbers, with the first byte in the range 192-255. Thus, the first 1, |
| 2, or 3 bytes of an Internet address specify a network. The remaining |
| bytes of the Internet address specify the address within that network. |
| |
| The Class A network 0 is reserved for broadcast to all networks. In |
| addition, the host number 0 within each network is reserved for |
| broadcast to all hosts in that network. These uses are obsolete now |
| but for compatibility reasons you shouldn't use network 0 and host |
| number 0. |
| |
| The Class A network 127 is reserved for loopback; you can always use |
| the Internet address `127.0.0.1' to refer to the host machine. |
| |
| Since a single machine can be a member of multiple networks, it can |
| have multiple Internet host addresses. However, there is never |
| supposed to be more than one machine with the same host address. |
| |
| There are four forms of the "standard numbers-and-dots notation" for |
| Internet addresses: |
| |
| `A.B.C.D' |
| This specifies all four bytes of the address individually and is |
| the commonly used representation. |
| |
| `A.B.C' |
| The last part of the address, C, is interpreted as a 2-byte |
| quantity. This is useful for specifying host addresses in a Class |
| B network with network address number `A.B'. |
| |
| `A.B' |
| The last part of the address, B, is interpreted as a 3-byte |
| quantity. This is useful for specifying host addresses in a Class |
| A network with network address number A. |
| |
| `A' |
| If only one part is given, this corresponds directly to the host |
| address number. |
| |
| Within each part of the address, the usual C conventions for |
| specifying the radix apply. In other words, a leading `0x' or `0X' |
| implies hexadecimal radix; a leading `0' implies octal; and otherwise |
| decimal radix is assumed. |
| |
| Classless Addresses |
| ................... |
| |
| IPv4 addresses (and IPv6 addresses also) are now considered classless; |
| the distinction between classes A, B and C can be ignored. Instead an |
| IPv4 host address consists of a 32-bit address and a 32-bit mask. The |
| mask contains set bits for the network part and cleared bits for the |
| host part. The network part is contiguous from the left, with the |
| remaining bits representing the host. As a consequence, the netmask can |
| simply be specified as the number of set bits. Classes A, B and C are |
| just special cases of this general rule. For example, class A addresses |
| have a netmask of `255.0.0.0' or a prefix length of 8. |
| |
| Classless IPv4 network addresses are written in numbers-and-dots |
| notation with the prefix length appended and a slash as separator. For |
| example the class A network 10 is written as `10.0.0.0/8'. |
| |
| IPv6 Addresses |
| .............. |
| |
| IPv6 addresses contain 128 bits (IPv4 has 32 bits) of data. A host |
| address is usually written as eight 16-bit hexadecimal numbers that are |
| separated by colons. Two colons are used to abbreviate strings of |
| consecutive zeros. For example, the IPv6 loopback address |
| `0:0:0:0:0:0:0:1' can just be written as `::1'. |
| |
| |
| File: libc.info, Node: Host Address Data Type, Next: Host Address Functions, Prev: Abstract Host Addresses, Up: Host Addresses |
| |
| 16.6.2.2 Host Address Data Type |
| ............................... |
| |
| IPv4 Internet host addresses are represented in some contexts as |
| integers (type `uint32_t'). In other contexts, the integer is packaged |
| inside a structure of type `struct in_addr'. It would be better if the |
| usage were made consistent, but it is not hard to extract the integer |
| from the structure or put the integer into a structure. |
| |
| You will find older code that uses `unsigned long int' for IPv4 |
| Internet host addresses instead of `uint32_t' or `struct in_addr'. |
| Historically `unsigned long int' was a 32-bit number but with 64-bit |
| machines this has changed. Using `unsigned long int' might break the |
| code if it is used on machines where this type doesn't have 32 bits. |
| `uint32_t' is specified by Unix98 and guaranteed to have 32 bits. |
| |
| IPv6 Internet host addresses have 128 bits and are packaged inside a |
| structure of type `struct in6_addr'. |
| |
| The following basic definitions for Internet addresses are declared |
| in the header file `netinet/in.h': |
| |
| -- Data Type: struct in_addr |
| This data type is used in certain contexts to contain an IPv4 |
| Internet host address. It has just one field, named `s_addr', |
| which records the host address number as an `uint32_t'. |
| |
| -- Macro: uint32_t INADDR_LOOPBACK |
| You can use this constant to stand for "the address of this |
| machine," instead of finding its actual address. It is the IPv4 |
| Internet address `127.0.0.1', which is usually called `localhost'. |
| This special constant saves you the trouble of looking up the |
| address of your own machine. Also, the system usually implements |
| `INADDR_LOOPBACK' specially, avoiding any network traffic for the |
| case of one machine talking to itself. |
| |
| -- Macro: uint32_t INADDR_ANY |
| You can use this constant to stand for "any incoming address" when |
| binding to an address. *Note Setting Address::. This is the usual |
| address to give in the `sin_addr' member of `struct sockaddr_in' |
| when you want to accept Internet connections. |
| |
| -- Macro: uint32_t INADDR_BROADCAST |
| This constant is the address you use to send a broadcast message. |
| |
| -- Macro: uint32_t INADDR_NONE |
| This constant is returned by some functions to indicate an error. |
| |
| -- Data Type: struct in6_addr |
| This data type is used to store an IPv6 address. It stores 128 |
| bits of data, which can be accessed (via a union) in a variety of |
| ways. |
| |
| -- Constant: struct in6_addr in6addr_loopback |
| This constant is the IPv6 address `::1', the loopback address. See |
| above for a description of what this means. The macro |
| `IN6ADDR_LOOPBACK_INIT' is provided to allow you to initialize your |
| own variables to this value. |
| |
| -- Constant: struct in6_addr in6addr_any |
| This constant is the IPv6 address `::', the unspecified address. |
| See above for a description of what this means. The macro |
| `IN6ADDR_ANY_INIT' is provided to allow you to initialize your own |
| variables to this value. |
| |
| |
| File: libc.info, Node: Host Address Functions, Next: Host Names, Prev: Host Address Data Type, Up: Host Addresses |
| |
| 16.6.2.3 Host Address Functions |
| ............................... |
| |
| These additional functions for manipulating Internet addresses are |
| declared in the header file `arpa/inet.h'. They represent Internet |
| addresses in network byte order, and network numbers and |
| local-address-within-network numbers in host byte order. *Note Byte |
| Order::, for an explanation of network and host byte order. |
| |
| -- Function: int inet_aton (const char *NAME, struct in_addr *ADDR) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| This function converts the IPv4 Internet host address NAME from |
| the standard numbers-and-dots notation into binary data and stores |
| it in the `struct in_addr' that ADDR points to. `inet_aton' |
| returns nonzero if the address is valid, zero if not. |
| |
| -- Function: uint32_t inet_addr (const char *NAME) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| This function converts the IPv4 Internet host address NAME from the |
| standard numbers-and-dots notation into binary data. If the input |
| is not valid, `inet_addr' returns `INADDR_NONE'. This is an |
| obsolete interface to `inet_aton', described immediately above. It |
| is obsolete because `INADDR_NONE' is a valid address |
| (255.255.255.255), and `inet_aton' provides a cleaner way to |
| indicate error return. |
| |
| -- Function: uint32_t inet_network (const char *NAME) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| This function extracts the network number from the address NAME, |
| given in the standard numbers-and-dots notation. The returned |
| address is in host order. If the input is not valid, |
| `inet_network' returns `-1'. |
| |
| The function works only with traditional IPv4 class A, B and C |
| network types. It doesn't work with classless addresses and |
| shouldn't be used anymore. |
| |
| -- Function: char * inet_ntoa (struct in_addr ADDR) |
| Preliminary: | MT-Safe locale | AS-Unsafe race | AC-Safe | *Note |
| POSIX Safety Concepts::. |
| |
| This function converts the IPv4 Internet host address ADDR to a |
| string in the standard numbers-and-dots notation. The return |
| value is a pointer into a statically-allocated buffer. Subsequent |
| calls will overwrite the same buffer, so you should copy the |
| string if you need to save it. |
| |
| In multi-threaded programs each thread has its own |
| statically-allocated buffer. But still subsequent calls of |
| `inet_ntoa' in the same thread will overwrite the result of the |
| last call. |
| |
| Instead of `inet_ntoa' the newer function `inet_ntop' which is |
| described below should be used since it handles both IPv4 and IPv6 |
| addresses. |
| |
| -- Function: struct in_addr inet_makeaddr (uint32_t NET, uint32_t |
| LOCAL) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function makes an IPv4 Internet host address by combining the |
| network number NET with the local-address-within-network number |
| LOCAL. |
| |
| -- Function: uint32_t inet_lnaof (struct in_addr ADDR) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function returns the local-address-within-network part of the |
| Internet host address ADDR. |
| |
| The function works only with traditional IPv4 class A, B and C |
| network types. It doesn't work with classless addresses and |
| shouldn't be used anymore. |
| |
| -- Function: uint32_t inet_netof (struct in_addr ADDR) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function returns the network number part of the Internet host |
| address ADDR. |
| |
| The function works only with traditional IPv4 class A, B and C |
| network types. It doesn't work with classless addresses and |
| shouldn't be used anymore. |
| |
| -- Function: int inet_pton (int AF, const char *CP, void *BUF) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| This function converts an Internet address (either IPv4 or IPv6) |
| from presentation (textual) to network (binary) format. AF should |
| be either `AF_INET' or `AF_INET6', as appropriate for the type of |
| address being converted. CP is a pointer to the input string, and |
| BUF is a pointer to a buffer for the result. It is the caller's |
| responsibility to make sure the buffer is large enough. |
| |
| -- Function: const char * inet_ntop (int AF, const void *CP, char |
| *BUF, socklen_t LEN) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| This function converts an Internet address (either IPv4 or IPv6) |
| from network (binary) to presentation (textual) form. AF should be |
| either `AF_INET' or `AF_INET6', as appropriate. CP is a pointer |
| to the address to be converted. BUF should be a pointer to a |
| buffer to hold the result, and LEN is the length of this buffer. |
| The return value from the function will be this buffer address. |
| |
| |
| File: libc.info, Node: Host Names, Prev: Host Address Functions, Up: Host Addresses |
| |
| 16.6.2.4 Host Names |
| ................... |
| |
| Besides the standard numbers-and-dots notation for Internet addresses, |
| you can also refer to a host by a symbolic name. The advantage of a |
| symbolic name is that it is usually easier to remember. For example, |
| the machine with Internet address `158.121.106.19' is also known as |
| `alpha.gnu.org'; and other machines in the `gnu.org' domain can refer |
| to it simply as `alpha'. |
| |
| Internally, the system uses a database to keep track of the mapping |
| between host names and host numbers. This database is usually either |
| the file `/etc/hosts' or an equivalent provided by a name server. The |
| functions and other symbols for accessing this database are declared in |
| `netdb.h'. They are BSD features, defined unconditionally if you |
| include `netdb.h'. |
| |
| -- Data Type: struct hostent |
| This data type is used to represent an entry in the hosts |
| database. It has the following members: |
| |
| `char *h_name' |
| This is the "official" name of the host. |
| |
| `char **h_aliases' |
| These are alternative names for the host, represented as a |
| null-terminated vector of strings. |
| |
| `int h_addrtype' |
| This is the host address type; in practice, its value is |
| always either `AF_INET' or `AF_INET6', with the latter being |
| used for IPv6 hosts. In principle other kinds of addresses |
| could be represented in the database as well as Internet |
| addresses; if this were done, you might find a value in this |
| field other than `AF_INET' or `AF_INET6'. *Note Socket |
| Addresses::. |
| |
| `int h_length' |
| This is the length, in bytes, of each address. |
| |
| `char **h_addr_list' |
| This is the vector of addresses for the host. (Recall that |
| the host might be connected to multiple networks and have |
| different addresses on each one.) The vector is terminated |
| by a null pointer. |
| |
| `char *h_addr' |
| This is a synonym for `h_addr_list[0]'; in other words, it is |
| the first host address. |
| |
| As far as the host database is concerned, each address is just a |
| block of memory `h_length' bytes long. But in other contexts there is |
| an implicit assumption that you can convert IPv4 addresses to a `struct |
| in_addr' or an `uint32_t'. Host addresses in a `struct hostent' |
| structure are always given in network byte order; see *note Byte |
| Order::. |
| |
| You can use `gethostbyname', `gethostbyname2' or `gethostbyaddr' to |
| search the hosts database for information about a particular host. The |
| information is returned in a statically-allocated structure; you must |
| copy the information if you need to save it across calls. You can also |
| use `getaddrinfo' and `getnameinfo' to obtain this information. |
| |
| -- Function: struct hostent * gethostbyname (const char *NAME) |
| Preliminary: | MT-Unsafe race:hostbyname env locale | AS-Unsafe |
| dlopen plugin corrupt heap lock | AC-Unsafe lock corrupt mem fd | |
| *Note POSIX Safety Concepts::. |
| |
| The `gethostbyname' function returns information about the host |
| named NAME. If the lookup fails, it returns a null pointer. |
| |
| -- Function: struct hostent * gethostbyname2 (const char *NAME, int AF) |
| Preliminary: | MT-Unsafe race:hostbyname2 env locale | AS-Unsafe |
| dlopen plugin corrupt heap lock | AC-Unsafe lock corrupt mem fd | |
| *Note POSIX Safety Concepts::. |
| |
| The `gethostbyname2' function is like `gethostbyname', but allows |
| the caller to specify the desired address family (e.g. `AF_INET' |
| or `AF_INET6') of the result. |
| |
| -- Function: struct hostent * gethostbyaddr (const void *ADDR, |
| socklen_t LENGTH, int FORMAT) |
| Preliminary: | MT-Unsafe race:hostbyaddr env locale | AS-Unsafe |
| dlopen plugin corrupt heap lock | AC-Unsafe lock corrupt mem fd | |
| *Note POSIX Safety Concepts::. |
| |
| The `gethostbyaddr' function returns information about the host |
| with Internet address ADDR. The parameter ADDR is not really a |
| pointer to char - it can be a pointer to an IPv4 or an IPv6 |
| address. The LENGTH argument is the size (in bytes) of the address |
| at ADDR. FORMAT specifies the address format; for an IPv4 |
| Internet address, specify a value of `AF_INET'; for an IPv6 |
| Internet address, use `AF_INET6'. |
| |
| If the lookup fails, `gethostbyaddr' returns a null pointer. |
| |
| If the name lookup by `gethostbyname' or `gethostbyaddr' fails, you |
| can find out the reason by looking at the value of the variable |
| `h_errno'. (It would be cleaner design for these functions to set |
| `errno', but use of `h_errno' is compatible with other systems.) |
| |
| Here are the error codes that you may find in `h_errno': |
| |
| `HOST_NOT_FOUND' |
| No such host is known in the database. |
| |
| `TRY_AGAIN' |
| This condition happens when the name server could not be |
| contacted. If you try again later, you may succeed then. |
| |
| `NO_RECOVERY' |
| A non-recoverable error occurred. |
| |
| `NO_ADDRESS' |
| The host database contains an entry for the name, but it doesn't |
| have an associated Internet address. |
| |
| The lookup functions above all have one thing in common: they are not |
| reentrant and therefore unusable in multi-threaded applications. |
| Therefore provides the GNU C Library a new set of functions which can be |
| used in this context. |
| |
| -- Function: int gethostbyname_r (const char *restrict NAME, struct |
| hostent *restrict RESULT_BUF, char *restrict BUF, size_t |
| BUFLEN, struct hostent **restrict RESULT, int *restrict |
| H_ERRNOP) |
| Preliminary: | MT-Safe env locale | AS-Unsafe dlopen plugin |
| corrupt heap lock | AC-Unsafe lock corrupt mem fd | *Note POSIX |
| Safety Concepts::. |
| |
| The `gethostbyname_r' function returns information about the host |
| named NAME. The caller must pass a pointer to an object of type |
| `struct hostent' in the RESULT_BUF parameter. In addition the |
| function may need extra buffer space and the caller must pass a |
| pointer and the size of the buffer in the BUF and BUFLEN |
| parameters. |
| |
| A pointer to the buffer, in which the result is stored, is |
| available in `*RESULT' after the function call successfully |
| returned. The buffer passed as the BUF parameter can be freed |
| only once the caller has finished with the result hostent struct, |
| or has copied it including all the other memory that it points to. |
| If an error occurs or if no entry is found, the pointer `*RESULT' |
| is a null pointer. Success is signalled by a zero return value. |
| If the function failed the return value is an error number. In |
| addition to the errors defined for `gethostbyname' it can also be |
| `ERANGE'. In this case the call should be repeated with a larger |
| buffer. Additional error information is not stored in the global |
| variable `h_errno' but instead in the object pointed to by |
| H_ERRNOP. |
| |
| Here's a small example: |
| struct hostent * |
| gethostname (char *host) |
| { |
| struct hostent *hostbuf, *hp; |
| size_t hstbuflen; |
| char *tmphstbuf; |
| int res; |
| int herr; |
| |
| hostbuf = malloc (sizeof (struct hostent)); |
| hstbuflen = 1024; |
| tmphstbuf = malloc (hstbuflen); |
| |
| while ((res = gethostbyname_r (host, hostbuf, tmphstbuf, hstbuflen, |
| &hp, &herr)) == ERANGE) |
| { |
| /* Enlarge the buffer. */ |
| hstbuflen *= 2; |
| tmphstbuf = realloc (tmphstbuf, hstbuflen); |
| } |
| |
| free (tmphstbuf); |
| /* Check for errors. */ |
| if (res || hp == NULL) |
| return NULL; |
| return hp; |
| } |
| |
| -- Function: int gethostbyname2_r (const char *NAME, int AF, struct |
| hostent *restrict RESULT_BUF, char *restrict BUF, size_t |
| BUFLEN, struct hostent **restrict RESULT, int *restrict |
| H_ERRNOP) |
| Preliminary: | MT-Safe env locale | AS-Unsafe dlopen plugin |
| corrupt heap lock | AC-Unsafe lock corrupt mem fd | *Note POSIX |
| Safety Concepts::. |
| |
| The `gethostbyname2_r' function is like `gethostbyname_r', but |
| allows the caller to specify the desired address family (e.g. |
| `AF_INET' or `AF_INET6') for the result. |
| |
| -- Function: int gethostbyaddr_r (const void *ADDR, socklen_t LENGTH, |
| int FORMAT, struct hostent *restrict RESULT_BUF, char |
| *restrict BUF, size_t BUFLEN, struct hostent **restrict |
| RESULT, int *restrict H_ERRNOP) |
| Preliminary: | MT-Safe env locale | AS-Unsafe dlopen plugin |
| corrupt heap lock | AC-Unsafe lock corrupt mem fd | *Note POSIX |
| Safety Concepts::. |
| |
| The `gethostbyaddr_r' function returns information about the host |
| with Internet address ADDR. The parameter ADDR is not really a |
| pointer to char - it can be a pointer to an IPv4 or an IPv6 |
| address. The LENGTH argument is the size (in bytes) of the address |
| at ADDR. FORMAT specifies the address format; for an IPv4 |
| Internet address, specify a value of `AF_INET'; for an IPv6 |
| Internet address, use `AF_INET6'. |
| |
| Similar to the `gethostbyname_r' function, the caller must provide |
| buffers for the result and memory used internally. In case of |
| success the function returns zero. Otherwise the value is an |
| error number where `ERANGE' has the special meaning that the |
| caller-provided buffer is too small. |
| |
| You can also scan the entire hosts database one entry at a time using |
| `sethostent', `gethostent' and `endhostent'. Be careful when using |
| these functions because they are not reentrant. |
| |
| -- Function: void sethostent (int STAYOPEN) |
| Preliminary: | MT-Unsafe race:hostent env locale | AS-Unsafe |
| dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note |
| POSIX Safety Concepts::. |
| |
| This function opens the hosts database to begin scanning it. You |
| can then call `gethostent' to read the entries. |
| |
| If the STAYOPEN argument is nonzero, this sets a flag so that |
| subsequent calls to `gethostbyname' or `gethostbyaddr' will not |
| close the database (as they usually would). This makes for more |
| efficiency if you call those functions several times, by avoiding |
| reopening the database for each call. |
| |
| -- Function: struct hostent * gethostent (void) |
| Preliminary: | MT-Unsafe race:hostent race:hostentbuf env locale | |
| AS-Unsafe dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem |
| | *Note POSIX Safety Concepts::. |
| |
| This function returns the next entry in the hosts database. It |
| returns a null pointer if there are no more entries. |
| |
| -- Function: void endhostent (void) |
| Preliminary: | MT-Unsafe race:hostent env locale | AS-Unsafe |
| dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note |
| POSIX Safety Concepts::. |
| |
| This function closes the hosts database. |
| |
| |
| File: libc.info, Node: Ports, Next: Services Database, Prev: Host Addresses, Up: Internet Namespace |
| |
| 16.6.3 Internet Ports |
| --------------------- |
| |
| A socket address in the Internet namespace consists of a machine's |
| Internet address plus a "port number" which distinguishes the sockets |
| on a given machine (for a given protocol). Port numbers range from 0 |
| to 65,535. |
| |
| Port numbers less than `IPPORT_RESERVED' are reserved for standard |
| servers, such as `finger' and `telnet'. There is a database that keeps |
| track of these, and you can use the `getservbyname' function to map a |
| service name onto a port number; see *note Services Database::. |
| |
| If you write a server that is not one of the standard ones defined in |
| the database, you must choose a port number for it. Use a number |
| greater than `IPPORT_USERRESERVED'; such numbers are reserved for |
| servers and won't ever be generated automatically by the system. |
| Avoiding conflicts with servers being run by other users is up to you. |
| |
| When you use a socket without specifying its address, the system |
| generates a port number for it. This number is between |
| `IPPORT_RESERVED' and `IPPORT_USERRESERVED'. |
| |
| On the Internet, it is actually legitimate to have two different |
| sockets with the same port number, as long as they never both try to |
| communicate with the same socket address (host address plus port |
| number). You shouldn't duplicate a port number except in special |
| circumstances where a higher-level protocol requires it. Normally, the |
| system won't let you do it; `bind' normally insists on distinct port |
| numbers. To reuse a port number, you must set the socket option |
| `SO_REUSEADDR'. *Note Socket-Level Options::. |
| |
| These macros are defined in the header file `netinet/in.h'. |
| |
| -- Macro: int IPPORT_RESERVED |
| Port numbers less than `IPPORT_RESERVED' are reserved for |
| superuser use. |
| |
| -- Macro: int IPPORT_USERRESERVED |
| Port numbers greater than or equal to `IPPORT_USERRESERVED' are |
| reserved for explicit use; they will never be allocated |
| automatically. |
| |
| |
| File: libc.info, Node: Services Database, Next: Byte Order, Prev: Ports, Up: Internet Namespace |
| |
| 16.6.4 The Services Database |
| ---------------------------- |
| |
| The database that keeps track of "well-known" services is usually |
| either the file `/etc/services' or an equivalent from a name server. |
| You can use these utilities, declared in `netdb.h', to access the |
| services database. |
| |
| -- Data Type: struct servent |
| This data type holds information about entries from the services |
| database. It has the following members: |
| |
| `char *s_name' |
| This is the "official" name of the service. |
| |
| `char **s_aliases' |
| These are alternate names for the service, represented as an |
| array of strings. A null pointer terminates the array. |
| |
| `int s_port' |
| This is the port number for the service. Port numbers are |
| given in network byte order; see *note Byte Order::. |
| |
| `char *s_proto' |
| This is the name of the protocol to use with this service. |
| *Note Protocols Database::. |
| |
| To get information about a particular service, use the |
| `getservbyname' or `getservbyport' functions. The information is |
| returned in a statically-allocated structure; you must copy the |
| information if you need to save it across calls. |
| |
| -- Function: struct servent * getservbyname (const char *NAME, const |
| char *PROTO) |
| Preliminary: | MT-Unsafe race:servbyname locale | AS-Unsafe dlopen |
| plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX |
| Safety Concepts::. |
| |
| The `getservbyname' function returns information about the service |
| named NAME using protocol PROTO. If it can't find such a service, |
| it returns a null pointer. |
| |
| This function is useful for servers as well as for clients; servers |
| use it to determine which port they should listen on (*note |
| Listening::). |
| |
| -- Function: struct servent * getservbyport (int PORT, const char |
| *PROTO) |
| Preliminary: | MT-Unsafe race:servbyport locale | AS-Unsafe dlopen |
| plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX |
| Safety Concepts::. |
| |
| The `getservbyport' function returns information about the service |
| at port PORT using protocol PROTO. If it can't find such a |
| service, it returns a null pointer. |
| |
| You can also scan the services database using `setservent', |
| `getservent' and `endservent'. Be careful when using these functions |
| because they are not reentrant. |
| |
| -- Function: void setservent (int STAYOPEN) |
| Preliminary: | MT-Unsafe race:servent locale | AS-Unsafe dlopen |
| plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX |
| Safety Concepts::. |
| |
| This function opens the services database to begin scanning it. |
| |
| If the STAYOPEN argument is nonzero, this sets a flag so that |
| subsequent calls to `getservbyname' or `getservbyport' will not |
| close the database (as they usually would). This makes for more |
| efficiency if you call those functions several times, by avoiding |
| reopening the database for each call. |
| |
| -- Function: struct servent * getservent (void) |
| Preliminary: | MT-Unsafe race:servent race:serventbuf locale | |
| AS-Unsafe dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem |
| | *Note POSIX Safety Concepts::. |
| |
| This function returns the next entry in the services database. If |
| there are no more entries, it returns a null pointer. |
| |
| -- Function: void endservent (void) |
| Preliminary: | MT-Unsafe race:servent locale | AS-Unsafe dlopen |
| plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX |
| Safety Concepts::. |
| |
| This function closes the services database. |
| |
| |
| File: libc.info, Node: Byte Order, Next: Protocols Database, Prev: Services Database, Up: Internet Namespace |
| |
| 16.6.5 Byte Order Conversion |
| ---------------------------- |
| |
| Different kinds of computers use different conventions for the ordering |
| of bytes within a word. Some computers put the most significant byte |
| within a word first (this is called "big-endian" order), and others put |
| it last ("little-endian" order). |
| |
| So that machines with different byte order conventions can |
| communicate, the Internet protocols specify a canonical byte order |
| convention for data transmitted over the network. This is known as |
| "network byte order". |
| |
| When establishing an Internet socket connection, you must make sure |
| that the data in the `sin_port' and `sin_addr' members of the |
| `sockaddr_in' structure are represented in network byte order. If you |
| are encoding integer data in the messages sent through the socket, you |
| should convert this to network byte order too. If you don't do this, |
| your program may fail when running on or talking to other kinds of |
| machines. |
| |
| If you use `getservbyname' and `gethostbyname' or `inet_addr' to get |
| the port number and host address, the values are already in network |
| byte order, and you can copy them directly into the `sockaddr_in' |
| structure. |
| |
| Otherwise, you have to convert the values explicitly. Use `htons' |
| and `ntohs' to convert values for the `sin_port' member. Use `htonl' |
| and `ntohl' to convert IPv4 addresses for the `sin_addr' member. |
| (Remember, `struct in_addr' is equivalent to `uint32_t'.) These |
| functions are declared in `netinet/in.h'. |
| |
| -- Function: uint16_t htons (uint16_t HOSTSHORT) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function converts the `uint16_t' integer HOSTSHORT from host |
| byte order to network byte order. |
| |
| -- Function: uint16_t ntohs (uint16_t NETSHORT) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function converts the `uint16_t' integer NETSHORT from |
| network byte order to host byte order. |
| |
| -- Function: uint32_t htonl (uint32_t HOSTLONG) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function converts the `uint32_t' integer HOSTLONG from host |
| byte order to network byte order. |
| |
| This is used for IPv4 Internet addresses. |
| |
| -- Function: uint32_t ntohl (uint32_t NETLONG) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function converts the `uint32_t' integer NETLONG from network |
| byte order to host byte order. |
| |
| This is used for IPv4 Internet addresses. |
| |
| |
| File: libc.info, Node: Protocols Database, Next: Inet Example, Prev: Byte Order, Up: Internet Namespace |
| |
| 16.6.6 Protocols Database |
| ------------------------- |
| |
| The communications protocol used with a socket controls low-level |
| details of how data are exchanged. For example, the protocol implements |
| things like checksums to detect errors in transmissions, and routing |
| instructions for messages. Normal user programs have little reason to |
| mess with these details directly. |
| |
| The default communications protocol for the Internet namespace |
| depends on the communication style. For stream communication, the |
| default is TCP ("transmission control protocol"). For datagram |
| communication, the default is UDP ("user datagram protocol"). For |
| reliable datagram communication, the default is RDP ("reliable datagram |
| protocol"). You should nearly always use the default. |
| |
| Internet protocols are generally specified by a name instead of a |
| number. The network protocols that a host knows about are stored in a |
| database. This is usually either derived from the file |
| `/etc/protocols', or it may be an equivalent provided by a name server. |
| You look up the protocol number associated with a named protocol in the |
| database using the `getprotobyname' function. |
| |
| Here are detailed descriptions of the utilities for accessing the |
| protocols database. These are declared in `netdb.h'. |
| |
| -- Data Type: struct protoent |
| This data type is used to represent entries in the network |
| protocols database. It has the following members: |
| |
| `char *p_name' |
| This is the official name of the protocol. |
| |
| `char **p_aliases' |
| These are alternate names for the protocol, specified as an |
| array of strings. The last element of the array is a null |
| pointer. |
| |
| `int p_proto' |
| This is the protocol number (in host byte order); use this |
| member as the PROTOCOL argument to `socket'. |
| |
| You can use `getprotobyname' and `getprotobynumber' to search the |
| protocols database for a specific protocol. The information is |
| returned in a statically-allocated structure; you must copy the |
| information if you need to save it across calls. |
| |
| -- Function: struct protoent * getprotobyname (const char *NAME) |
| Preliminary: | MT-Unsafe race:protobyname locale | AS-Unsafe |
| dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note |
| POSIX Safety Concepts::. |
| |
| The `getprotobyname' function returns information about the |
| network protocol named NAME. If there is no such protocol, it |
| returns a null pointer. |
| |
| -- Function: struct protoent * getprotobynumber (int PROTOCOL) |
| Preliminary: | MT-Unsafe race:protobynumber locale | AS-Unsafe |
| dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note |
| POSIX Safety Concepts::. |
| |
| The `getprotobynumber' function returns information about the |
| network protocol with number PROTOCOL. If there is no such |
| protocol, it returns a null pointer. |
| |
| You can also scan the whole protocols database one protocol at a |
| time by using `setprotoent', `getprotoent' and `endprotoent'. Be |
| careful when using these functions because they are not reentrant. |
| |
| -- Function: void setprotoent (int STAYOPEN) |
| Preliminary: | MT-Unsafe race:protoent locale | AS-Unsafe dlopen |
| plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX |
| Safety Concepts::. |
| |
| This function opens the protocols database to begin scanning it. |
| |
| If the STAYOPEN argument is nonzero, this sets a flag so that |
| subsequent calls to `getprotobyname' or `getprotobynumber' will |
| not close the database (as they usually would). This makes for |
| more efficiency if you call those functions several times, by |
| avoiding reopening the database for each call. |
| |
| -- Function: struct protoent * getprotoent (void) |
| Preliminary: | MT-Unsafe race:protoent race:protoentbuf locale | |
| AS-Unsafe dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem |
| | *Note POSIX Safety Concepts::. |
| |
| This function returns the next entry in the protocols database. It |
| returns a null pointer if there are no more entries. |
| |
| -- Function: void endprotoent (void) |
| Preliminary: | MT-Unsafe race:protoent locale | AS-Unsafe dlopen |
| plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX |
| Safety Concepts::. |
| |
| This function closes the protocols database. |
| |
| |
| File: libc.info, Node: Inet Example, Prev: Protocols Database, Up: Internet Namespace |
| |
| 16.6.7 Internet Socket Example |
| ------------------------------ |
| |
| Here is an example showing how to create and name a socket in the |
| Internet namespace. The newly created socket exists on the machine that |
| the program is running on. Rather than finding and using the machine's |
| Internet address, this example specifies `INADDR_ANY' as the host |
| address; the system replaces that with the machine's actual address. |
| |
| |
| #include <stdio.h> |
| #include <stdlib.h> |
| #include <sys/socket.h> |
| #include <netinet/in.h> |
| |
| int |
| make_socket (uint16_t port) |
| { |
| int sock; |
| struct sockaddr_in name; |
| |
| /* Create the socket. */ |
| sock = socket (PF_INET, SOCK_STREAM, 0); |
| if (sock < 0) |
| { |
| perror ("socket"); |
| exit (EXIT_FAILURE); |
| } |
| |
| /* Give the socket a name. */ |
| name.sin_family = AF_INET; |
| name.sin_port = htons (port); |
| name.sin_addr.s_addr = htonl (INADDR_ANY); |
| if (bind (sock, (struct sockaddr *) &name, sizeof (name)) < 0) |
| { |
| perror ("bind"); |
| exit (EXIT_FAILURE); |
| } |
| |
| return sock; |
| } |
| |
| Here is another example, showing how you can fill in a `sockaddr_in' |
| structure, given a host name string and a port number: |
| |
| |
| #include <stdio.h> |
| #include <stdlib.h> |
| #include <sys/socket.h> |
| #include <netinet/in.h> |
| #include <netdb.h> |
| |
| void |
| init_sockaddr (struct sockaddr_in *name, |
| const char *hostname, |
| uint16_t port) |
| { |
| struct hostent *hostinfo; |
| |
| name->sin_family = AF_INET; |
| name->sin_port = htons (port); |
| hostinfo = gethostbyname (hostname); |
| if (hostinfo == NULL) |
| { |
| fprintf (stderr, "Unknown host %s.\n", hostname); |
| exit (EXIT_FAILURE); |
| } |
| name->sin_addr = *(struct in_addr *) hostinfo->h_addr; |
| } |
| |
| |
| File: libc.info, Node: Misc Namespaces, Next: Open/Close Sockets, Prev: Internet Namespace, Up: Sockets |
| |
| 16.7 Other Namespaces |
| ===================== |
| |
| Certain other namespaces and associated protocol families are supported |
| but not documented yet because they are not often used. `PF_NS' refers |
| to the Xerox Network Software protocols. `PF_ISO' stands for Open |
| Systems Interconnect. `PF_CCITT' refers to protocols from CCITT. |
| `socket.h' defines these symbols and others naming protocols not |
| actually implemented. |
| |
| `PF_IMPLINK' is used for communicating between hosts and Internet |
| Message Processors. For information on this and `PF_ROUTE', an |
| occasionally-used local area routing protocol, see the GNU Hurd Manual |
| (to appear in the future). |
| |
| |
| File: libc.info, Node: Open/Close Sockets, Next: Connections, Prev: Misc Namespaces, Up: Sockets |
| |
| 16.8 Opening and Closing Sockets |
| ================================ |
| |
| This section describes the actual library functions for opening and |
| closing sockets. The same functions work for all namespaces and |
| connection styles. |
| |
| * Menu: |
| |
| * Creating a Socket:: How to open a socket. |
| * Closing a Socket:: How to close a socket. |
| * Socket Pairs:: These are created like pipes. |
| |
| |
| File: libc.info, Node: Creating a Socket, Next: Closing a Socket, Up: Open/Close Sockets |
| |
| 16.8.1 Creating a Socket |
| ------------------------ |
| |
| The primitive for creating a socket is the `socket' function, declared |
| in `sys/socket.h'. |
| |
| -- Function: int socket (int NAMESPACE, int STYLE, int PROTOCOL) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety |
| Concepts::. |
| |
| This function creates a socket and specifies communication style |
| STYLE, which should be one of the socket styles listed in *note |
| Communication Styles::. The NAMESPACE argument specifies the |
| namespace; it must be `PF_LOCAL' (*note Local Namespace::) or |
| `PF_INET' (*note Internet Namespace::). PROTOCOL designates the |
| specific protocol (*note Socket Concepts::); zero is usually right |
| for PROTOCOL. |
| |
| The return value from `socket' is the file descriptor for the new |
| socket, or `-1' in case of error. The following `errno' error |
| conditions are defined for this function: |
| |
| `EPROTONOSUPPORT' |
| The PROTOCOL or STYLE is not supported by the NAMESPACE |
| specified. |
| |
| `EMFILE' |
| The process already has too many file descriptors open. |
| |
| `ENFILE' |
| The system already has too many file descriptors open. |
| |
| `EACCES' |
| The process does not have the privilege to create a socket of |
| the specified STYLE or PROTOCOL. |
| |
| `ENOBUFS' |
| The system ran out of internal buffer space. |
| |
| The file descriptor returned by the `socket' function supports both |
| read and write operations. However, like pipes, sockets do not |
| support file positioning operations. |
| |
| For examples of how to call the `socket' function, see *note Local |
| Socket Example::, or *note Inet Example::. |
| |
| |
| File: libc.info, Node: Closing a Socket, Next: Socket Pairs, Prev: Creating a Socket, Up: Open/Close Sockets |
| |
| 16.8.2 Closing a Socket |
| ----------------------- |
| |
| When you have finished using a socket, you can simply close its file |
| descriptor with `close'; see *note Opening and Closing Files::. If |
| there is still data waiting to be transmitted over the connection, |
| normally `close' tries to complete this transmission. You can control |
| this behavior using the `SO_LINGER' socket option to specify a timeout |
| period; see *note Socket Options::. |
| |
| You can also shut down only reception or transmission on a |
| connection by calling `shutdown', which is declared in `sys/socket.h'. |
| |
| -- Function: int shutdown (int SOCKET, int HOW) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `shutdown' function shuts down the connection of socket |
| SOCKET. The argument HOW specifies what action to perform: |
| |
| `0' |
| Stop receiving data for this socket. If further data arrives, |
| reject it. |
| |
| `1' |
| Stop trying to transmit data from this socket. Discard any |
| data waiting to be sent. Stop looking for acknowledgement of |
| data already sent; don't retransmit it if it is lost. |
| |
| `2' |
| Stop both reception and transmission. |
| |
| The return value is `0' on success and `-1' on failure. The |
| following `errno' error conditions are defined for this function: |
| |
| `EBADF' |
| SOCKET is not a valid file descriptor. |
| |
| `ENOTSOCK' |
| SOCKET is not a socket. |
| |
| `ENOTCONN' |
| SOCKET is not connected. |
| |
| |
| File: libc.info, Node: Socket Pairs, Prev: Closing a Socket, Up: Open/Close Sockets |
| |
| 16.8.3 Socket Pairs |
| ------------------- |
| |
| A "socket pair" consists of a pair of connected (but unnamed) sockets. |
| It is very similar to a pipe and is used in much the same way. Socket |
| pairs are created with the `socketpair' function, declared in |
| `sys/socket.h'. A socket pair is much like a pipe; the main difference |
| is that the socket pair is bidirectional, whereas the pipe has one |
| input-only end and one output-only end (*note Pipes and FIFOs::). |
| |
| -- Function: int socketpair (int NAMESPACE, int STYLE, int PROTOCOL, |
| int FILEDES[2]) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety |
| Concepts::. |
| |
| This function creates a socket pair, returning the file |
| descriptors in `FILEDES[0]' and `FILEDES[1]'. The socket pair is |
| a full-duplex communications channel, so that both reading and |
| writing may be performed at either end. |
| |
| The NAMESPACE, STYLE and PROTOCOL arguments are interpreted as for |
| the `socket' function. STYLE should be one of the communication |
| styles listed in *note Communication Styles::. The NAMESPACE |
| argument specifies the namespace, which must be `AF_LOCAL' (*note |
| Local Namespace::); PROTOCOL specifies the communications |
| protocol, but zero is the only meaningful value. |
| |
| If STYLE specifies a connectionless communication style, then the |
| two sockets you get are not _connected_, strictly speaking, but |
| each of them knows the other as the default destination address, |
| so they can send packets to each other. |
| |
| The `socketpair' function returns `0' on success and `-1' on |
| failure. The following `errno' error conditions are defined for |
| this function: |
| |
| `EMFILE' |
| The process has too many file descriptors open. |
| |
| `EAFNOSUPPORT' |
| The specified namespace is not supported. |
| |
| `EPROTONOSUPPORT' |
| The specified protocol is not supported. |
| |
| `EOPNOTSUPP' |
| The specified protocol does not support the creation of |
| socket pairs. |
| |
| |
| File: libc.info, Node: Connections, Next: Datagrams, Prev: Open/Close Sockets, Up: Sockets |
| |
| 16.9 Using Sockets with Connections |
| =================================== |
| |
| The most common communication styles involve making a connection to a |
| particular other socket, and then exchanging data with that socket over |
| and over. Making a connection is asymmetric; one side (the "client") |
| acts to request a connection, while the other side (the "server") makes |
| a socket and waits for the connection request. |
| |
| * Menu: |
| |
| * 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. |
| |
| |
| File: libc.info, Node: Connecting, Next: Listening, Up: Connections |
| |
| 16.9.1 Making a Connection |
| -------------------------- |
| |
| In making a connection, the client makes a connection while the server |
| waits for and accepts the connection. Here we discuss what the client |
| program must do with the `connect' function, which is declared in |
| `sys/socket.h'. |
| |
| -- Function: int connect (int SOCKET, struct sockaddr *ADDR, socklen_t |
| LENGTH) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `connect' function initiates a connection from the socket with |
| file descriptor SOCKET to the socket whose address is specified by |
| the ADDR and LENGTH arguments. (This socket is typically on |
| another machine, and it must be already set up as a server.) |
| *Note Socket Addresses::, for information about how these |
| arguments are interpreted. |
| |
| Normally, `connect' waits until the server responds to the request |
| before it returns. You can set nonblocking mode on the socket |
| SOCKET to make `connect' return immediately without waiting for |
| the response. *Note File Status Flags::, for information about |
| nonblocking mode. |
| |
| The normal return value from `connect' is `0'. If an error |
| occurs, `connect' returns `-1'. The following `errno' error |
| conditions are defined for this function: |
| |
| `EBADF' |
| The socket SOCKET is not a valid file descriptor. |
| |
| `ENOTSOCK' |
| File descriptor SOCKET is not a socket. |
| |
| `EADDRNOTAVAIL' |
| The specified address is not available on the remote machine. |
| |
| `EAFNOSUPPORT' |
| The namespace of the ADDR is not supported by this socket. |
| |
| `EISCONN' |
| The socket SOCKET is already connected. |
| |
| `ETIMEDOUT' |
| The attempt to establish the connection timed out. |
| |
| `ECONNREFUSED' |
| The server has actively refused to establish the connection. |
| |
| `ENETUNREACH' |
| The network of the given ADDR isn't reachable from this host. |
| |
| `EADDRINUSE' |
| The socket address of the given ADDR is already in use. |
| |
| `EINPROGRESS' |
| The socket SOCKET is non-blocking and the connection could |
| not be established immediately. You can determine when the |
| connection is completely established with `select'; *note |
| Waiting for I/O::. Another `connect' call on the same |
| socket, before the connection is completely established, will |
| fail with `EALREADY'. |
| |
| `EALREADY' |
| The socket SOCKET is non-blocking and already has a pending |
| connection in progress (see `EINPROGRESS' above). |
| |
| This function is defined as a cancellation point in multi-threaded |
| programs, so one has to be prepared for this and make sure that |
| allocated resources (like memory, file descriptors, semaphores or |
| whatever) are freed even if the thread is canceled. |
| |
| |
| File: libc.info, Node: Listening, Next: Accepting Connections, Prev: Connecting, Up: Connections |
| |
| 16.9.2 Listening for Connections |
| -------------------------------- |
| |
| Now let us consider what the server process must do to accept |
| connections on a socket. First it must use the `listen' function to |
| enable connection requests on the socket, and then accept each incoming |
| connection with a call to `accept' (*note Accepting Connections::). |
| Once connection requests are enabled on a server socket, the `select' |
| function reports when the socket has a connection ready to be accepted |
| (*note Waiting for I/O::). |
| |
| The `listen' function is not allowed for sockets using |
| connectionless communication styles. |
| |
| You can write a network server that does not even start running |
| until a connection to it is requested. *Note Inetd Servers::. |
| |
| In the Internet namespace, there are no special protection mechanisms |
| for controlling access to a port; any process on any machine can make a |
| connection to your server. If you want to restrict access to your |
| server, make it examine the addresses associated with connection |
| requests or implement some other handshaking or identification protocol. |
| |
| In the local namespace, the ordinary file protection bits control |
| who has access to connect to the socket. |
| |
| -- Function: int listen (int SOCKET, int N) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety |
| Concepts::. |
| |
| The `listen' function enables the socket SOCKET to accept |
| connections, thus making it a server socket. |
| |
| The argument N specifies the length of the queue for pending |
| connections. When the queue fills, new clients attempting to |
| connect fail with `ECONNREFUSED' until the server calls `accept' to |
| accept a connection from the queue. |
| |
| The `listen' function returns `0' on success and `-1' on failure. |
| The following `errno' error conditions are defined for this |
| function: |
| |
| `EBADF' |
| The argument SOCKET is not a valid file descriptor. |
| |
| `ENOTSOCK' |
| The argument SOCKET is not a socket. |
| |
| `EOPNOTSUPP' |
| The socket SOCKET does not support this operation. |
| |
| |
| File: libc.info, Node: Accepting Connections, Next: Who is Connected, Prev: Listening, Up: Connections |
| |
| 16.9.3 Accepting Connections |
| ---------------------------- |
| |
| When a server receives a connection request, it can complete the |
| connection by accepting the request. Use the function `accept' to do |
| this. |
| |
| A socket that has been established as a server can accept connection |
| requests from multiple clients. The server's original socket _does not |
| become part of the connection_; instead, `accept' makes a new socket |
| which participates in the connection. `accept' returns the descriptor |
| for this socket. The server's original socket remains available for |
| listening for further connection requests. |
| |
| The number of pending connection requests on a server socket is |
| finite. If connection requests arrive from clients faster than the |
| server can act upon them, the queue can fill up and additional requests |
| are refused with an `ECONNREFUSED' error. You can specify the maximum |
| length of this queue as an argument to the `listen' function, although |
| the system may also impose its own internal limit on the length of this |
| queue. |
| |
| -- Function: int accept (int SOCKET, struct sockaddr *ADDR, socklen_t |
| *LENGTH_PTR) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety |
| Concepts::. |
| |
| This function is used to accept a connection request on the server |
| socket SOCKET. |
| |
| The `accept' function waits if there are no connections pending, |
| unless the socket SOCKET has nonblocking mode set. (You can use |
| `select' to wait for a pending connection, with a nonblocking |
| socket.) *Note File Status Flags::, for information about |
| nonblocking mode. |
| |
| The ADDR and LENGTH-PTR arguments are used to return information |
| about the name of the client socket that initiated the connection. |
| *Note Socket Addresses::, for information about the format of the |
| information. |
| |
| Accepting a connection does not make SOCKET part of the |
| connection. Instead, it creates a new socket which becomes |
| connected. The normal return value of `accept' is the file |
| descriptor for the new socket. |
| |
| After `accept', the original socket SOCKET remains open and |
| unconnected, and continues listening until you close it. You can |
| accept further connections with SOCKET by calling `accept' again. |
| |
| If an error occurs, `accept' returns `-1'. The following `errno' |
| error conditions are defined for this function: |
| |
| `EBADF' |
| The SOCKET argument is not a valid file descriptor. |
| |
| `ENOTSOCK' |
| The descriptor SOCKET argument is not a socket. |
| |
| `EOPNOTSUPP' |
| The descriptor SOCKET does not support this operation. |
| |
| `EWOULDBLOCK' |
| SOCKET has nonblocking mode set, and there are no pending |
| connections immediately available. |
| |
| This function is defined as a cancellation point in multi-threaded |
| programs, so one has to be prepared for this and make sure that |
| allocated resources (like memory, file descriptors, semaphores or |
| whatever) are freed even if the thread is canceled. |
| |
| The `accept' function is not allowed for sockets using |
| connectionless communication styles. |
| |
| |
| File: libc.info, Node: Who is Connected, Next: Transferring Data, Prev: Accepting Connections, Up: Connections |
| |
| 16.9.4 Who is Connected to Me? |
| ------------------------------ |
| |
| -- Function: int getpeername (int SOCKET, struct sockaddr *ADDR, |
| socklen_t *LENGTH-PTR) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `getpeername' function returns the address of the socket that |
| SOCKET is connected to; it stores the address in the memory space |
| specified by ADDR and LENGTH-PTR. It stores the length of the |
| address in `*LENGTH-PTR'. |
| |
| *Note Socket Addresses::, for information about the format of the |
| address. In some operating systems, `getpeername' works only for |
| sockets in the Internet domain. |
| |
| The return value is `0' on success and `-1' on error. The |
| following `errno' error conditions are defined for this function: |
| |
| `EBADF' |
| The argument SOCKET is not a valid file descriptor. |
| |
| `ENOTSOCK' |
| The descriptor SOCKET is not a socket. |
| |
| `ENOTCONN' |
| The socket SOCKET is not connected. |
| |
| `ENOBUFS' |
| There are not enough internal buffers available. |
| |
| |
| File: libc.info, Node: Transferring Data, Next: Byte Stream Example, Prev: Who is Connected, Up: Connections |
| |
| 16.9.5 Transferring Data |
| ------------------------ |
| |
| Once a socket has been connected to a peer, you can use the ordinary |
| `read' and `write' operations (*note I/O Primitives::) to transfer |
| data. A socket is a two-way communications channel, so read and write |
| operations can be performed at either end. |
| |
| There are also some I/O modes that are specific to socket operations. |
| In order to specify these modes, you must use the `recv' and `send' |
| functions instead of the more generic `read' and `write' functions. |
| The `recv' and `send' functions take an additional argument which you |
| can use to specify various flags to control special I/O modes. For |
| example, you can specify the `MSG_OOB' flag to read or write |
| out-of-band data, the `MSG_PEEK' flag to peek at input, or the |
| `MSG_DONTROUTE' flag to control inclusion of routing information on |
| output. |
| |
| * Menu: |
| |
| * Sending Data:: Sending data with `send'. |
| * Receiving Data:: Reading data with `recv'. |
| * Socket Data Options:: Using `send' and `recv'. |
| |
| |
| File: libc.info, Node: Sending Data, Next: Receiving Data, Up: Transferring Data |
| |
| 16.9.5.1 Sending Data |
| ..................... |
| |
| The `send' function is declared in the header file `sys/socket.h'. If |
| your FLAGS argument is zero, you can just as well use `write' instead |
| of `send'; see *note I/O Primitives::. If the socket was connected but |
| the connection has broken, you get a `SIGPIPE' signal for any use of |
| `send' or `write' (*note Miscellaneous Signals::). |
| |
| -- Function: ssize_t send (int SOCKET, const void *BUFFER, size_t |
| SIZE, int FLAGS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `send' function is like `write', but with the additional flags |
| FLAGS. The possible values of FLAGS are described in *note Socket |
| Data Options::. |
| |
| This function returns the number of bytes transmitted, or `-1' on |
| failure. If the socket is nonblocking, then `send' (like `write') |
| can return after sending just part of the data. *Note File Status |
| Flags::, for information about nonblocking mode. |
| |
| Note, however, that a successful return value merely indicates that |
| the message has been sent without error, not necessarily that it |
| has been received without error. |
| |
| The following `errno' error conditions are defined for this |
| function: |
| |
| `EBADF' |
| The SOCKET argument is not a valid file descriptor. |
| |
| `EINTR' |
| The operation was interrupted by a signal before any data was |
| sent. *Note Interrupted Primitives::. |
| |
| `ENOTSOCK' |
| The descriptor SOCKET is not a socket. |
| |
| `EMSGSIZE' |
| The socket type requires that the message be sent atomically, |
| but the message is too large for this to be possible. |
| |
| `EWOULDBLOCK' |
| Nonblocking mode has been set on the socket, and the write |
| operation would block. (Normally `send' blocks until the |
| operation can be completed.) |
| |
| `ENOBUFS' |
| There is not enough internal buffer space available. |
| |
| `ENOTCONN' |
| You never connected this socket. |
| |
| `EPIPE' |
| This socket was connected but the connection is now broken. |
| In this case, `send' generates a `SIGPIPE' signal first; if |
| that signal is ignored or blocked, or if its handler returns, |
| then `send' fails with `EPIPE'. |
| |
| This function is defined as a cancellation point in multi-threaded |
| programs, so one has to be prepared for this and make sure that |
| allocated resources (like memory, file descriptors, semaphores or |
| whatever) are freed even if the thread is canceled. |
| |
| |
| File: libc.info, Node: Receiving Data, Next: Socket Data Options, Prev: Sending Data, Up: Transferring Data |
| |
| 16.9.5.2 Receiving Data |
| ....................... |
| |
| The `recv' function is declared in the header file `sys/socket.h'. If |
| your FLAGS argument is zero, you can just as well use `read' instead of |
| `recv'; see *note I/O Primitives::. |
| |
| -- Function: ssize_t recv (int SOCKET, void *BUFFER, size_t SIZE, int |
| FLAGS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `recv' function is like `read', but with the additional flags |
| FLAGS. The possible values of FLAGS are described in *note Socket |
| Data Options::. |
| |
| If nonblocking mode is set for SOCKET, and no data are available to |
| be read, `recv' fails immediately rather than waiting. *Note File |
| Status Flags::, for information about nonblocking mode. |
| |
| This function returns the number of bytes received, or `-1' on |
| failure. The following `errno' error conditions are defined for |
| this function: |
| |
| `EBADF' |
| The SOCKET argument is not a valid file descriptor. |
| |
| `ENOTSOCK' |
| The descriptor SOCKET is not a socket. |
| |
| `EWOULDBLOCK' |
| Nonblocking mode has been set on the socket, and the read |
| operation would block. (Normally, `recv' blocks until there |
| is input available to be read.) |
| |
| `EINTR' |
| The operation was interrupted by a signal before any data was |
| read. *Note Interrupted Primitives::. |
| |
| `ENOTCONN' |
| You never connected this socket. |
| |
| This function is defined as a cancellation point in multi-threaded |
| programs, so one has to be prepared for this and make sure that |
| allocated resources (like memory, file descriptors, semaphores or |
| whatever) are freed even if the thread is canceled. |
| |
| |
| File: libc.info, Node: Socket Data Options, Prev: Receiving Data, Up: Transferring Data |
| |
| 16.9.5.3 Socket Data Options |
| ............................ |
| |
| The FLAGS argument to `send' and `recv' is a bit mask. You can |
| bitwise-OR the values of the following macros together to obtain a |
| value for this argument. All are defined in the header file |
| `sys/socket.h'. |
| |
| -- Macro: int MSG_OOB |
| Send or receive out-of-band data. *Note Out-of-Band Data::. |
| |
| -- Macro: int MSG_PEEK |
| Look at the data but don't remove it from the input queue. This is |
| only meaningful with input functions such as `recv', not with |
| `send'. |
| |
| -- Macro: int MSG_DONTROUTE |
| Don't include routing information in the message. This is only |
| meaningful with output operations, and is usually only of interest |
| for diagnostic or routing programs. We don't try to explain it |
| here. |
| |
| |
| File: libc.info, Node: Byte Stream Example, Next: Server Example, Prev: Transferring Data, Up: Connections |
| |
| 16.9.6 Byte Stream Socket Example |
| --------------------------------- |
| |
| Here is an example client program that makes a connection for a byte |
| stream socket in the Internet namespace. It doesn't do anything |
| particularly interesting once it has connected to the server; it just |
| sends a text string to the server and exits. |
| |
| This program uses `init_sockaddr' to set up the socket address; see |
| *note Inet Example::. |
| |
| |
| #include <stdio.h> |
| #include <errno.h> |
| #include <stdlib.h> |
| #include <unistd.h> |
| #include <sys/types.h> |
| #include <sys/socket.h> |
| #include <netinet/in.h> |
| #include <netdb.h> |
| |
| #define PORT 5555 |
| #define MESSAGE "Yow!!! Are we having fun yet?!?" |
| #define SERVERHOST "www.gnu.org" |
| |
| void |
| write_to_server (int filedes) |
| { |
| int nbytes; |
| |
| nbytes = write (filedes, MESSAGE, strlen (MESSAGE) + 1); |
| if (nbytes < 0) |
| { |
| perror ("write"); |
| exit (EXIT_FAILURE); |
| } |
| } |
| |
| |
| int |
| main (void) |
| { |
| extern void init_sockaddr (struct sockaddr_in *name, |
| const char *hostname, |
| uint16_t port); |
| int sock; |
| struct sockaddr_in servername; |
| |
| /* Create the socket. */ |
| sock = socket (PF_INET, SOCK_STREAM, 0); |
| if (sock < 0) |
| { |
| perror ("socket (client)"); |
| exit (EXIT_FAILURE); |
| } |
| |
| /* Connect to the server. */ |
| init_sockaddr (&servername, SERVERHOST, PORT); |
| if (0 > connect (sock, |
| (struct sockaddr *) &servername, |
| sizeof (servername))) |
| { |
| perror ("connect (client)"); |
| exit (EXIT_FAILURE); |
| } |
| |
| /* Send data to the server. */ |
| write_to_server (sock); |
| close (sock); |
| exit (EXIT_SUCCESS); |
| } |
| |
| |
| File: libc.info, Node: Server Example, Next: Out-of-Band Data, Prev: Byte Stream Example, Up: Connections |
| |
| 16.9.7 Byte Stream Connection Server Example |
| -------------------------------------------- |
| |
| The server end is much more complicated. Since we want to allow |
| multiple clients to be connected to the server at the same time, it |
| would be incorrect to wait for input from a single client by simply |
| calling `read' or `recv'. Instead, the right thing to do is to use |
| `select' (*note Waiting for I/O::) to wait for input on all of the open |
| sockets. This also allows the server to deal with additional |
| connection requests. |
| |
| This particular server doesn't do anything interesting once it has |
| gotten a message from a client. It does close the socket for that |
| client when it detects an end-of-file condition (resulting from the |
| client shutting down its end of the connection). |
| |
| This program uses `make_socket' to set up the socket address; see |
| *note Inet Example::. |
| |
| |
| #include <stdio.h> |
| #include <errno.h> |
| #include <stdlib.h> |
| #include <unistd.h> |
| #include <sys/types.h> |
| #include <sys/socket.h> |
| #include <netinet/in.h> |
| #include <netdb.h> |
| |
| #define PORT 5555 |
| #define MAXMSG 512 |
| |
| int |
| read_from_client (int filedes) |
| { |
| char buffer[MAXMSG]; |
| int nbytes; |
| |
| nbytes = read (filedes, buffer, MAXMSG); |
| if (nbytes < 0) |
| { |
| /* Read error. */ |
| perror ("read"); |
| exit (EXIT_FAILURE); |
| } |
| else if (nbytes == 0) |
| /* End-of-file. */ |
| return -1; |
| else |
| { |
| /* Data read. */ |
| fprintf (stderr, "Server: got message: `%s'\n", buffer); |
| return 0; |
| } |
| } |
| |
| int |
| main (void) |
| { |
| extern int make_socket (uint16_t port); |
| int sock; |
| fd_set active_fd_set, read_fd_set; |
| int i; |
| struct sockaddr_in clientname; |
| size_t size; |
| |
| /* Create the socket and set it up to accept connections. */ |
| sock = make_socket (PORT); |
| if (listen (sock, 1) < 0) |
| { |
| perror ("listen"); |
| exit (EXIT_FAILURE); |
| } |
| |
| /* Initialize the set of active sockets. */ |
| FD_ZERO (&active_fd_set); |
| FD_SET (sock, &active_fd_set); |
| |
| while (1) |
| { |
| /* Block until input arrives on one or more active sockets. */ |
| read_fd_set = active_fd_set; |
| if (select (FD_SETSIZE, &read_fd_set, NULL, NULL, NULL) < 0) |
| { |
| perror ("select"); |
| exit (EXIT_FAILURE); |
| } |
| |
| /* Service all the sockets with input pending. */ |
| for (i = 0; i < FD_SETSIZE; ++i) |
| if (FD_ISSET (i, &read_fd_set)) |
| { |
| if (i == sock) |
| { |
| /* Connection request on original socket. */ |
| int new; |
| size = sizeof (clientname); |
| new = accept (sock, |
| (struct sockaddr *) &clientname, |
| &size); |
| if (new < 0) |
| { |
| perror ("accept"); |
| exit (EXIT_FAILURE); |
| } |
| fprintf (stderr, |
| "Server: connect from host %s, port %hd.\n", |
| inet_ntoa (clientname.sin_addr), |
| ntohs (clientname.sin_port)); |
| FD_SET (new, &active_fd_set); |
| } |
| else |
| { |
| /* Data arriving on an already-connected socket. */ |
| if (read_from_client (i) < 0) |
| { |
| close (i); |
| FD_CLR (i, &active_fd_set); |
| } |
| } |
| } |
| } |
| } |
| |
| |
| File: libc.info, Node: Out-of-Band Data, Prev: Server Example, Up: Connections |
| |
| 16.9.8 Out-of-Band Data |
| ----------------------- |
| |
| Streams with connections permit "out-of-band" data that is delivered |
| with higher priority than ordinary data. Typically the reason for |
| sending out-of-band data is to send notice of an exceptional condition. |
| To send out-of-band data use `send', specifying the flag `MSG_OOB' |
| (*note Sending Data::). |
| |
| Out-of-band data are received with higher priority because the |
| receiving process need not read it in sequence; to read the next |
| available out-of-band data, use `recv' with the `MSG_OOB' flag (*note |
| Receiving Data::). Ordinary read operations do not read out-of-band |
| data; they read only ordinary data. |
| |
| When a socket finds that out-of-band data are on their way, it sends |
| a `SIGURG' signal to the owner process or process group of the socket. |
| You can specify the owner using the `F_SETOWN' command to the `fcntl' |
| function; see *note Interrupt Input::. You must also establish a |
| handler for this signal, as described in *note Signal Handling::, in |
| order to take appropriate action such as reading the out-of-band data. |
| |
| Alternatively, you can test for pending out-of-band data, or wait |
| until there is out-of-band data, using the `select' function; it can |
| wait for an exceptional condition on the socket. *Note Waiting for |
| I/O::, for more information about `select'. |
| |
| Notification of out-of-band data (whether with `SIGURG' or with |
| `select') indicates that out-of-band data are on the way; the data may |
| not actually arrive until later. If you try to read the out-of-band |
| data before it arrives, `recv' fails with an `EWOULDBLOCK' error. |
| |
| Sending out-of-band data automatically places a "mark" in the stream |
| of ordinary data, showing where in the sequence the out-of-band data |
| "would have been". This is useful when the meaning of out-of-band data |
| is "cancel everything sent so far". Here is how you can test, in the |
| receiving process, whether any ordinary data was sent before the mark: |
| |
| success = ioctl (socket, SIOCATMARK, &atmark); |
| |
| The `integer' variable ATMARK is set to a nonzero value if the |
| socket's read pointer has reached the "mark". |
| |
| Here's a function to discard any ordinary data preceding the |
| out-of-band mark: |
| |
| int |
| discard_until_mark (int socket) |
| { |
| while (1) |
| { |
| /* This is not an arbitrary limit; any size will do. */ |
| char buffer[1024]; |
| int atmark, success; |
| |
| /* If we have reached the mark, return. */ |
| success = ioctl (socket, SIOCATMARK, &atmark); |
| if (success < 0) |
| perror ("ioctl"); |
| if (result) |
| return; |
| |
| /* Otherwise, read a bunch of ordinary data and discard it. |
| This is guaranteed not to read past the mark |
| if it starts before the mark. */ |
| success = read (socket, buffer, sizeof buffer); |
| if (success < 0) |
| perror ("read"); |
| } |
| } |
| |
| If you don't want to discard the ordinary data preceding the mark, |
| you may need to read some of it anyway, to make room in internal system |
| buffers for the out-of-band data. If you try to read out-of-band data |
| and get an `EWOULDBLOCK' error, try reading some ordinary data (saving |
| it so that you can use it when you want it) and see if that makes room. |
| Here is an example: |
| |
| struct buffer |
| { |
| char *buf; |
| int size; |
| struct buffer *next; |
| }; |
| |
| /* Read the out-of-band data from SOCKET and return it |
| as a `struct buffer', which records the address of the data |
| and its size. |
| |
| It may be necessary to read some ordinary data |
| in order to make room for the out-of-band data. |
| If so, the ordinary data are saved as a chain of buffers |
| found in the `next' field of the value. */ |
| |
| struct buffer * |
| read_oob (int socket) |
| { |
| struct buffer *tail = 0; |
| struct buffer *list = 0; |
| |
| while (1) |
| { |
| /* This is an arbitrary limit. |
| Does anyone know how to do this without a limit? */ |
| #define BUF_SZ 1024 |
| char *buf = (char *) xmalloc (BUF_SZ); |
| int success; |
| int atmark; |
| |
| /* Try again to read the out-of-band data. */ |
| success = recv (socket, buf, BUF_SZ, MSG_OOB); |
| if (success >= 0) |
| { |
| /* We got it, so return it. */ |
| struct buffer *link |
| = (struct buffer *) xmalloc (sizeof (struct buffer)); |
| link->buf = buf; |
| link->size = success; |
| link->next = list; |
| return link; |
| } |
| |
| /* If we fail, see if we are at the mark. */ |
| success = ioctl (socket, SIOCATMARK, &atmark); |
| if (success < 0) |
| perror ("ioctl"); |
| if (atmark) |
| { |
| /* At the mark; skipping past more ordinary data cannot help. |
| So just wait a while. */ |
| sleep (1); |
| continue; |
| } |
| |
| /* Otherwise, read a bunch of ordinary data and save it. |
| This is guaranteed not to read past the mark |
| if it starts before the mark. */ |
| success = read (socket, buf, BUF_SZ); |
| if (success < 0) |
| perror ("read"); |
| |
| /* Save this data in the buffer list. */ |
| { |
| struct buffer *link |
| = (struct buffer *) xmalloc (sizeof (struct buffer)); |
| link->buf = buf; |
| link->size = success; |
| |
| /* Add the new link to the end of the list. */ |
| if (tail) |
| tail->next = link; |
| else |
| list = link; |
| tail = link; |
| } |
| } |
| } |
| |
| |
| File: libc.info, Node: Datagrams, Next: Inetd, Prev: Connections, Up: Sockets |
| |
| 16.10 Datagram Socket Operations |
| ================================ |
| |
| This section describes how to use communication styles that don't use |
| connections (styles `SOCK_DGRAM' and `SOCK_RDM'). Using these styles, |
| you group data into packets and each packet is an independent |
| communication. You specify the destination for each packet |
| individually. |
| |
| Datagram packets are like letters: you send each one independently |
| with its own destination address, and they may arrive in the wrong |
| order or not at all. |
| |
| The `listen' and `accept' functions are not allowed for sockets |
| using connectionless communication styles. |
| |
| * Menu: |
| |
| * 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. |
| |
| |
| File: libc.info, Node: Sending Datagrams, Next: Receiving Datagrams, Up: Datagrams |
| |
| 16.10.1 Sending Datagrams |
| ------------------------- |
| |
| The normal way of sending data on a datagram socket is by using the |
| `sendto' function, declared in `sys/socket.h'. |
| |
| You can call `connect' on a datagram socket, but this only specifies |
| a default destination for further data transmission on the socket. |
| When a socket has a default destination you can use `send' (*note |
| Sending Data::) or even `write' (*note I/O Primitives::) to send a |
| packet there. You can cancel the default destination by calling |
| `connect' using an address format of `AF_UNSPEC' in the ADDR argument. |
| *Note Connecting::, for more information about the `connect' function. |
| |
| -- Function: ssize_t sendto (int SOCKET, const void *BUFFER, size_t |
| SIZE, int FLAGS, struct sockaddr *ADDR, socklen_t LENGTH) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `sendto' function transmits the data in the BUFFER through the |
| socket SOCKET to the destination address specified by the ADDR and |
| LENGTH arguments. The SIZE argument specifies the number of bytes |
| to be transmitted. |
| |
| The FLAGS are interpreted the same way as for `send'; see *note |
| Socket Data Options::. |
| |
| The return value and error conditions are also the same as for |
| `send', but you cannot rely on the system to detect errors and |
| report them; the most common error is that the packet is lost or |
| there is no-one at the specified address to receive it, and the |
| operating system on your machine usually does not know this. |
| |
| It is also possible for one call to `sendto' to report an error |
| owing to a problem related to a previous call. |
| |
| This function is defined as a cancellation point in multi-threaded |
| programs, so one has to be prepared for this and make sure that |
| allocated resources (like memory, file descriptors, semaphores or |
| whatever) are freed even if the thread is canceled. |
| |
| |
| File: libc.info, Node: Receiving Datagrams, Next: Datagram Example, Prev: Sending Datagrams, Up: Datagrams |
| |
| 16.10.2 Receiving Datagrams |
| --------------------------- |
| |
| The `recvfrom' function reads a packet from a datagram socket and also |
| tells you where it was sent from. This function is declared in |
| `sys/socket.h'. |
| |
| -- Function: ssize_t recvfrom (int SOCKET, void *BUFFER, size_t SIZE, |
| int FLAGS, struct sockaddr *ADDR, socklen_t *LENGTH-PTR) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `recvfrom' function reads one packet from the socket SOCKET |
| into the buffer BUFFER. The SIZE argument specifies the maximum |
| number of bytes to be read. |
| |
| If the packet is longer than SIZE bytes, then you get the first |
| SIZE bytes of the packet and the rest of the packet is lost. |
| There's no way to read the rest of the packet. Thus, when you use |
| a packet protocol, you must always know how long a packet to |
| expect. |
| |
| The ADDR and LENGTH-PTR arguments are used to return the address |
| where the packet came from. *Note Socket Addresses::. For a |
| socket in the local domain the address information won't be |
| meaningful, since you can't read the address of such a socket |
| (*note Local Namespace::). You can specify a null pointer as the |
| ADDR argument if you are not interested in this information. |
| |
| The FLAGS are interpreted the same way as for `recv' (*note Socket |
| Data Options::). The return value and error conditions are also |
| the same as for `recv'. |
| |
| This function is defined as a cancellation point in multi-threaded |
| programs, so one has to be prepared for this and make sure that |
| allocated resources (like memory, file descriptors, semaphores or |
| whatever) are freed even if the thread is canceled. |
| |
| You can use plain `recv' (*note Receiving Data::) instead of |
| `recvfrom' if you don't need to find out who sent the packet (either |
| because you know where it should come from or because you treat all |
| possible senders alike). Even `read' can be used if you don't want to |
| specify FLAGS (*note I/O Primitives::). |
| |
| |
| File: libc.info, Node: Datagram Example, Next: Example Receiver, Prev: Receiving Datagrams, Up: Datagrams |
| |
| 16.10.3 Datagram Socket Example |
| ------------------------------- |
| |
| Here is a set of example programs that send messages over a datagram |
| stream in the local namespace. Both the client and server programs use |
| the `make_named_socket' function that was presented in *note Local |
| Socket Example::, to create and name their sockets. |
| |
| First, here is the server program. It sits in a loop waiting for |
| messages to arrive, bouncing each message back to the sender. |
| Obviously this isn't a particularly useful program, but it does show |
| the general ideas involved. |
| |
| |
| #include <stdio.h> |
| #include <errno.h> |
| #include <stdlib.h> |
| #include <sys/socket.h> |
| #include <sys/un.h> |
| |
| #define SERVER "/tmp/serversocket" |
| #define MAXMSG 512 |
| |
| int |
| main (void) |
| { |
| int sock; |
| char message[MAXMSG]; |
| struct sockaddr_un name; |
| size_t size; |
| int nbytes; |
| |
| /* Remove the filename first, it's ok if the call fails */ |
| unlink (SERVER); |
| |
| /* Make the socket, then loop endlessly. */ |
| sock = make_named_socket (SERVER); |
| while (1) |
| { |
| /* Wait for a datagram. */ |
| size = sizeof (name); |
| nbytes = recvfrom (sock, message, MAXMSG, 0, |
| (struct sockaddr *) & name, &size); |
| if (nbytes < 0) |
| { |
| perror ("recfrom (server)"); |
| exit (EXIT_FAILURE); |
| } |
| |
| /* Give a diagnostic message. */ |
| fprintf (stderr, "Server: got message: %s\n", message); |
| |
| /* Bounce the message back to the sender. */ |
| nbytes = sendto (sock, message, nbytes, 0, |
| (struct sockaddr *) & name, size); |
| if (nbytes < 0) |
| { |
| perror ("sendto (server)"); |
| exit (EXIT_FAILURE); |
| } |
| } |
| } |
| |
| |
| File: libc.info, Node: Example Receiver, Prev: Datagram Example, Up: Datagrams |
| |
| 16.10.4 Example of Reading Datagrams |
| ------------------------------------ |
| |
| Here is the client program corresponding to the server above. |
| |
| It sends a datagram to the server and then waits for a reply. Notice |
| that the socket for the client (as well as for the server) in this |
| example has to be given a name. This is so that the server can direct |
| a message back to the client. Since the socket has no associated |
| connection state, the only way the server can do this is by referencing |
| the name of the client. |
| |
| |
| #include <stdio.h> |
| #include <errno.h> |
| #include <unistd.h> |
| #include <stdlib.h> |
| #include <sys/socket.h> |
| #include <sys/un.h> |
| |
| #define SERVER "/tmp/serversocket" |
| #define CLIENT "/tmp/mysocket" |
| #define MAXMSG 512 |
| #define MESSAGE "Yow!!! Are we having fun yet?!?" |
| |
| int |
| main (void) |
| { |
| extern int make_named_socket (const char *name); |
| int sock; |
| char message[MAXMSG]; |
| struct sockaddr_un name; |
| size_t size; |
| int nbytes; |
| |
| /* Make the socket. */ |
| sock = make_named_socket (CLIENT); |
| |
| /* Initialize the server socket address. */ |
| name.sun_family = AF_LOCAL; |
| strcpy (name.sun_path, SERVER); |
| size = strlen (name.sun_path) + sizeof (name.sun_family); |
| |
| /* Send the datagram. */ |
| nbytes = sendto (sock, MESSAGE, strlen (MESSAGE) + 1, 0, |
| (struct sockaddr *) & name, size); |
| if (nbytes < 0) |
| { |
| perror ("sendto (client)"); |
| exit (EXIT_FAILURE); |
| } |
| |
| /* Wait for a reply. */ |
| nbytes = recvfrom (sock, message, MAXMSG, 0, NULL, 0); |
| if (nbytes < 0) |
| { |
| perror ("recfrom (client)"); |
| exit (EXIT_FAILURE); |
| } |
| |
| /* Print a diagnostic message. */ |
| fprintf (stderr, "Client: got message: %s\n", message); |
| |
| /* Clean up. */ |
| remove (CLIENT); |
| close (sock); |
| } |
| |
| Keep in mind that datagram socket communications are unreliable. In |
| this example, the client program waits indefinitely if the message |
| never reaches the server or if the server's response never comes back. |
| It's up to the user running the program to kill and restart it if |
| desired. A more automatic solution could be to use `select' (*note |
| Waiting for I/O::) to establish a timeout period for the reply, and in |
| case of timeout either re-send the message or shut down the socket and |
| exit. |
| |
| |
| File: libc.info, Node: Inetd, Next: Socket Options, Prev: Datagrams, Up: Sockets |
| |
| 16.11 The `inetd' Daemon |
| ======================== |
| |
| We've explained above how to write a server program that does its own |
| listening. Such a server must already be running in order for anyone |
| to connect to it. |
| |
| Another way to provide a service on an Internet port is to let the |
| daemon program `inetd' do the listening. `inetd' is a program that |
| runs all the time and waits (using `select') for messages on a |
| specified set of ports. When it receives a message, it accepts the |
| connection (if the socket style calls for connections) and then forks a |
| child process to run the corresponding server program. You specify the |
| ports and their programs in the file `/etc/inetd.conf'. |
| |
| * Menu: |
| |
| * Inetd Servers:: |
| * Configuring Inetd:: |
| |
| |
| File: libc.info, Node: Inetd Servers, Next: Configuring Inetd, Up: Inetd |
| |
| 16.11.1 `inetd' Servers |
| ----------------------- |
| |
| Writing a server program to be run by `inetd' is very simple. Each time |
| someone requests a connection to the appropriate port, a new server |
| process starts. The connection already exists at this time; the socket |
| is available as the standard input descriptor and as the standard |
| output descriptor (descriptors 0 and 1) in the server process. Thus |
| the server program can begin reading and writing data right away. |
| Often the program needs only the ordinary I/O facilities; in fact, a |
| general-purpose filter program that knows nothing about sockets can |
| work as a byte stream server run by `inetd'. |
| |
| You can also use `inetd' for servers that use connectionless |
| communication styles. For these servers, `inetd' does not try to accept |
| a connection since no connection is possible. It just starts the |
| server program, which can read the incoming datagram packet from |
| descriptor 0. The server program can handle one request and then exit, |
| or you can choose to write it to keep reading more requests until no |
| more arrive, and then exit. You must specify which of these two |
| techniques the server uses when you configure `inetd'. |
| |
| |
| File: libc.info, Node: Configuring Inetd, Prev: Inetd Servers, Up: Inetd |
| |
| 16.11.2 Configuring `inetd' |
| --------------------------- |
| |
| The file `/etc/inetd.conf' tells `inetd' which ports to listen to and |
| what server programs to run for them. Normally each entry in the file |
| is one line, but you can split it onto multiple lines provided all but |
| the first line of the entry start with whitespace. Lines that start |
| with `#' are comments. |
| |
| Here are two standard entries in `/etc/inetd.conf': |
| |
| ftp stream tcp nowait root /libexec/ftpd ftpd |
| talk dgram udp wait root /libexec/talkd talkd |
| |
| An entry has this format: |
| |
| SERVICE STYLE PROTOCOL WAIT USERNAME PROGRAM ARGUMENTS |
| |
| The SERVICE field says which service this program provides. It |
| should be the name of a service defined in `/etc/services'. `inetd' |
| uses SERVICE to decide which port to listen on for this entry. |
| |
| The fields STYLE and PROTOCOL specify the communication style and |
| the protocol to use for the listening socket. The style should be the |
| name of a communication style, converted to lower case and with `SOCK_' |
| deleted--for example, `stream' or `dgram'. PROTOCOL should be one of |
| the protocols listed in `/etc/protocols'. The typical protocol names |
| are `tcp' for byte stream connections and `udp' for unreliable |
| datagrams. |
| |
| The WAIT field should be either `wait' or `nowait'. Use `wait' if |
| STYLE is a connectionless style and the server, once started, handles |
| multiple requests as they come in. Use `nowait' if `inetd' should |
| start a new process for each message or request that comes in. If |
| STYLE uses connections, then WAIT *must* be `nowait'. |
| |
| USER is the user name that the server should run as. `inetd' runs |
| as root, so it can set the user ID of its children arbitrarily. It's |
| best to avoid using `root' for USER if you can; but some servers, such |
| as Telnet and FTP, read a username and passphrase themselves. These |
| servers need to be root initially so they can log in as commanded by |
| the data coming over the network. |
| |
| PROGRAM together with ARGUMENTS specifies the command to run to |
| start the server. PROGRAM should be an absolute file name specifying |
| the executable file to run. ARGUMENTS consists of any number of |
| whitespace-separated words, which become the command-line arguments of |
| PROGRAM. The first word in ARGUMENTS is argument zero, which should by |
| convention be the program name itself (sans directories). |
| |
| If you edit `/etc/inetd.conf', you can tell `inetd' to reread the |
| file and obey its new contents by sending the `inetd' process the |
| `SIGHUP' signal. You'll have to use `ps' to determine the process ID |
| of the `inetd' process as it is not fixed. |
| |
| |
| File: libc.info, Node: Socket Options, Next: Networks Database, Prev: Inetd, Up: Sockets |
| |
| 16.12 Socket Options |
| ==================== |
| |
| This section describes how to read or set various options that modify |
| the behavior of sockets and their underlying communications protocols. |
| |
| When you are manipulating a socket option, you must specify which |
| "level" the option pertains to. This describes whether the option |
| applies to the socket interface, or to a lower-level communications |
| protocol interface. |
| |
| * Menu: |
| |
| * Socket Option Functions:: The basic functions for setting and getting |
| socket options. |
| * Socket-Level Options:: Details of the options at the socket level. |
| |
| |
| File: libc.info, Node: Socket Option Functions, Next: Socket-Level Options, Up: Socket Options |
| |
| 16.12.1 Socket Option Functions |
| ------------------------------- |
| |
| Here are the functions for examining and modifying socket options. |
| They are declared in `sys/socket.h'. |
| |
| -- Function: int getsockopt (int SOCKET, int LEVEL, int OPTNAME, void |
| *OPTVAL, socklen_t *OPTLEN-PTR) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `getsockopt' function gets information about the value of |
| option OPTNAME at level LEVEL for socket SOCKET. |
| |
| The option value is stored in the buffer that OPTVAL points to. |
| Before the call, you should supply in `*OPTLEN-PTR' the size of |
| this buffer; on return, it contains the number of bytes of |
| information actually stored in the buffer. |
| |
| Most options interpret the OPTVAL buffer as a single `int' value. |
| |
| The actual return value of `getsockopt' is `0' on success and `-1' |
| on failure. The following `errno' error conditions are defined: |
| |
| `EBADF' |
| The SOCKET argument is not a valid file descriptor. |
| |
| `ENOTSOCK' |
| The descriptor SOCKET is not a socket. |
| |
| `ENOPROTOOPT' |
| The OPTNAME doesn't make sense for the given LEVEL. |
| |
| -- Function: int setsockopt (int SOCKET, int LEVEL, int OPTNAME, const |
| void *OPTVAL, socklen_t OPTLEN) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is used to set the socket option OPTNAME at level |
| LEVEL for socket SOCKET. The value of the option is passed in the |
| buffer OPTVAL of size OPTLEN. |
| |
| The return value and error codes for `setsockopt' are the same as |
| for `getsockopt'. |
| |
| |
| |
| |
| Local Variables: |
| coding: utf-8 |
| End: |
