This is libc.info, produced by makeinfo version 5.2 from libc.texinfo.
|
|
This file documents the GNU C Library.
|
|
This is ‘The GNU C Library Reference Manual’, for version 2.25.
|
|
Copyright © 1993–2017 Free Software Foundation, Inc.
|
|
Permission is granted to copy, distribute and/or modify this document
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
any later version published by the Free Software Foundation; with the
|
Invariant Sections being “Free Software Needs Free Documentation” and
|
“GNU Lesser General Public License”, the Front-Cover texts being “A GNU
|
Manual”, and with the Back-Cover Texts as in (a) below. A copy of the
|
license is included in the section entitled "GNU Free Documentation
|
License".
|
|
(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
|
modify this GNU manual. Buying copies from the FSF supports it in
|
developing GNU and promoting software freedom.”
|
INFO-DIR-SECTION Software libraries
|
START-INFO-DIR-ENTRY
|
* Libc: (libc). C library.
|
END-INFO-DIR-ENTRY
|
|
INFO-DIR-SECTION GNU C library functions and macros
|
START-INFO-DIR-ENTRY
|
* ALTWERASE: (libc)Local Modes.
|
* ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions.
|
* ARG_MAX: (libc)General Limits.
|
* BC_BASE_MAX: (libc)Utility Limits.
|
* BC_DIM_MAX: (libc)Utility Limits.
|
* BC_SCALE_MAX: (libc)Utility Limits.
|
* BC_STRING_MAX: (libc)Utility Limits.
|
* BRKINT: (libc)Input Modes.
|
* BUFSIZ: (libc)Controlling Buffering.
|
* CCTS_OFLOW: (libc)Control Modes.
|
* CHILD_MAX: (libc)General Limits.
|
* CIGNORE: (libc)Control Modes.
|
* CLK_TCK: (libc)Processor Time.
|
* CLOCAL: (libc)Control Modes.
|
* CLOCKS_PER_SEC: (libc)CPU Time.
|
* COLL_WEIGHTS_MAX: (libc)Utility Limits.
|
* CPU_CLR: (libc)CPU Affinity.
|
* CPU_ISSET: (libc)CPU Affinity.
|
* CPU_SET: (libc)CPU Affinity.
|
* CPU_SETSIZE: (libc)CPU Affinity.
|
* CPU_ZERO: (libc)CPU Affinity.
|
* CREAD: (libc)Control Modes.
|
* CRTS_IFLOW: (libc)Control Modes.
|
* CS5: (libc)Control Modes.
|
* CS6: (libc)Control Modes.
|
* CS7: (libc)Control Modes.
|
* CS8: (libc)Control Modes.
|
* CSIZE: (libc)Control Modes.
|
* CSTOPB: (libc)Control Modes.
|
* DES_FAILED: (libc)DES Encryption.
|
* DTTOIF: (libc)Directory Entries.
|
* E2BIG: (libc)Error Codes.
|
* EACCES: (libc)Error Codes.
|
* EADDRINUSE: (libc)Error Codes.
|
* EADDRNOTAVAIL: (libc)Error Codes.
|
* EADV: (libc)Error Codes.
|
* EAFNOSUPPORT: (libc)Error Codes.
|
* EAGAIN: (libc)Error Codes.
|
* EALREADY: (libc)Error Codes.
|
* EAUTH: (libc)Error Codes.
|
* EBACKGROUND: (libc)Error Codes.
|
* EBADE: (libc)Error Codes.
|
* EBADF: (libc)Error Codes.
|
* EBADFD: (libc)Error Codes.
|
* EBADMSG: (libc)Error Codes.
|
* EBADR: (libc)Error Codes.
|
* EBADRPC: (libc)Error Codes.
|
* EBADRQC: (libc)Error Codes.
|
* EBADSLT: (libc)Error Codes.
|
* EBFONT: (libc)Error Codes.
|
* EBUSY: (libc)Error Codes.
|
* ECANCELED: (libc)Error Codes.
|
* ECHILD: (libc)Error Codes.
|
* ECHO: (libc)Local Modes.
|
* ECHOCTL: (libc)Local Modes.
|
* ECHOE: (libc)Local Modes.
|
* ECHOK: (libc)Local Modes.
|
* ECHOKE: (libc)Local Modes.
|
* ECHONL: (libc)Local Modes.
|
* ECHOPRT: (libc)Local Modes.
|
* ECHRNG: (libc)Error Codes.
|
* ECOMM: (libc)Error Codes.
|
* ECONNABORTED: (libc)Error Codes.
|
* ECONNREFUSED: (libc)Error Codes.
|
* ECONNRESET: (libc)Error Codes.
|
* ED: (libc)Error Codes.
|
* EDEADLK: (libc)Error Codes.
|
* EDEADLOCK: (libc)Error Codes.
|
* EDESTADDRREQ: (libc)Error Codes.
|
* EDIED: (libc)Error Codes.
|
* EDOM: (libc)Error Codes.
|
* EDOTDOT: (libc)Error Codes.
|
* EDQUOT: (libc)Error Codes.
|
* EEXIST: (libc)Error Codes.
|
* EFAULT: (libc)Error Codes.
|
* EFBIG: (libc)Error Codes.
|
* EFTYPE: (libc)Error Codes.
|
* EGRATUITOUS: (libc)Error Codes.
|
* EGREGIOUS: (libc)Error Codes.
|
* EHOSTDOWN: (libc)Error Codes.
|
* EHOSTUNREACH: (libc)Error Codes.
|
* EHWPOISON: (libc)Error Codes.
|
* EIDRM: (libc)Error Codes.
|
* EIEIO: (libc)Error Codes.
|
* EILSEQ: (libc)Error Codes.
|
* EINPROGRESS: (libc)Error Codes.
|
* EINTR: (libc)Error Codes.
|
* EINVAL: (libc)Error Codes.
|
* EIO: (libc)Error Codes.
|
* EISCONN: (libc)Error Codes.
|
* EISDIR: (libc)Error Codes.
|
* EISNAM: (libc)Error Codes.
|
* EKEYEXPIRED: (libc)Error Codes.
|
* EKEYREJECTED: (libc)Error Codes.
|
* EKEYREVOKED: (libc)Error Codes.
|
* EL2HLT: (libc)Error Codes.
|
* EL2NSYNC: (libc)Error Codes.
|
* EL3HLT: (libc)Error Codes.
|
* EL3RST: (libc)Error Codes.
|
* ELIBACC: (libc)Error Codes.
|
* ELIBBAD: (libc)Error Codes.
|
* ELIBEXEC: (libc)Error Codes.
|
* ELIBMAX: (libc)Error Codes.
|
* ELIBSCN: (libc)Error Codes.
|
* ELNRNG: (libc)Error Codes.
|
* ELOOP: (libc)Error Codes.
|
* EMEDIUMTYPE: (libc)Error Codes.
|
* EMFILE: (libc)Error Codes.
|
* EMLINK: (libc)Error Codes.
|
* EMSGSIZE: (libc)Error Codes.
|
* EMULTIHOP: (libc)Error Codes.
|
* ENAMETOOLONG: (libc)Error Codes.
|
* ENAVAIL: (libc)Error Codes.
|
* ENEEDAUTH: (libc)Error Codes.
|
* ENETDOWN: (libc)Error Codes.
|
* ENETRESET: (libc)Error Codes.
|
* ENETUNREACH: (libc)Error Codes.
|
* ENFILE: (libc)Error Codes.
|
* ENOANO: (libc)Error Codes.
|
* ENOBUFS: (libc)Error Codes.
|
* ENOCSI: (libc)Error Codes.
|
* ENODATA: (libc)Error Codes.
|
* ENODEV: (libc)Error Codes.
|
* ENOENT: (libc)Error Codes.
|
* ENOEXEC: (libc)Error Codes.
|
* ENOKEY: (libc)Error Codes.
|
* ENOLCK: (libc)Error Codes.
|
* ENOLINK: (libc)Error Codes.
|
* ENOMEDIUM: (libc)Error Codes.
|
* ENOMEM: (libc)Error Codes.
|
* ENOMSG: (libc)Error Codes.
|
* ENONET: (libc)Error Codes.
|
* ENOPKG: (libc)Error Codes.
|
* ENOPROTOOPT: (libc)Error Codes.
|
* ENOSPC: (libc)Error Codes.
|
* ENOSR: (libc)Error Codes.
|
* ENOSTR: (libc)Error Codes.
|
* ENOSYS: (libc)Error Codes.
|
* ENOTBLK: (libc)Error Codes.
|
* ENOTCONN: (libc)Error Codes.
|
* ENOTDIR: (libc)Error Codes.
|
* ENOTEMPTY: (libc)Error Codes.
|
* ENOTNAM: (libc)Error Codes.
|
* ENOTRECOVERABLE: (libc)Error Codes.
|
* ENOTSOCK: (libc)Error Codes.
|
* ENOTSUP: (libc)Error Codes.
|
* ENOTTY: (libc)Error Codes.
|
* ENOTUNIQ: (libc)Error Codes.
|
* ENXIO: (libc)Error Codes.
|
* EOF: (libc)EOF and Errors.
|
* EOPNOTSUPP: (libc)Error Codes.
|
* EOVERFLOW: (libc)Error Codes.
|
* EOWNERDEAD: (libc)Error Codes.
|
* EPERM: (libc)Error Codes.
|
* EPFNOSUPPORT: (libc)Error Codes.
|
* EPIPE: (libc)Error Codes.
|
* EPROCLIM: (libc)Error Codes.
|
* EPROCUNAVAIL: (libc)Error Codes.
|
* EPROGMISMATCH: (libc)Error Codes.
|
* EPROGUNAVAIL: (libc)Error Codes.
|
* EPROTO: (libc)Error Codes.
|
* EPROTONOSUPPORT: (libc)Error Codes.
|
* EPROTOTYPE: (libc)Error Codes.
|
* EQUIV_CLASS_MAX: (libc)Utility Limits.
|
* ERANGE: (libc)Error Codes.
|
* EREMCHG: (libc)Error Codes.
|
* EREMOTE: (libc)Error Codes.
|
* EREMOTEIO: (libc)Error Codes.
|
* ERESTART: (libc)Error Codes.
|
* ERFKILL: (libc)Error Codes.
|
* EROFS: (libc)Error Codes.
|
* ERPCMISMATCH: (libc)Error Codes.
|
* ESHUTDOWN: (libc)Error Codes.
|
* ESOCKTNOSUPPORT: (libc)Error Codes.
|
* ESPIPE: (libc)Error Codes.
|
* ESRCH: (libc)Error Codes.
|
* ESRMNT: (libc)Error Codes.
|
* ESTALE: (libc)Error Codes.
|
* ESTRPIPE: (libc)Error Codes.
|
* ETIME: (libc)Error Codes.
|
* ETIMEDOUT: (libc)Error Codes.
|
* ETOOMANYREFS: (libc)Error Codes.
|
* ETXTBSY: (libc)Error Codes.
|
* EUCLEAN: (libc)Error Codes.
|
* EUNATCH: (libc)Error Codes.
|
* EUSERS: (libc)Error Codes.
|
* EWOULDBLOCK: (libc)Error Codes.
|
* EXDEV: (libc)Error Codes.
|
* EXFULL: (libc)Error Codes.
|
* EXIT_FAILURE: (libc)Exit Status.
|
* EXIT_SUCCESS: (libc)Exit Status.
|
* EXPR_NEST_MAX: (libc)Utility Limits.
|
* FD_CLOEXEC: (libc)Descriptor Flags.
|
* FD_CLR: (libc)Waiting for I/O.
|
* FD_ISSET: (libc)Waiting for I/O.
|
* FD_SET: (libc)Waiting for I/O.
|
* FD_SETSIZE: (libc)Waiting for I/O.
|
* FD_ZERO: (libc)Waiting for I/O.
|
* 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.
|
* HUPCL: (libc)Control Modes.
|
* I: (libc)Complex Numbers.
|
* ICANON: (libc)Local Modes.
|
* ICRNL: (libc)Input Modes.
|
* IEXTEN: (libc)Local Modes.
|
* IFNAMSIZ: (libc)Interface Naming.
|
* IFTODT: (libc)Directory Entries.
|
* IGNBRK: (libc)Input Modes.
|
* IGNCR: (libc)Input Modes.
|
* IGNPAR: (libc)Input Modes.
|
* IMAXBEL: (libc)Input Modes.
|
* INADDR_ANY: (libc)Host Address Data Type.
|
* INADDR_BROADCAST: (libc)Host Address Data Type.
|
* INADDR_LOOPBACK: (libc)Host Address Data Type.
|
* INADDR_NONE: (libc)Host Address Data Type.
|
* INFINITY: (libc)Infinity and NaN.
|
* INLCR: (libc)Input Modes.
|
* INPCK: (libc)Input Modes.
|
* IPPORT_RESERVED: (libc)Ports.
|
* IPPORT_USERRESERVED: (libc)Ports.
|
* ISIG: (libc)Local Modes.
|
* ISTRIP: (libc)Input Modes.
|
* IXANY: (libc)Input Modes.
|
* IXOFF: (libc)Input Modes.
|
* IXON: (libc)Input Modes.
|
* LINE_MAX: (libc)Utility Limits.
|
* LINK_MAX: (libc)Limits for Files.
|
* L_ctermid: (libc)Identifying the Terminal.
|
* L_cuserid: (libc)Who Logged In.
|
* L_tmpnam: (libc)Temporary Files.
|
* MAXNAMLEN: (libc)Limits for Files.
|
* MAXSYMLINKS: (libc)Symbolic Links.
|
* MAX_CANON: (libc)Limits for Files.
|
* MAX_INPUT: (libc)Limits for Files.
|
* MB_CUR_MAX: (libc)Selecting the Conversion.
|
* MB_LEN_MAX: (libc)Selecting the Conversion.
|
* MDMBUF: (libc)Control Modes.
|
* MSG_DONTROUTE: (libc)Socket Data Options.
|
* MSG_OOB: (libc)Socket Data Options.
|
* MSG_PEEK: (libc)Socket Data Options.
|
* NAME_MAX: (libc)Limits for Files.
|
* NAN: (libc)Infinity and NaN.
|
* NCCS: (libc)Mode Data Types.
|
* NGROUPS_MAX: (libc)General Limits.
|
* NOFLSH: (libc)Local Modes.
|
* NOKERNINFO: (libc)Local Modes.
|
* NSIG: (libc)Standard Signals.
|
* NULL: (libc)Null Pointer Constant.
|
* ONLCR: (libc)Output Modes.
|
* ONOEOT: (libc)Output Modes.
|
* OPEN_MAX: (libc)General Limits.
|
* OPOST: (libc)Output Modes.
|
* OXTABS: (libc)Output Modes.
|
* O_ACCMODE: (libc)Access Modes.
|
* O_APPEND: (libc)Operating Modes.
|
* O_ASYNC: (libc)Operating Modes.
|
* O_CREAT: (libc)Open-time Flags.
|
* O_EXCL: (libc)Open-time Flags.
|
* O_EXEC: (libc)Access Modes.
|
* O_EXLOCK: (libc)Open-time Flags.
|
* O_FSYNC: (libc)Operating Modes.
|
* O_IGNORE_CTTY: (libc)Open-time Flags.
|
* O_NDELAY: (libc)Operating Modes.
|
* O_NOATIME: (libc)Operating Modes.
|
* O_NOCTTY: (libc)Open-time Flags.
|
* O_NOLINK: (libc)Open-time Flags.
|
* O_NONBLOCK: (libc)Open-time Flags.
|
* O_NONBLOCK: (libc)Operating Modes.
|
* O_NOTRANS: (libc)Open-time Flags.
|
* O_RDONLY: (libc)Access Modes.
|
* O_RDWR: (libc)Access Modes.
|
* O_READ: (libc)Access Modes.
|
* O_SHLOCK: (libc)Open-time Flags.
|
* O_SYNC: (libc)Operating Modes.
|
* O_TRUNC: (libc)Open-time Flags.
|
* O_WRITE: (libc)Access Modes.
|
* O_WRONLY: (libc)Access Modes.
|
* PARENB: (libc)Control Modes.
|
* PARMRK: (libc)Input Modes.
|
* PARODD: (libc)Control Modes.
|
* PATH_MAX: (libc)Limits for Files.
|
* PA_FLAG_MASK: (libc)Parsing a Template String.
|
* PENDIN: (libc)Local Modes.
|
* PF_FILE: (libc)Local Namespace Details.
|
* PF_INET6: (libc)Internet Namespace.
|
* PF_INET: (libc)Internet Namespace.
|
* PF_LOCAL: (libc)Local Namespace Details.
|
* PF_UNIX: (libc)Local Namespace Details.
|
* PIPE_BUF: (libc)Limits for Files.
|
* P_tmpdir: (libc)Temporary Files.
|
* RAND_MAX: (libc)ISO Random.
|
* RE_DUP_MAX: (libc)General Limits.
|
* RLIM_INFINITY: (libc)Limits on Resources.
|
* R_OK: (libc)Testing File Access.
|
* SA_NOCLDSTOP: (libc)Flags for Sigaction.
|
* SA_ONSTACK: (libc)Flags for Sigaction.
|
* SA_RESTART: (libc)Flags for Sigaction.
|
* SEEK_CUR: (libc)File Positioning.
|
* SEEK_END: (libc)File Positioning.
|
* SEEK_SET: (libc)File Positioning.
|
* SIGABRT: (libc)Program Error Signals.
|
* SIGALRM: (libc)Alarm Signals.
|
* SIGBUS: (libc)Program Error Signals.
|
* SIGCHLD: (libc)Job Control Signals.
|
* SIGCLD: (libc)Job Control Signals.
|
* SIGCONT: (libc)Job Control Signals.
|
* SIGEMT: (libc)Program Error Signals.
|
* SIGFPE: (libc)Program Error Signals.
|
* SIGHUP: (libc)Termination Signals.
|
* SIGILL: (libc)Program Error Signals.
|
* SIGINFO: (libc)Miscellaneous Signals.
|
* SIGINT: (libc)Termination Signals.
|
* SIGIO: (libc)Asynchronous I/O Signals.
|
* SIGIOT: (libc)Program Error Signals.
|
* SIGKILL: (libc)Termination Signals.
|
* SIGLOST: (libc)Operation Error Signals.
|
* SIGPIPE: (libc)Operation Error Signals.
|
* SIGPOLL: (libc)Asynchronous I/O Signals.
|
* SIGPROF: (libc)Alarm Signals.
|
* SIGQUIT: (libc)Termination Signals.
|
* SIGSEGV: (libc)Program Error Signals.
|
* SIGSTOP: (libc)Job Control Signals.
|
* SIGSYS: (libc)Program Error Signals.
|
* SIGTERM: (libc)Termination Signals.
|
* SIGTRAP: (libc)Program Error Signals.
|
* SIGTSTP: (libc)Job Control Signals.
|
* SIGTTIN: (libc)Job Control Signals.
|
* SIGTTOU: (libc)Job Control Signals.
|
* SIGURG: (libc)Asynchronous I/O Signals.
|
* SIGUSR1: (libc)Miscellaneous Signals.
|
* SIGUSR2: (libc)Miscellaneous Signals.
|
* SIGVTALRM: (libc)Alarm Signals.
|
* SIGWINCH: (libc)Miscellaneous Signals.
|
* SIGXCPU: (libc)Operation Error Signals.
|
* SIGXFSZ: (libc)Operation Error Signals.
|
* SIG_ERR: (libc)Basic Signal Handling.
|
* SNAN: (libc)Infinity and NaN.
|
* SNANF: (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.
|
* __va_copy: (libc)Argument Macros.
|
* _exit: (libc)Termination Internals.
|
* _flushlbf: (libc)Flushing Buffers.
|
* _tolower: (libc)Case Conversion.
|
* _toupper: (libc)Case Conversion.
|
* a64l: (libc)Encode Binary Data.
|
* abort: (libc)Aborting a Program.
|
* abs: (libc)Absolute Value.
|
* accept: (libc)Accepting Connections.
|
* access: (libc)Testing File Access.
|
* acos: (libc)Inverse Trig Functions.
|
* acosf: (libc)Inverse Trig Functions.
|
* acosh: (libc)Hyperbolic Functions.
|
* acoshf: (libc)Hyperbolic Functions.
|
* acoshl: (libc)Hyperbolic Functions.
|
* acosl: (libc)Inverse Trig Functions.
|
* addmntent: (libc)mtab.
|
* addseverity: (libc)Adding Severity Classes.
|
* adjtime: (libc)High-Resolution Calendar.
|
* adjtimex: (libc)High-Resolution Calendar.
|
* aio_cancel64: (libc)Cancel AIO Operations.
|
* aio_cancel: (libc)Cancel AIO Operations.
|
* aio_error64: (libc)Status of AIO Operations.
|
* aio_error: (libc)Status of AIO Operations.
|
* aio_fsync64: (libc)Synchronizing AIO Operations.
|
* aio_fsync: (libc)Synchronizing AIO Operations.
|
* aio_init: (libc)Configuration of AIO.
|
* aio_read64: (libc)Asynchronous Reads/Writes.
|
* aio_read: (libc)Asynchronous Reads/Writes.
|
* aio_return64: (libc)Status of AIO Operations.
|
* aio_return: (libc)Status of AIO Operations.
|
* aio_suspend64: (libc)Synchronizing AIO Operations.
|
* aio_suspend: (libc)Synchronizing AIO Operations.
|
* aio_write64: (libc)Asynchronous Reads/Writes.
|
* aio_write: (libc)Asynchronous Reads/Writes.
|
* alarm: (libc)Setting an Alarm.
|
* aligned_alloc: (libc)Aligned Memory Blocks.
|
* alloca: (libc)Variable Size Automatic.
|
* alphasort64: (libc)Scanning Directory Content.
|
* alphasort: (libc)Scanning Directory Content.
|
* argp_error: (libc)Argp Helper Functions.
|
* argp_failure: (libc)Argp Helper Functions.
|
* argp_help: (libc)Argp Help.
|
* argp_parse: (libc)Argp.
|
* argp_state_help: (libc)Argp Helper Functions.
|
* argp_usage: (libc)Argp Helper Functions.
|
* argz_add: (libc)Argz Functions.
|
* argz_add_sep: (libc)Argz Functions.
|
* argz_append: (libc)Argz Functions.
|
* argz_count: (libc)Argz Functions.
|
* argz_create: (libc)Argz Functions.
|
* argz_create_sep: (libc)Argz Functions.
|
* argz_delete: (libc)Argz Functions.
|
* argz_extract: (libc)Argz Functions.
|
* argz_insert: (libc)Argz Functions.
|
* argz_next: (libc)Argz Functions.
|
* argz_replace: (libc)Argz Functions.
|
* argz_stringify: (libc)Argz Functions.
|
* asctime: (libc)Formatting Calendar Time.
|
* asctime_r: (libc)Formatting Calendar Time.
|
* asin: (libc)Inverse Trig Functions.
|
* asinf: (libc)Inverse Trig Functions.
|
* asinh: (libc)Hyperbolic Functions.
|
* asinhf: (libc)Hyperbolic Functions.
|
* asinhl: (libc)Hyperbolic Functions.
|
* asinl: (libc)Inverse Trig Functions.
|
* asprintf: (libc)Dynamic Output.
|
* assert: (libc)Consistency Checking.
|
* assert_perror: (libc)Consistency Checking.
|
* atan2: (libc)Inverse Trig Functions.
|
* atan2f: (libc)Inverse Trig Functions.
|
* atan2l: (libc)Inverse Trig Functions.
|
* atan: (libc)Inverse Trig Functions.
|
* atanf: (libc)Inverse Trig Functions.
|
* atanh: (libc)Hyperbolic Functions.
|
* atanhf: (libc)Hyperbolic Functions.
|
* atanhl: (libc)Hyperbolic Functions.
|
* atanl: (libc)Inverse Trig Functions.
|
* atexit: (libc)Cleanups on Exit.
|
* atof: (libc)Parsing of Floats.
|
* atoi: (libc)Parsing of Integers.
|
* atol: (libc)Parsing of Integers.
|
* atoll: (libc)Parsing of Integers.
|
* backtrace: (libc)Backtraces.
|
* backtrace_symbols: (libc)Backtraces.
|
* backtrace_symbols_fd: (libc)Backtraces.
|
* basename: (libc)Finding Tokens in a String.
|
* basename: (libc)Finding Tokens in a String.
|
* bcmp: (libc)String/Array Comparison.
|
* bcopy: (libc)Copying 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.
|
* cabsl: (libc)Absolute Value.
|
* cacos: (libc)Inverse Trig Functions.
|
* cacosf: (libc)Inverse Trig Functions.
|
* cacosh: (libc)Hyperbolic Functions.
|
* cacoshf: (libc)Hyperbolic Functions.
|
* cacoshl: (libc)Hyperbolic Functions.
|
* cacosl: (libc)Inverse Trig Functions.
|
* calloc: (libc)Allocating Cleared Space.
|
* canonicalize: (libc)FP Bit Twiddling.
|
* canonicalize_file_name: (libc)Symbolic Links.
|
* canonicalizef: (libc)FP Bit Twiddling.
|
* canonicalizel: (libc)FP Bit Twiddling.
|
* carg: (libc)Operations on Complex.
|
* cargf: (libc)Operations on Complex.
|
* cargl: (libc)Operations on Complex.
|
* casin: (libc)Inverse Trig Functions.
|
* casinf: (libc)Inverse Trig Functions.
|
* casinh: (libc)Hyperbolic Functions.
|
* casinhf: (libc)Hyperbolic Functions.
|
* casinhl: (libc)Hyperbolic Functions.
|
* casinl: (libc)Inverse Trig Functions.
|
* catan: (libc)Inverse Trig Functions.
|
* catanf: (libc)Inverse Trig Functions.
|
* catanh: (libc)Hyperbolic Functions.
|
* catanhf: (libc)Hyperbolic Functions.
|
* catanhl: (libc)Hyperbolic Functions.
|
* catanl: (libc)Inverse Trig Functions.
|
* catclose: (libc)The catgets Functions.
|
* catgets: (libc)The catgets Functions.
|
* catopen: (libc)The catgets Functions.
|
* cbc_crypt: (libc)DES Encryption.
|
* cbrt: (libc)Exponents and Logarithms.
|
* cbrtf: (libc)Exponents and Logarithms.
|
* cbrtl: (libc)Exponents and Logarithms.
|
* ccos: (libc)Trig Functions.
|
* ccosf: (libc)Trig Functions.
|
* ccosh: (libc)Hyperbolic Functions.
|
* ccoshf: (libc)Hyperbolic Functions.
|
* ccoshl: (libc)Hyperbolic Functions.
|
* ccosl: (libc)Trig Functions.
|
* ceil: (libc)Rounding Functions.
|
* ceilf: (libc)Rounding Functions.
|
* ceill: (libc)Rounding Functions.
|
* cexp: (libc)Exponents and Logarithms.
|
* cexpf: (libc)Exponents and Logarithms.
|
* cexpl: (libc)Exponents and Logarithms.
|
* cfgetispeed: (libc)Line Speed.
|
* cfgetospeed: (libc)Line Speed.
|
* cfmakeraw: (libc)Noncanonical Input.
|
* cfree: (libc)Freeing after Malloc.
|
* cfsetispeed: (libc)Line Speed.
|
* cfsetospeed: (libc)Line Speed.
|
* cfsetspeed: (libc)Line Speed.
|
* chdir: (libc)Working Directory.
|
* chmod: (libc)Setting Permissions.
|
* chown: (libc)File Owner.
|
* cimag: (libc)Operations on Complex.
|
* cimagf: (libc)Operations on Complex.
|
* cimagl: (libc)Operations on Complex.
|
* clearenv: (libc)Environment Access.
|
* clearerr: (libc)Error Recovery.
|
* clearerr_unlocked: (libc)Error Recovery.
|
* clock: (libc)CPU Time.
|
* clog10: (libc)Exponents and Logarithms.
|
* clog10f: (libc)Exponents and Logarithms.
|
* clog10l: (libc)Exponents and Logarithms.
|
* clog: (libc)Exponents and Logarithms.
|
* clogf: (libc)Exponents and Logarithms.
|
* clogl: (libc)Exponents and Logarithms.
|
* close: (libc)Opening and Closing Files.
|
* closedir: (libc)Reading/Closing Directory.
|
* closelog: (libc)closelog.
|
* confstr: (libc)String Parameters.
|
* conj: (libc)Operations on Complex.
|
* conjf: (libc)Operations on Complex.
|
* conjl: (libc)Operations on Complex.
|
* connect: (libc)Connecting.
|
* copysign: (libc)FP Bit Twiddling.
|
* copysignf: (libc)FP Bit Twiddling.
|
* copysignl: (libc)FP Bit Twiddling.
|
* cos: (libc)Trig Functions.
|
* cosf: (libc)Trig Functions.
|
* cosh: (libc)Hyperbolic Functions.
|
* coshf: (libc)Hyperbolic Functions.
|
* coshl: (libc)Hyperbolic Functions.
|
* cosl: (libc)Trig Functions.
|
* cpow: (libc)Exponents and Logarithms.
|
* cpowf: (libc)Exponents and Logarithms.
|
* cpowl: (libc)Exponents and Logarithms.
|
* cproj: (libc)Operations on Complex.
|
* cprojf: (libc)Operations on Complex.
|
* cprojl: (libc)Operations on Complex.
|
* creal: (libc)Operations on Complex.
|
* crealf: (libc)Operations on Complex.
|
* creall: (libc)Operations on Complex.
|
* creat64: (libc)Opening and Closing Files.
|
* creat: (libc)Opening and Closing Files.
|
* crypt: (libc)crypt.
|
* crypt_r: (libc)crypt.
|
* csin: (libc)Trig Functions.
|
* csinf: (libc)Trig Functions.
|
* csinh: (libc)Hyperbolic Functions.
|
* csinhf: (libc)Hyperbolic Functions.
|
* csinhl: (libc)Hyperbolic Functions.
|
* csinl: (libc)Trig Functions.
|
* csqrt: (libc)Exponents and Logarithms.
|
* csqrtf: (libc)Exponents and Logarithms.
|
* csqrtl: (libc)Exponents and Logarithms.
|
* ctan: (libc)Trig Functions.
|
* ctanf: (libc)Trig Functions.
|
* ctanh: (libc)Hyperbolic Functions.
|
* ctanhf: (libc)Hyperbolic Functions.
|
* ctanhl: (libc)Hyperbolic Functions.
|
* ctanl: (libc)Trig Functions.
|
* ctermid: (libc)Identifying the Terminal.
|
* ctime: (libc)Formatting Calendar Time.
|
* ctime_r: (libc)Formatting Calendar Time.
|
* cuserid: (libc)Who Logged In.
|
* dcgettext: (libc)Translation with gettext.
|
* dcngettext: (libc)Advanced gettext functions.
|
* des_setparity: (libc)DES Encryption.
|
* dgettext: (libc)Translation with gettext.
|
* difftime: (libc)Elapsed Time.
|
* dirfd: (libc)Opening a Directory.
|
* dirname: (libc)Finding Tokens in a String.
|
* div: (libc)Integer Division.
|
* dngettext: (libc)Advanced gettext functions.
|
* drand48: (libc)SVID Random.
|
* drand48_r: (libc)SVID Random.
|
* drem: (libc)Remainder Functions.
|
* dremf: (libc)Remainder Functions.
|
* dreml: (libc)Remainder Functions.
|
* dup2: (libc)Duplicating Descriptors.
|
* dup: (libc)Duplicating Descriptors.
|
* ecb_crypt: (libc)DES Encryption.
|
* ecvt: (libc)System V Number Conversion.
|
* ecvt_r: (libc)System V Number Conversion.
|
* encrypt: (libc)DES Encryption.
|
* encrypt_r: (libc)DES Encryption.
|
* endfsent: (libc)fstab.
|
* endgrent: (libc)Scanning All Groups.
|
* endhostent: (libc)Host Names.
|
* endmntent: (libc)mtab.
|
* endnetent: (libc)Networks Database.
|
* endnetgrent: (libc)Lookup Netgroup.
|
* endprotoent: (libc)Protocols Database.
|
* endpwent: (libc)Scanning All Users.
|
* endservent: (libc)Services Database.
|
* endutent: (libc)Manipulating the Database.
|
* endutxent: (libc)XPG Functions.
|
* envz_add: (libc)Envz Functions.
|
* envz_entry: (libc)Envz Functions.
|
* envz_get: (libc)Envz Functions.
|
* envz_merge: (libc)Envz Functions.
|
* envz_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.
|
* erfcl: (libc)Special Functions.
|
* erff: (libc)Special Functions.
|
* erfl: (libc)Special Functions.
|
* err: (libc)Error Messages.
|
* errno: (libc)Checking for Errors.
|
* error: (libc)Error Messages.
|
* error_at_line: (libc)Error Messages.
|
* errx: (libc)Error Messages.
|
* execl: (libc)Executing a File.
|
* execle: (libc)Executing a File.
|
* execlp: (libc)Executing a File.
|
* execv: (libc)Executing a File.
|
* execve: (libc)Executing a File.
|
* execvp: (libc)Executing a File.
|
* exit: (libc)Normal Termination.
|
* exp10: (libc)Exponents and Logarithms.
|
* exp10f: (libc)Exponents and Logarithms.
|
* exp10l: (libc)Exponents and Logarithms.
|
* exp2: (libc)Exponents and Logarithms.
|
* exp2f: (libc)Exponents and Logarithms.
|
* exp2l: (libc)Exponents and Logarithms.
|
* exp: (libc)Exponents and Logarithms.
|
* expf: (libc)Exponents and Logarithms.
|
* expl: (libc)Exponents and Logarithms.
|
* explicit_bzero: (libc)Erasing Sensitive Data.
|
* expm1: (libc)Exponents and Logarithms.
|
* expm1f: (libc)Exponents and Logarithms.
|
* expm1l: (libc)Exponents and Logarithms.
|
* fabs: (libc)Absolute Value.
|
* fabsf: (libc)Absolute Value.
|
* fabsl: (libc)Absolute Value.
|
* fchdir: (libc)Working Directory.
|
* fchmod: (libc)Setting Permissions.
|
* fchown: (libc)File Owner.
|
* fclose: (libc)Closing Streams.
|
* fcloseall: (libc)Closing Streams.
|
* fcntl: (libc)Control Operations.
|
* fcvt: (libc)System V Number Conversion.
|
* fcvt_r: (libc)System V Number Conversion.
|
* fdatasync: (libc)Synchronizing I/O.
|
* fdim: (libc)Misc FP Arithmetic.
|
* fdimf: (libc)Misc FP Arithmetic.
|
* fdiml: (libc)Misc FP Arithmetic.
|
* fdopen: (libc)Descriptors and Streams.
|
* fdopendir: (libc)Opening a Directory.
|
* feclearexcept: (libc)Status bit operations.
|
* fedisableexcept: (libc)Control Functions.
|
* feenableexcept: (libc)Control Functions.
|
* fegetenv: (libc)Control Functions.
|
* fegetexcept: (libc)Control Functions.
|
* fegetexceptflag: (libc)Status bit operations.
|
* 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.
|
* floorl: (libc)Rounding Functions.
|
* fma: (libc)Misc FP Arithmetic.
|
* fmaf: (libc)Misc FP Arithmetic.
|
* fmal: (libc)Misc FP Arithmetic.
|
* fmax: (libc)Misc FP Arithmetic.
|
* fmaxf: (libc)Misc FP Arithmetic.
|
* fmaxl: (libc)Misc FP Arithmetic.
|
* fmaxmag: (libc)Misc FP Arithmetic.
|
* fmaxmagf: (libc)Misc FP Arithmetic.
|
* fmaxmagl: (libc)Misc FP Arithmetic.
|
* fmemopen: (libc)String Streams.
|
* fmin: (libc)Misc FP Arithmetic.
|
* fminf: (libc)Misc FP Arithmetic.
|
* fminl: (libc)Misc FP Arithmetic.
|
* fminmag: (libc)Misc FP Arithmetic.
|
* fminmagf: (libc)Misc FP Arithmetic.
|
* fminmagl: (libc)Misc FP Arithmetic.
|
* fmod: (libc)Remainder Functions.
|
* fmodf: (libc)Remainder Functions.
|
* fmodl: (libc)Remainder Functions.
|
* fmtmsg: (libc)Printing Formatted Messages.
|
* fnmatch: (libc)Wildcard Matching.
|
* fopen64: (libc)Opening Streams.
|
* fopen: (libc)Opening Streams.
|
* fopencookie: (libc)Streams and Cookies.
|
* fork: (libc)Creating a Process.
|
* forkpty: (libc)Pseudo-Terminal Pairs.
|
* fpathconf: (libc)Pathconf.
|
* fpclassify: (libc)Floating Point Classes.
|
* fprintf: (libc)Formatted Output Functions.
|
* fputc: (libc)Simple Output.
|
* fputc_unlocked: (libc)Simple Output.
|
* fputs: (libc)Simple Output.
|
* fputs_unlocked: (libc)Simple Output.
|
* fputwc: (libc)Simple Output.
|
* fputwc_unlocked: (libc)Simple Output.
|
* fputws: (libc)Simple Output.
|
* fputws_unlocked: (libc)Simple Output.
|
* fread: (libc)Block Input/Output.
|
* fread_unlocked: (libc)Block Input/Output.
|
* free: (libc)Freeing after Malloc.
|
* freopen64: (libc)Opening Streams.
|
* freopen: (libc)Opening Streams.
|
* frexp: (libc)Normalization Functions.
|
* frexpf: (libc)Normalization Functions.
|
* frexpl: (libc)Normalization Functions.
|
* fromfp: (libc)Rounding Functions.
|
* fromfpf: (libc)Rounding Functions.
|
* fromfpl: (libc)Rounding Functions.
|
* fromfpx: (libc)Rounding Functions.
|
* fromfpxf: (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.
|
* fsync: (libc)Synchronizing I/O.
|
* ftell: (libc)File Positioning.
|
* ftello64: (libc)File Positioning.
|
* ftello: (libc)File Positioning.
|
* ftruncate64: (libc)File Size.
|
* ftruncate: (libc)File Size.
|
* ftrylockfile: (libc)Streams and Threads.
|
* ftw64: (libc)Working with Directory Trees.
|
* ftw: (libc)Working with Directory Trees.
|
* funlockfile: (libc)Streams and Threads.
|
* futimes: (libc)File Times.
|
* fwide: (libc)Streams and I18N.
|
* fwprintf: (libc)Formatted Output Functions.
|
* fwrite: (libc)Block Input/Output.
|
* fwrite_unlocked: (libc)Block Input/Output.
|
* fwscanf: (libc)Formatted Input Functions.
|
* gamma: (libc)Special Functions.
|
* gammaf: (libc)Special Functions.
|
* gammal: (libc)Special Functions.
|
* gcvt: (libc)System V Number Conversion.
|
* get_avphys_pages: (libc)Query Memory Parameters.
|
* get_current_dir_name: (libc)Working Directory.
|
* get_nprocs: (libc)Processor Resources.
|
* get_nprocs_conf: (libc)Processor Resources.
|
* get_phys_pages: (libc)Query Memory Parameters.
|
* getauxval: (libc)Auxiliary Vector.
|
* getc: (libc)Character Input.
|
* getc_unlocked: (libc)Character Input.
|
* getchar: (libc)Character Input.
|
* getchar_unlocked: (libc)Character Input.
|
* getcontext: (libc)System V contexts.
|
* getcwd: (libc)Working Directory.
|
* getdate: (libc)General Time String Parsing.
|
* getdate_r: (libc)General Time String Parsing.
|
* getdelim: (libc)Line Input.
|
* getdomainnname: (libc)Host Identification.
|
* getegid: (libc)Reading Persona.
|
* 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.
|
* 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.
|
* gettimeofday: (libc)High-Resolution Calendar.
|
* getuid: (libc)Reading Persona.
|
* getumask: (libc)Setting Permissions.
|
* getutent: (libc)Manipulating the Database.
|
* getutent_r: (libc)Manipulating the Database.
|
* getutid: (libc)Manipulating the Database.
|
* getutid_r: (libc)Manipulating the Database.
|
* getutline: (libc)Manipulating the Database.
|
* getutline_r: (libc)Manipulating the Database.
|
* getutmp: (libc)XPG Functions.
|
* getutmpx: (libc)XPG Functions.
|
* getutxent: (libc)XPG Functions.
|
* getutxid: (libc)XPG Functions.
|
* getutxline: (libc)XPG Functions.
|
* getw: (libc)Character Input.
|
* getwc: (libc)Character Input.
|
* getwc_unlocked: (libc)Character Input.
|
* getwchar: (libc)Character Input.
|
* getwchar_unlocked: (libc)Character Input.
|
* getwd: (libc)Working Directory.
|
* glob64: (libc)Calling Glob.
|
* glob: (libc)Calling Glob.
|
* globfree64: (libc)More Flags for Globbing.
|
* globfree: (libc)More Flags for Globbing.
|
* gmtime: (libc)Broken-down Time.
|
* gmtime_r: (libc)Broken-down Time.
|
* grantpt: (libc)Allocation.
|
* gsignal: (libc)Signaling Yourself.
|
* gtty: (libc)BSD Terminal Modes.
|
* hasmntopt: (libc)mtab.
|
* hcreate: (libc)Hash Search Function.
|
* hcreate_r: (libc)Hash Search Function.
|
* hdestroy: (libc)Hash Search Function.
|
* hdestroy_r: (libc)Hash Search Function.
|
* hsearch: (libc)Hash Search Function.
|
* hsearch_r: (libc)Hash Search Function.
|
* htonl: (libc)Byte Order.
|
* htons: (libc)Byte Order.
|
* hypot: (libc)Exponents and Logarithms.
|
* hypotf: (libc)Exponents and Logarithms.
|
* hypotl: (libc)Exponents and Logarithms.
|
* iconv: (libc)Generic Conversion Interface.
|
* iconv_close: (libc)Generic Conversion Interface.
|
* iconv_open: (libc)Generic Conversion Interface.
|
* if_freenameindex: (libc)Interface Naming.
|
* if_indextoname: (libc)Interface Naming.
|
* if_nameindex: (libc)Interface Naming.
|
* if_nametoindex: (libc)Interface Naming.
|
* ilogb: (libc)Exponents and Logarithms.
|
* ilogbf: (libc)Exponents and Logarithms.
|
* ilogbl: (libc)Exponents and Logarithms.
|
* imaxabs: (libc)Absolute Value.
|
* imaxdiv: (libc)Integer Division.
|
* in6addr_any: (libc)Host Address Data Type.
|
* in6addr_loopback: (libc)Host Address Data Type.
|
* index: (libc)Search Functions.
|
* inet_addr: (libc)Host Address Functions.
|
* inet_aton: (libc)Host Address Functions.
|
* inet_lnaof: (libc)Host Address Functions.
|
* inet_makeaddr: (libc)Host Address Functions.
|
* inet_netof: (libc)Host Address Functions.
|
* inet_network: (libc)Host Address Functions.
|
* inet_ntoa: (libc)Host Address Functions.
|
* inet_ntop: (libc)Host Address Functions.
|
* inet_pton: (libc)Host Address Functions.
|
* initgroups: (libc)Setting Groups.
|
* initstate: (libc)BSD Random.
|
* initstate_r: (libc)BSD Random.
|
* innetgr: (libc)Netgroup Membership.
|
* ioctl: (libc)IOCTLs.
|
* isalnum: (libc)Classification of Characters.
|
* isalpha: (libc)Classification of Characters.
|
* isascii: (libc)Classification of Characters.
|
* isatty: (libc)Is It a Terminal.
|
* isblank: (libc)Classification of Characters.
|
* 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.
|
* j0l: (libc)Special Functions.
|
* j1: (libc)Special Functions.
|
* j1f: (libc)Special Functions.
|
* j1l: (libc)Special Functions.
|
* jn: (libc)Special Functions.
|
* jnf: (libc)Special Functions.
|
* jnl: (libc)Special Functions.
|
* jrand48: (libc)SVID Random.
|
* jrand48_r: (libc)SVID Random.
|
* kill: (libc)Signaling Another Process.
|
* killpg: (libc)Signaling Another Process.
|
* l64a: (libc)Encode Binary Data.
|
* labs: (libc)Absolute Value.
|
* lcong48: (libc)SVID Random.
|
* lcong48_r: (libc)SVID Random.
|
* ldexp: (libc)Normalization Functions.
|
* ldexpf: (libc)Normalization Functions.
|
* ldexpl: (libc)Normalization Functions.
|
* ldiv: (libc)Integer Division.
|
* lfind: (libc)Array Search Function.
|
* lgamma: (libc)Special Functions.
|
* lgamma_r: (libc)Special Functions.
|
* lgammaf: (libc)Special Functions.
|
* lgammaf_r: (libc)Special Functions.
|
* lgammal: (libc)Special Functions.
|
* lgammal_r: (libc)Special Functions.
|
* link: (libc)Hard Links.
|
* lio_listio64: (libc)Asynchronous Reads/Writes.
|
* lio_listio: (libc)Asynchronous Reads/Writes.
|
* listen: (libc)Listening.
|
* llabs: (libc)Absolute Value.
|
* lldiv: (libc)Integer Division.
|
* llogb: (libc)Exponents and Logarithms.
|
* llogbf: (libc)Exponents and Logarithms.
|
* llogbl: (libc)Exponents and Logarithms.
|
* llrint: (libc)Rounding Functions.
|
* llrintf: (libc)Rounding Functions.
|
* llrintl: (libc)Rounding Functions.
|
* llround: (libc)Rounding Functions.
|
* llroundf: (libc)Rounding Functions.
|
* llroundl: (libc)Rounding Functions.
|
* localeconv: (libc)The Lame Way to Locale Data.
|
* localtime: (libc)Broken-down Time.
|
* localtime_r: (libc)Broken-down Time.
|
* log10: (libc)Exponents and Logarithms.
|
* log10f: (libc)Exponents and Logarithms.
|
* log10l: (libc)Exponents and Logarithms.
|
* log1p: (libc)Exponents and Logarithms.
|
* log1pf: (libc)Exponents and Logarithms.
|
* log1pl: (libc)Exponents and Logarithms.
|
* log2: (libc)Exponents and Logarithms.
|
* log2f: (libc)Exponents and Logarithms.
|
* log2l: (libc)Exponents and Logarithms.
|
* log: (libc)Exponents and Logarithms.
|
* logb: (libc)Exponents and Logarithms.
|
* logbf: (libc)Exponents and Logarithms.
|
* logbl: (libc)Exponents and Logarithms.
|
* logf: (libc)Exponents and Logarithms.
|
* login: (libc)Logging In and Out.
|
* login_tty: (libc)Logging In and Out.
|
* logl: (libc)Exponents and Logarithms.
|
* logout: (libc)Logging In and Out.
|
* logwtmp: (libc)Logging In and Out.
|
* longjmp: (libc)Non-Local Details.
|
* lrand48: (libc)SVID Random.
|
* lrand48_r: (libc)SVID Random.
|
* lrint: (libc)Rounding Functions.
|
* lrintf: (libc)Rounding Functions.
|
* lrintl: (libc)Rounding Functions.
|
* lround: (libc)Rounding Functions.
|
* lroundf: (libc)Rounding Functions.
|
* lroundl: (libc)Rounding Functions.
|
* lsearch: (libc)Array Search Function.
|
* lseek64: (libc)File Position Primitive.
|
* lseek: (libc)File Position Primitive.
|
* lstat64: (libc)Reading Attributes.
|
* lstat: (libc)Reading Attributes.
|
* lutimes: (libc)File Times.
|
* madvise: (libc)Memory-mapped I/O.
|
* makecontext: (libc)System V contexts.
|
* mallinfo: (libc)Statistics of Malloc.
|
* malloc: (libc)Basic Allocation.
|
* mallopt: (libc)Malloc Tunable Parameters.
|
* mblen: (libc)Non-reentrant Character Conversion.
|
* mbrlen: (libc)Converting a Character.
|
* mbrtowc: (libc)Converting a Character.
|
* mbsinit: (libc)Keeping the state.
|
* mbsnrtowcs: (libc)Converting Strings.
|
* mbsrtowcs: (libc)Converting Strings.
|
* mbstowcs: (libc)Non-reentrant String Conversion.
|
* mbtowc: (libc)Non-reentrant Character Conversion.
|
* mcheck: (libc)Heap Consistency Checking.
|
* memalign: (libc)Aligned Memory Blocks.
|
* memccpy: (libc)Copying Strings and Arrays.
|
* memchr: (libc)Search Functions.
|
* memcmp: (libc)String/Array Comparison.
|
* memcpy: (libc)Copying Strings and Arrays.
|
* memfrob: (libc)Trivial Encryption.
|
* 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.
|
* mlock: (libc)Page Lock Functions.
|
* mlockall: (libc)Page Lock Functions.
|
* mmap64: (libc)Memory-mapped I/O.
|
* mmap: (libc)Memory-mapped I/O.
|
* modf: (libc)Rounding Functions.
|
* modff: (libc)Rounding Functions.
|
* modfl: (libc)Rounding Functions.
|
* mount: (libc)Mount-Unmount-Remount.
|
* mprobe: (libc)Heap Consistency Checking.
|
* mrand48: (libc)SVID Random.
|
* mrand48_r: (libc)SVID Random.
|
* mremap: (libc)Memory-mapped I/O.
|
* msync: (libc)Memory-mapped I/O.
|
* mtrace: (libc)Tracing malloc.
|
* munlock: (libc)Page Lock Functions.
|
* munlockall: (libc)Page Lock Functions.
|
* munmap: (libc)Memory-mapped I/O.
|
* muntrace: (libc)Tracing malloc.
|
* nan: (libc)FP Bit Twiddling.
|
* nanf: (libc)FP Bit Twiddling.
|
* nanl: (libc)FP Bit Twiddling.
|
* nanosleep: (libc)Sleeping.
|
* nearbyint: (libc)Rounding Functions.
|
* nearbyintf: (libc)Rounding Functions.
|
* nearbyintl: (libc)Rounding Functions.
|
* nextafter: (libc)FP Bit Twiddling.
|
* nextafterf: (libc)FP Bit Twiddling.
|
* nextafterl: (libc)FP Bit Twiddling.
|
* nextdown: (libc)FP Bit Twiddling.
|
* nextdownf: (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.
|
* 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.
|
* popen: (libc)Pipe to a Subprocess.
|
* posix_fallocate64: (libc)Storage Allocation.
|
* posix_fallocate: (libc)Storage Allocation.
|
* posix_memalign: (libc)Aligned Memory Blocks.
|
* pow10: (libc)Exponents and Logarithms.
|
* pow10f: (libc)Exponents and Logarithms.
|
* pow10l: (libc)Exponents and Logarithms.
|
* pow: (libc)Exponents and Logarithms.
|
* powf: (libc)Exponents and Logarithms.
|
* powl: (libc)Exponents and Logarithms.
|
* pread64: (libc)I/O Primitives.
|
* pread: (libc)I/O Primitives.
|
* printf: (libc)Formatted Output Functions.
|
* printf_size: (libc)Predefined Printf Handlers.
|
* printf_size_info: (libc)Predefined Printf Handlers.
|
* psignal: (libc)Signal Messages.
|
* pthread_getattr_default_np: (libc)Default Thread Attributes.
|
* pthread_getspecific: (libc)Thread-specific Data.
|
* pthread_key_create: (libc)Thread-specific Data.
|
* pthread_key_delete: (libc)Thread-specific Data.
|
* pthread_setattr_default_np: (libc)Default Thread Attributes.
|
* pthread_setspecific: (libc)Thread-specific Data.
|
* ptsname: (libc)Allocation.
|
* ptsname_r: (libc)Allocation.
|
* putc: (libc)Simple Output.
|
* putc_unlocked: (libc)Simple Output.
|
* putchar: (libc)Simple Output.
|
* putchar_unlocked: (libc)Simple Output.
|
* putenv: (libc)Environment Access.
|
* putpwent: (libc)Writing a User Entry.
|
* puts: (libc)Simple Output.
|
* pututline: (libc)Manipulating the Database.
|
* pututxline: (libc)XPG Functions.
|
* putw: (libc)Simple Output.
|
* putwc: (libc)Simple Output.
|
* putwc_unlocked: (libc)Simple Output.
|
* putwchar: (libc)Simple Output.
|
* putwchar_unlocked: (libc)Simple Output.
|
* pwrite64: (libc)I/O Primitives.
|
* pwrite: (libc)I/O Primitives.
|
* qecvt: (libc)System V Number Conversion.
|
* qecvt_r: (libc)System V Number Conversion.
|
* qfcvt: (libc)System V Number Conversion.
|
* qfcvt_r: (libc)System V Number Conversion.
|
* qgcvt: (libc)System V Number Conversion.
|
* qsort: (libc)Array Sort Function.
|
* raise: (libc)Signaling Yourself.
|
* rand: (libc)ISO Random.
|
* rand_r: (libc)ISO Random.
|
* random: (libc)BSD Random.
|
* random_r: (libc)BSD Random.
|
* rawmemchr: (libc)Search Functions.
|
* read: (libc)I/O Primitives.
|
* readdir64: (libc)Reading/Closing Directory.
|
* readdir64_r: (libc)Reading/Closing Directory.
|
* readdir: (libc)Reading/Closing Directory.
|
* readdir_r: (libc)Reading/Closing Directory.
|
* readlink: (libc)Symbolic Links.
|
* readv: (libc)Scatter-Gather.
|
* realloc: (libc)Changing Block Size.
|
* realpath: (libc)Symbolic Links.
|
* recv: (libc)Receiving Data.
|
* recvfrom: (libc)Receiving Datagrams.
|
* recvmsg: (libc)Receiving Datagrams.
|
* regcomp: (libc)POSIX Regexp Compilation.
|
* regerror: (libc)Regexp Cleanup.
|
* regexec: (libc)Matching POSIX Regexps.
|
* regfree: (libc)Regexp Cleanup.
|
* register_printf_function: (libc)Registering New Conversions.
|
* remainder: (libc)Remainder Functions.
|
* remainderf: (libc)Remainder Functions.
|
* remainderl: (libc)Remainder Functions.
|
* remove: (libc)Deleting Files.
|
* rename: (libc)Renaming Files.
|
* rewind: (libc)File Positioning.
|
* rewinddir: (libc)Random Access Directory.
|
* rindex: (libc)Search Functions.
|
* rint: (libc)Rounding Functions.
|
* rintf: (libc)Rounding Functions.
|
* rintl: (libc)Rounding Functions.
|
* rmdir: (libc)Deleting Files.
|
* round: (libc)Rounding Functions.
|
* roundeven: (libc)Rounding Functions.
|
* roundevenf: (libc)Rounding Functions.
|
* roundevenl: (libc)Rounding Functions.
|
* roundf: (libc)Rounding Functions.
|
* roundl: (libc)Rounding Functions.
|
* rpmatch: (libc)Yes-or-No Questions.
|
* sbrk: (libc)Resizing the Data Segment.
|
* scalb: (libc)Normalization Functions.
|
* scalbf: (libc)Normalization Functions.
|
* scalbl: (libc)Normalization Functions.
|
* scalbln: (libc)Normalization Functions.
|
* scalblnf: (libc)Normalization Functions.
|
* scalblnl: (libc)Normalization Functions.
|
* scalbn: (libc)Normalization Functions.
|
* scalbnf: (libc)Normalization Functions.
|
* scalbnl: (libc)Normalization Functions.
|
* scandir64: (libc)Scanning Directory Content.
|
* scandir: (libc)Scanning Directory Content.
|
* scanf: (libc)Formatted Input Functions.
|
* sched_get_priority_max: (libc)Basic Scheduling Functions.
|
* sched_get_priority_min: (libc)Basic Scheduling Functions.
|
* sched_getaffinity: (libc)CPU Affinity.
|
* sched_getparam: (libc)Basic Scheduling Functions.
|
* sched_getscheduler: (libc)Basic Scheduling Functions.
|
* sched_rr_get_interval: (libc)Basic Scheduling Functions.
|
* sched_setaffinity: (libc)CPU Affinity.
|
* sched_setparam: (libc)Basic Scheduling Functions.
|
* sched_setscheduler: (libc)Basic Scheduling Functions.
|
* sched_yield: (libc)Basic Scheduling Functions.
|
* secure_getenv: (libc)Environment Access.
|
* seed48: (libc)SVID Random.
|
* seed48_r: (libc)SVID Random.
|
* seekdir: (libc)Random Access Directory.
|
* select: (libc)Waiting for I/O.
|
* 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.
|
* setkey: (libc)DES Encryption.
|
* setkey_r: (libc)DES Encryption.
|
* setlinebuf: (libc)Controlling Buffering.
|
* setlocale: (libc)Setting the Locale.
|
* setlogmask: (libc)setlogmask.
|
* setmntent: (libc)mtab.
|
* setnetent: (libc)Networks Database.
|
* setnetgrent: (libc)Lookup Netgroup.
|
* setpayload: (libc)FP Bit Twiddling.
|
* setpayloadf: (libc)FP Bit Twiddling.
|
* setpayloadl: (libc)FP Bit Twiddling.
|
* setpayloadsig: (libc)FP Bit Twiddling.
|
* setpayloadsigf: (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.
|
* sincosl: (libc)Trig Functions.
|
* sinf: (libc)Trig Functions.
|
* sinh: (libc)Hyperbolic Functions.
|
* sinhf: (libc)Hyperbolic Functions.
|
* sinhl: (libc)Hyperbolic Functions.
|
* sinl: (libc)Trig Functions.
|
* sleep: (libc)Sleeping.
|
* snprintf: (libc)Formatted Output Functions.
|
* socket: (libc)Creating a Socket.
|
* socketpair: (libc)Socket Pairs.
|
* sprintf: (libc)Formatted Output Functions.
|
* sqrt: (libc)Exponents and Logarithms.
|
* sqrtf: (libc)Exponents and Logarithms.
|
* sqrtl: (libc)Exponents and Logarithms.
|
* srand48: (libc)SVID Random.
|
* srand48_r: (libc)SVID Random.
|
* srand: (libc)ISO Random.
|
* srandom: (libc)BSD Random.
|
* srandom_r: (libc)BSD Random.
|
* sscanf: (libc)Formatted Input Functions.
|
* ssignal: (libc)Basic Signal Handling.
|
* stat64: (libc)Reading Attributes.
|
* stat: (libc)Reading Attributes.
|
* stime: (libc)Simple Calendar Time.
|
* stpcpy: (libc)Copying 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.
|
* strfroml: (libc)Printing of Floats.
|
* strfry: (libc)strfry.
|
* 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.
|
* strtoimax: (libc)Parsing of Integers.
|
* strtok: (libc)Finding Tokens in a String.
|
* strtok_r: (libc)Finding Tokens in a String.
|
* strtol: (libc)Parsing of Integers.
|
* strtold: (libc)Parsing of Floats.
|
* strtoll: (libc)Parsing of Integers.
|
* strtoq: (libc)Parsing of Integers.
|
* strtoul: (libc)Parsing of Integers.
|
* strtoull: (libc)Parsing of Integers.
|
* strtoumax: (libc)Parsing of Integers.
|
* strtouq: (libc)Parsing of Integers.
|
* strverscmp: (libc)String/Array Comparison.
|
* strxfrm: (libc)Collation Functions.
|
* stty: (libc)BSD Terminal Modes.
|
* swapcontext: (libc)System V contexts.
|
* swprintf: (libc)Formatted Output Functions.
|
* swscanf: (libc)Formatted Input Functions.
|
* symlink: (libc)Symbolic Links.
|
* sync: (libc)Synchronizing I/O.
|
* syscall: (libc)System Calls.
|
* sysconf: (libc)Sysconf Definition.
|
* sysctl: (libc)System Parameters.
|
* syslog: (libc)syslog; vsyslog.
|
* system: (libc)Running a Command.
|
* sysv_signal: (libc)Basic Signal Handling.
|
* tan: (libc)Trig Functions.
|
* tanf: (libc)Trig Functions.
|
* tanh: (libc)Hyperbolic Functions.
|
* tanhf: (libc)Hyperbolic Functions.
|
* tanhl: (libc)Hyperbolic Functions.
|
* tanl: (libc)Trig Functions.
|
* tcdrain: (libc)Line Control.
|
* tcflow: (libc)Line Control.
|
* tcflush: (libc)Line Control.
|
* tcgetattr: (libc)Mode Functions.
|
* tcgetpgrp: (libc)Terminal Access Functions.
|
* tcgetsid: (libc)Terminal Access Functions.
|
* tcsendbreak: (libc)Line Control.
|
* tcsetattr: (libc)Mode Functions.
|
* tcsetpgrp: (libc)Terminal Access Functions.
|
* tdelete: (libc)Tree Search Function.
|
* tdestroy: (libc)Tree Search Function.
|
* telldir: (libc)Random Access Directory.
|
* tempnam: (libc)Temporary Files.
|
* textdomain: (libc)Locating gettext catalog.
|
* tfind: (libc)Tree Search Function.
|
* tgamma: (libc)Special Functions.
|
* tgammaf: (libc)Special Functions.
|
* tgammal: (libc)Special Functions.
|
* time: (libc)Simple Calendar Time.
|
* timegm: (libc)Broken-down Time.
|
* timelocal: (libc)Broken-down Time.
|
* times: (libc)Processor Time.
|
* tmpfile64: (libc)Temporary Files.
|
* tmpfile: (libc)Temporary Files.
|
* tmpnam: (libc)Temporary Files.
|
* tmpnam_r: (libc)Temporary Files.
|
* toascii: (libc)Case Conversion.
|
* tolower: (libc)Case Conversion.
|
* totalorder: (libc)FP Comparison Functions.
|
* totalorderf: (libc)FP Comparison Functions.
|
* totalorderl: (libc)FP Comparison Functions.
|
* totalordermag: (libc)FP Comparison Functions.
|
* totalordermagf: (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.
|
* truncl: (libc)Rounding Functions.
|
* tsearch: (libc)Tree Search Function.
|
* ttyname: (libc)Is It a Terminal.
|
* ttyname_r: (libc)Is It a Terminal.
|
* twalk: (libc)Tree Search Function.
|
* tzset: (libc)Time Zone Functions.
|
* ufromfp: (libc)Rounding Functions.
|
* ufromfpf: (libc)Rounding Functions.
|
* ufromfpl: (libc)Rounding Functions.
|
* ufromfpx: (libc)Rounding Functions.
|
* ufromfpxf: (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.
|
* 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.
|
* y0l: (libc)Special Functions.
|
* y1: (libc)Special Functions.
|
* y1f: (libc)Special Functions.
|
* y1l: (libc)Special Functions.
|
* yn: (libc)Special Functions.
|
* ynf: (libc)Special Functions.
|
* ynl: (libc)Special Functions.
|
END-INFO-DIR-ENTRY
|
|
|
File: libc.info, Node: Operating Modes, Next: Getting File Status Flags, Prev: Open-time Flags, Up: File Status Flags
|
|
13.14.3 I/O Operating Modes
|
---------------------------
|
|
The operating modes affect how input and output operations using a file
|
descriptor work. These flags are set by ‘open’ and can be fetched and
|
changed with ‘fcntl’.
|
|
-- Macro: int O_APPEND
|
The bit that enables append mode for the file. If set, then all
|
‘write’ operations write the data at the end of the file, extending
|
it, regardless of the current file position. This is the only
|
reliable way to append to a file. In append mode, you are
|
guaranteed that the data you write will always go to the current
|
end of the file, regardless of other processes writing to the file.
|
Conversely, if you simply set the file position to the end of file
|
and write, then another process can extend the file after you set
|
the file position but before you write, resulting in your data
|
appearing someplace before the real end of file.
|
|
-- Macro: int O_NONBLOCK
|
The bit that enables nonblocking mode for the file. If this bit is
|
set, ‘read’ requests on the file can return immediately with a
|
failure status if there is no input immediately available, instead
|
of blocking. Likewise, ‘write’ requests can also return
|
immediately with a failure status if the output can’t be written
|
immediately.
|
|
Note that the ‘O_NONBLOCK’ flag is overloaded as both an I/O
|
operating mode and a file name translation flag; *note Open-time
|
Flags::.
|
|
-- Macro: int O_NDELAY
|
This is an obsolete name for ‘O_NONBLOCK’, provided for
|
compatibility with BSD. It is not defined by the POSIX.1 standard.
|
|
The remaining operating modes are BSD and GNU extensions. They exist
|
only on some systems. On other systems, these macros are not defined.
|
|
-- Macro: int O_ASYNC
|
The bit that enables asynchronous input mode. If set, then ‘SIGIO’
|
signals will be generated when input is available. *Note Interrupt
|
Input::.
|
|
Asynchronous input mode is a BSD feature.
|
|
-- Macro: int O_FSYNC
|
The bit that enables synchronous writing for the file. If set,
|
each ‘write’ call will make sure the data is reliably stored on
|
disk before returning.
|
|
Synchronous writing is a BSD feature.
|
|
-- Macro: int O_SYNC
|
This is another name for ‘O_FSYNC’. They have the same value.
|
|
-- Macro: int O_NOATIME
|
If this bit is set, ‘read’ will not update the access time of the
|
file. *Note File Times::. This is used by programs that do
|
backups, so that backing a file up does not count as reading it.
|
Only the owner of the file or the superuser may use this bit.
|
|
This is a GNU extension.
|
|
|
File: libc.info, Node: Getting File Status Flags, Prev: Operating Modes, Up: File Status Flags
|
|
13.14.4 Getting and Setting File Status Flags
|
---------------------------------------------
|
|
The ‘fcntl’ function can fetch or change file status flags.
|
|
-- Macro: int F_GETFL
|
This macro is used as the COMMAND argument to ‘fcntl’, to read the
|
file status flags for the open file with descriptor FILEDES.
|
|
The normal return value from ‘fcntl’ with this command is a
|
nonnegative number which can be interpreted as the bitwise OR of
|
the individual flags. Since the file access modes are not
|
single-bit values, you can mask off other bits in the returned
|
flags with ‘O_ACCMODE’ to compare them.
|
|
In case of an error, ‘fcntl’ returns -1. The following ‘errno’
|
error conditions are defined for this command:
|
|
‘EBADF’
|
The FILEDES argument is invalid.
|
|
-- Macro: int F_SETFL
|
This macro is used as the COMMAND argument to ‘fcntl’, to set the
|
file status flags for the open file corresponding to the FILEDES
|
argument. This command requires a third ‘int’ argument to specify
|
the new flags, so the call looks like this:
|
|
fcntl (FILEDES, F_SETFL, NEW-FLAGS)
|
|
You can’t change the access mode for the file in this way; that is,
|
whether the file descriptor was opened for reading or writing.
|
|
The normal return value from ‘fcntl’ with this command is an
|
unspecified value other than -1, which indicates an error. The
|
error conditions are the same as for the ‘F_GETFL’ command.
|
|
If you want to modify the file status flags, you should get the
|
current flags with ‘F_GETFL’ and modify the value. Don’t assume that
|
the flags listed here are the only ones that are implemented; your
|
program may be run years from now and more flags may exist then. For
|
example, here is a function to set or clear the flag ‘O_NONBLOCK’
|
without altering any other flags:
|
|
/* Set the ‘O_NONBLOCK’ flag of DESC if VALUE is nonzero,
|
or clear the flag if VALUE is 0.
|
Return 0 on success, or -1 on error with ‘errno’ set. */
|
|
int
|
set_nonblock_flag (int desc, int value)
|
{
|
int oldflags = fcntl (desc, F_GETFL, 0);
|
/* If reading the flags failed, return error indication now. */
|
if (oldflags == -1)
|
return -1;
|
/* Set just the flag we want to set. */
|
if (value != 0)
|
oldflags |= O_NONBLOCK;
|
else
|
oldflags &= ~O_NONBLOCK;
|
/* Store modified flag word in the descriptor. */
|
return fcntl (desc, F_SETFL, oldflags);
|
}
|
|
|
File: libc.info, Node: File Locks, Next: Open File Description Locks, Prev: File Status Flags, Up: Low-Level I/O
|
|
13.15 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.16 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.17 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.18 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.19 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::.
|
|
This ‘get_current_dir_name’ function is basically equivalent to
|
‘getcwd (NULL, 0)’. The only difference is that the value of the
|
‘PWD’ variable is returned if this value is correct. This is a
|
subtle difference which is visible if the path described by the
|
‘PWD’ value is using one or more symbol links in which case the
|
value returned by ‘getcwd’ can resolve the symbol 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.
|
|
|
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.
|
|
-- 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-Unsafe race:dirstream | 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.
|
|
In POSIX.1-2008, ‘readdir’ is not thread-safe. In the GNU C
|
Library implementation, it is safe to call ‘readdir’ concurrently
|
on different DIRSTREAMs, but multiple threads accessing the same
|
DIRSTREAM result in undefined behavior. ‘readdir_r’ is a fully
|
thread-safe alternative, but suffers from poor portability (see
|
below). It is recommended that you use ‘readdir’, with external
|
locking if multiple threads access the same DIRSTREAM.
|
|
-- 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-Unsafe race:dirstream | 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, 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: 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.
|
|
|
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 password
|
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.
|
*Note Socket Addresses::.
|
|
‘struct in_addr sin_addr’
|
This is the Internet address of the host machine. *Note Host
|
Addresses::, and *note Host Names::, for how to get a value to
|
store here.
|
|
‘unsigned short int sin_port’
|
This is the port number. *Note Ports::.
|
|
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::.
|
|
‘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.
|
|
‘uint32_t sin6_flowinfo’
|
This is a currently unimplemented field.
|
|
‘uint16_t sin6_port’
|
This is the port number. *Note Ports::.
|
|
|
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.
|
